Récepteur OData dans SAP CPI : $select, $filter, $expand et $orderby sans fautes de frappe

L'adaptateur récepteur OData de SAP CPI transforme un Resource Path et une ligne d'options de requête en un appel à un service OData, par exemple une API SAP S/4HANA. Les options de requête déterminent quels champs, quelles lignes et quelles entités liées sont renvoyés, et un seul nom de propriété mal orthographié suffit pour que le service rejette l'appel.

Cet article passe en revue $select, $filter, $expand et $orderby sur un exemple, les différences entre OData V2 et V4 qui piègent souvent, et la façon de garder des noms corrects.

Où placer les options de requête dans le récepteur OData

Dans l'onglet Processing de l'adaptateur, vous choisissez l'opération, puis vous renseignez le Resource Path, c'est-à-dire l'entity set ou l'entité appelée, et les Query Options, soit tout ce qui suit le ? dans l'URL. L'assistant de requête de l'adaptateur peut générer les deux à partir des métadonnées du service, et il stocke ces métadonnées, le fichier EDMX, dans les ressources de l'iFlow.

Les options de requête peuvent contenir des expressions Simple, si bien que les valeurs peuvent venir du message, par exemple $filter=SoldToParty eq '${property.customerId}'. L'exemple ci-dessous lit des commandes clients avec leurs postes depuis API_SALES_ORDER_SRV, un service 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

Dans l'adaptateur, les options de requête tiennent sur une seule ligne ; elles ne sont découpées ici que pour la lisibilité.

Les quatre options, une par une

$top et $skip limitent et paginent le résultat. En OData V2, une propriété d'une entité étendue se sélectionne par un chemin, comme to_Item/Material, et la propriété de navigation doit aussi figurer dans $expand.

$filter a ses propres opérateurs : eq, ne, gt, ge, lt, le, combinés avec and, or et not. Les valeurs texte s'écrivent entre apostrophes, et les dates exigent la forme littérale attendue par la version du service.

OData V2 et V4 ne s'écrivent pas de la même façon

L'adaptateur OData prend en charge les deux versions, et de nombreuses API SAP existent dans les deux. Copier une requête d'une version à l'autre est une source d'erreurs fréquente :

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)

• Compter les lignes : $inlinecount=allpages en V2, $count=true en V4.
• Chercher dans un texte : substringof('Smith',CustomerName) en V2, contains(CustomerName,'Smith') en V4. Notez que les arguments sont dans l'ordre inverse.
• Dates : la V2 écrit datetime'2026-01-01T00:00:00' ; la V4 écrit la valeur sans préfixe.
• Propriétés étendues : la V2 les sélectionne par un chemin ; la V4 imbrique les options dans l'expand, comme dans $expand=_Item($select=Product,Quantity).

Les fautes de frappe qui provoquent un HTTP 400

Quand une option de requête est erronée, le service répond généralement par un HTTP 400 et nomme la partie qu'il n'a pas pu lire. Les erreurs en cause sont presque toujours les mêmes :

• Mauvaise casse : les noms OData sont sensibles à la casse, donc soldToParty n'est pas SoldToParty.
• Un entity set là où il faut une propriété de navigation : $expand=A_SalesOrderItem au lieu de $expand=to_Item.
• Une propriété qui existe sur une autre entité, ou seulement dans une autre version du service.
• Des apostrophes manquantes autour de valeurs texte, ou un littéral de date V2 envoyé à un service V4.
• Un problème de séparateur : les options sont reliées par &, et chaque nom d'option commence par $.

Les expressions ajoutent leur propre risque : si ${property.customerId} est vide, le filtre devient SoldToParty eq '' et ne renvoie discrètement aucune ligne au lieu d'une erreur. L'article sur les expressions Simple explique comment ces valeurs sont lues.

Garder la requête et le service synchronisés

• Considérez l'EDMX des ressources de l'iFlow comme la référence pour les noms, et actualisez-le quand le service change.
• Ne sélectionnez que les champs que vous mappez ; une réponse plus petite est plus rapide et plus lisible dans une trace.
• Pour les lectures volumineuses, utilisez l'option de l'adaptateur qui traite par pages plutôt qu'en une seule énorme réponse.
• Testez la requête une fois avec les valeurs exactes qu'un vrai message y placera.

Vous appelez une API REST plutôt qu'un service OData ? L'article sur Postman et OpenAPI traite du récepteur HTTP.

Ce qu'apporte Kitegra

L'extension de navigateur Kitegra lit l'EDMX que votre iFlow contient déjà pour un canal récepteur OData. Dans le designer, elle suggère à partir de cet EDMX le Resource Path ainsi que les noms de propriétés et de navigation pour $select, $filter, $expand et $orderby : vous choisissez les noms au lieu de les taper.

Son panneau de lint signale les noms OData absents de l'EDMX, ainsi que les ${ non fermés et les headers ou propriétés que rien ne définit. Si un canal ne reçoit aucune suggestion, vérifiez que son EDMX figure dans les ressources de l'iFlow. L'extension n'enregistre, ne déploie et ne modifie jamais le contenu d'un iFlow, et votre tenant ne change que lorsque vous cliquez sur l'une de quatre actions nommées, qui peuvent être désactivées.

Pour vérifier ce que le service OData a réellement répondu, tracez le message étape par étape et lisez le body après l'appel.

Sans compte Kitegra, elle fonctionne sur 5 iFlows par module. Le forfait Free en couvre 50, Starter 100 et Pro 300 ; Business n'a pas de limite. Comparez les forfaits.

Essayez-le dans votre prochain iFlow

Découvrez ce que fait Kitegra dans le designer de SAP Integration Suite, ou voyez-le aux côtés des autres extensions Chrome de Kitegra.

Questions fréquentes