Receiver OData in SAP CPI: $select, $filter, $expand e $orderby senza errori di battitura

L'adapter receiver OData di SAP CPI trasforma un Resource Path e una riga di query option in una chiamata a un servizio OData, come un'API di SAP S/4HANA. Le query option decidono quali campi, righe ed entità correlate vengono restituiti, e basta un nome di proprietà scritto male perché il servizio rifiuti la chiamata.

Questo articolo esamina $select, $filter, $expand e $orderby su un esempio, le differenze tra OData V2 e V4 che spesso traggono in inganno, e come mantenere i nomi corretti.

Dove vanno le query option nel receiver OData

Nella scheda Processing dell'adapter scegli l'operazione, poi imposti il Resource Path, cioè l'entity set o l'entità che chiami, e le Query Options, cioè tutto ciò che segue il ? nell'URL. Il wizard di query dell'adapter può costruirli entrambi dai metadati del servizio e salva quei metadati, il file EDMX, tra le risorse dell'iFlow.

Le query option possono contenere espressioni Simple, quindi i valori possono arrivare dal messaggio, per esempio $filter=SoldToParty eq '${property.customerId}'. L'esempio seguente legge gli ordini di vendita con le loro posizioni da API_SALES_ORDER_SRV, un servizio 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

Nell'adapter le query option stanno su una sola riga; qui sono divise solo per renderle leggibili.

Le quattro opzioni, una per una

$top e $skip limitano e paginano il risultato. In OData V2, una proprietà di un'entità espansa si seleziona con un percorso, come in to_Item/Material, e la navigation property deve comparire anche in $expand.

$filter ha i suoi operatori: eq, ne, gt, ge, lt, le, combinati con and, or e not. I valori di testo vanno tra apici singoli, e le date richiedono la forma letterale prevista dalla versione del servizio.

OData V2 e V4 non si scrivono allo stesso modo

L'adapter OData supporta entrambe le versioni, e molte API SAP esistono in tutte e due. Copiare una query da una versione all'altra è una fonte frequente di errori:

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)

• Contare le righe: $inlinecount=allpages in V2, $count=true in V4.
• Cercare all'interno di un testo: substringof('Smith',CustomerName) in V2, contains(CustomerName,'Smith') in V4. Nota che gli argomenti sono in ordine inverso.
• Date: V2 scrive datetime'2026-01-01T00:00:00'; V4 scrive il valore senza prefisso.
• Proprietà espanse: V2 le seleziona con un percorso; V4 annida le opzioni dentro l'expand, come in $expand=_Item($select=Product,Quantity).

Gli errori di battitura che causano HTTP 400

Quando una query option è sbagliata, il servizio di solito risponde con HTTP 400 e indica la parte che non è riuscito a leggere. Gli errori dietro sono quasi sempre gli stessi:

• Maiuscole e minuscole sbagliate: i nomi OData le distinguono, quindi soldToParty non è SoldToParty.
• Un entity set al posto di una navigation property: $expand=A_SalesOrderItem invece di $expand=to_Item.
• Una proprietà che esiste su un'altra entità, o solo in un'altra versione del servizio.
• Apici mancanti attorno ai valori di testo, o un letterale di data V2 inviato a un servizio V4.
• Un problema di separatori: le opzioni si uniscono con &, e ogni nome di opzione inizia con $.

Le espressioni aggiungono un rischio in più: se ${property.customerId} è vuoto, il filtro diventa SoldToParty eq '' e non restituisce nessuna riga in silenzio, invece di dare un errore. L'articolo sulle espressioni Simple spiega come vengono letti quei valori.

Mantieni query e servizio allineati

• Considera l'EDMX tra le risorse dell'iFlow la fonte di verità per i nomi, e aggiornalo quando il servizio cambia.
• Seleziona solo i campi che mappi; una risposta più piccola è più veloce e più facile da leggere in un trace.
• Per letture grandi, usa l'opzione dell'adapter per elaborare a pagine invece di un'unica risposta enorme.
• Prova la query una volta con i valori esatti che ci metterà un messaggio reale.

Devi chiamare un'API REST invece di un servizio OData? L'articolo su Postman e OpenAPI tratta il receiver HTTP.

Come aiuta Kitegra

L'estensione del browser Kitegra legge l'EDMX che il tuo iFlow contiene già per un canale receiver OData. Nel designer suggerisce il Resource Path e i nomi di proprietà e di navigazione per $select, $filter, $expand e $orderby a partire da quell'EDMX, così scegli i nomi invece di digitarli.

Il suo pannello di lint segnala i nomi OData che l'EDMX non contiene, insieme a ${ non chiusi e header o proprietà che nulla imposta. Se un canale non riceve suggerimenti, verifica che il suo EDMX sia tra le risorse dell'iFlow. L'estensione non salva, non esegue il deploy e non modifica mai il contenuto di un iFlow, e il tuo tenant cambia solo quando fai clic su una di quattro azioni ben precise, che si possono disattivare.

Per verificare cosa ha risposto davvero il servizio OData, traccia il messaggio step by step e leggi il body dopo la chiamata.

Senza un account Kitegra funziona su 5 iFlow per modulo. Il piano Free ne copre 50, Starter 100 e Pro 300; Business non ha limiti. Confronta i piani.

Provalo nel tuo prossimo iFlow

Scopri cosa fa Kitegra nel designer di SAP Integration Suite, oppure guardalo accanto alle altre estensioni Chrome di Kitegra.

Domande frequenti