Receptor OData no SAP CPI: $select, $filter, $expand e $orderby sem erros de digitação

O adaptador receptor OData do SAP CPI transforma um Resource Path e uma linha de opções de consulta em uma chamada a um serviço OData, como uma API do SAP S/4HANA. As opções de consulta decidem quais campos, linhas e entidades relacionadas voltam, e um único nome de propriedade digitado errado basta para o serviço rejeitar a chamada.

Este artigo percorre $select, $filter, $expand e $orderby com um exemplo, as diferenças entre OData V2 e V4 que confundem muita gente, e como manter os nomes corretos.

Onde ficam as opções de consulta no receptor OData

Na aba Processing do adaptador, você escolhe a operação e depois define o Resource Path, que é o entity set ou a entidade chamada, e as Query Options, que são tudo o que vem depois do ? na URL. O assistente de consulta do adaptador consegue montar os dois a partir dos metadados do serviço e guarda esses metadados, o arquivo EDMX, nos recursos do iFlow.

As opções de consulta podem conter expressões Simple, então os valores podem vir da mensagem, por exemplo $filter=SoldToParty eq '${property.customerId}'. O exemplo abaixo lê ordens de venda com seus itens de API_SALES_ORDER_SRV, um serviço OData V2:

Resource Path:  A_SalesOrder
Query Options:  $select=SalesOrder,SoldToParty,CreationDate,to_Item/SalesOrderItem,to_Item/Material
                &$expand=to_Item
                &$filter=SoldToParty eq '${property.customerId}' and CreationDate ge datetime'2026-01-01T00:00:00'
                &$orderby=CreationDate desc
                &$top=50

No adaptador, as opções de consulta ficam em uma única linha; aqui elas foram quebradas apenas para facilitar a leitura.

As quatro opções, uma a uma

$top e $skip limitam e paginam o resultado. No OData V2, uma propriedade de uma entidade expandida é selecionada com um caminho, como em to_Item/Material, e a propriedade de navegação também precisa estar em $expand.

$filter tem operadores próprios: eq, ne, gt, ge, lt, le, combinados com and, or e not. Valores de texto vão entre aspas simples, e datas precisam do formato literal que a versão do serviço espera.

OData V2 e V4 não se escrevem do mesmo jeito

O adaptador OData suporta as duas versões, e muitas APIs SAP existem nas duas. Copiar uma consulta de uma versão para a outra é uma fonte comum de erros:

OData V2:  $inlinecount=allpages
           $filter=substringof('Smith',CustomerName)
           $filter=CreationDate ge datetime'2026-01-01T00:00:00'

OData V4:  $count=true
           $filter=contains(CustomerName,'Smith')
           $filter=CreatedAt ge 2026-01-01T00:00:00Z
           $expand=_Item($select=Product,Quantity)

• Contar linhas: $inlinecount=allpages no V2, $count=true no V4.
• Buscar dentro de um texto: substringof('Smith',CustomerName) no V2, contains(CustomerName,'Smith') no V4. Repare que os argumentos ficam em ordem inversa.
• Datas: o V2 escreve datetime'2026-01-01T00:00:00'; o V4 escreve o valor sem prefixo.
• Propriedades expandidas: o V2 as seleciona com um caminho; o V4 aninha as opções dentro do expand, como em $expand=_Item($select=Product,Quantity).

Os erros de digitação que causam HTTP 400

Quando uma opção de consulta está errada, o serviço costuma responder com HTTP 400 e indicar a parte que não conseguiu ler. Os erros por trás disso são quase sempre os mesmos:

• Maiúsculas e minúsculas erradas: nomes OData as diferenciam, então soldToParty não é SoldToParty.
• Um entity set no lugar de uma propriedade de navegação: $expand=A_SalesOrderItem em vez de $expand=to_Item.
• Uma propriedade que existe em outra entidade, ou só em outra versão do serviço.
• Aspas faltando em valores de texto, ou um literal de data do V2 enviado a um serviço V4.
• Um problema de separador: as opções são unidas com &, e todo nome de opção começa com $.

Expressões trazem um risco próprio: se ${property.customerId} estiver vazio, o filtro vira SoldToParty eq '' e não retorna nenhuma linha, em silêncio, em vez de dar erro. O artigo sobre expressões Simple explica como esses valores são lidos.

Mantenha a consulta e o serviço em sincronia

• Trate o EDMX nos recursos do iFlow como a fonte da verdade para os nomes, e atualize-o quando o serviço mudar.
• Selecione só os campos que você mapeia; uma resposta menor é mais rápida e mais fácil de ler em um trace.
• Para leituras grandes, use a opção do adaptador de processar em páginas, em vez de uma única resposta enorme.
• Teste a consulta uma vez com os valores exatos que uma mensagem real vai colocar nela.

Vai chamar uma API REST em vez de um serviço OData? O artigo sobre Postman e OpenAPI cobre o receptor HTTP.

Como o Kitegra ajuda

A extensão de navegador Kitegra lê o EDMX que o seu iFlow já guarda para um canal receptor OData. No designer, ela sugere o Resource Path e os nomes de propriedades e de navegação para $select, $filter, $expand e $orderby a partir desse EDMX, então você escolhe os nomes em vez de digitá-los.

O painel de lint aponta nomes OData que não estão no EDMX, além de ${ não fechados e headers ou propriedades que nada define. Se um canal não recebe sugestões, confira se o EDMX dele está nos recursos do iFlow. A extensão nunca salva, implanta nem edita o conteúdo de um iFlow, e o seu tenant só muda quando você clica em uma de quatro ações nomeadas, que podem ser desativadas.

Para conferir o que o serviço OData realmente respondeu, rastreie a mensagem passo a passo e leia o corpo depois da chamada.

Sem uma conta Kitegra, ela funciona em 5 iFlows por módulo. O plano Free cobre 50, o Starter 100 e o Pro 300; o Business não tem limite. Compare os planos.

Experimente no seu próximo iFlow

Veja o que o Kitegra faz no designer do SAP Integration Suite, ou confira-o ao lado das outras extensões do Chrome da Kitegra.

Perguntas frequentes