Introduction
In my previous blog post Consuming Gateway OData service with OData adapter, I introduced the usage of the OData adapter in consuming a NetWeaver Gateway OData service.
As I dive deeper into using the OData adapter, I found several OData-related capability of the adapter that is neither mentioned in the OData Channel Configuration Guide, or any other SAP Community content.
For those who would like to try out this adapter, here are some of my findings that might help you utilise more capabilities of the adapter in your own integrations.
OData Expand System Query Option ($expand)
Unlike the "free-style" schema definition of SOAP-based web services, OData modelling is based on Entity Sets, and the relationships between them. Generally, Entity Set structures are flat in nature so if a deep structure is required within a single response, we might need to query an entity set and its related entity sets.
The $expand option (mentioned in section 4.6 of URI Conventions (OData Version 2.0)) allows the return of an entity set together with additional specified related entity set(s).
The OData adapter supports such usage from design, configuration and runtime perspectives. Let's use the publicly available Northwind OData V2 service as an example. For this service, the Entity Set Products is related to Categories and Suppliers.
Using the HCI Operations Modeler, we can generate the ESR schema for this by selecting the Entity Set and increasing the sub level. In the next screen, the related entity sets and their properties can be selected.
| Entity Set selection | Property and Related Entity Sets selection |
 |  |
Once the schema is generated and uploaded to ESR, the relationships and deep structure can be viewed.
In the channel configuration, the $expand option can be configured in the Resource Path as follows:-
<MainEntitySet>?$expand=<CommaSeparatedValueOfRelatedEntities>
i.e. Products?$expand=Category,Supplier
When end-to-end testing is executed, we can see that the related Entities are included inline in the response as a deep structure.
OData Skip Token System Query Option ($skiptoken)
One of the key considerations when designing synchronous services is the size of the payload. It is no different for OData services, where it uses pagination when there are too many records to return. This is typically handled by a combination of the $top and $skip options.
An alternative approach is by using the $skiptoken option (mentioned here), which returns a "bookmark" to be used for the next call to the service. This allows the caller to return to the last point of the previous call and continue from there.
It was an interesting discovery to find that the $skiptoken functionality is automatically handled by the adapter. This meant that the adapter will determine if there is a skip token returned in a call, and automatically use the value in the next call until all the records are returned (i.e. no more skip token in the final call). The adapter then merges all the responses from all the calls and returns it as a single response to the calling application.
In order to test this functionality, the NetWeaver Gateway OData service was designed to return a skip token when there were more records to be retrieved. Note that the skip token can be of any arbitrary string value, and it is up to the OData logic to generate and interpret it.
When the traffic from the OData adapter is routed to Fiddler for analysis, the trace shows that there were multiple calls to the OData service.
For each of the call, the PI message ID is dynamically retrieved during mapping and populated as one of the values in the $filter option. This helps us to confirm that indeed the OData adapter is making all the calls from a single PI message. In the response section of the first call, we can see $skiptoken=1 is returned by the service.
In the subsequent call, the OData adapter automatically adds $skiptoken=1 as a parameter in the call. In this call, again the service returns a skip token with a new "bookmark" value.
After a few calls, in the final call (with $skiptoken=4), all the records are retrieved and the service no longer returns any skip token value.
Within PI's Message Monitor, only a single PI Message ID pair (request and response) can be seen instead of the multiple calls made by the OData adapter.
Finally, on the calling application side, we can view the response from PI adapter which merges all the calls into a single response.
- SAP Managed Tags:
6 Comments
