Using the OData Service for Extracting ODP Data

An OData client can consume the service for extracting ODP data via URLs and request the resources of the data model. Here standard OData requests and the OData standard syntax is used.

Basic URL structure for extracting ODP data

http://<Host>:<Port>/sap/opu/odata/SAP/<Service Name>/<Entity Set Name>/<Query Options>

URL structure for accessing the model metadata of the service

http://<Host>:<Port>/sap/opu/odata/SAP/<Service Name>/$metadata

The OData service can expose its entity model and its structure via a URL. Information is displayed about the entity sets and their structures (entity types). SAP-specific enhancements allow ODPs (sap:aggregation-role="dimension" or "measure") to access semantics, for example. You can find an overview of these enhancements on the SAP Community Network on http://scn.sap.com/docs/DOC-44986 Information published on SAP site .

OData query options for data extraction

Using standard OData query options you can specify the data you want to extract in more detail:

System query options	Description of the use case
$select For example, $select=field1,field2,...	Using this option you can express a projection for which fields you want to request.
$filter For example, $filter=field3 eq <value> and …	With this option you can use Boolean operators to express which entries or records you want to request.
$inlinecount For example, inlinecount=allpages	With this option you can output the total number of entries to be extracted.
$top For example, $top=<N>	Using this option you can restrict the entries to be extracted to the first N entries. This option is only used for the preview. Note The preview is implemented via direct access without packaging and without using the operational delta queue.
$skip For example, $skip=<M>	Using this option you can specify that extraction should start from entry M. This option is only used for the preview. Note The preview is implemented via direct access without packaging and without using the operational delta queue.
$format For example, $format=xlsx	Using this option you can specify the output format for extraction, for example json, xml or xlsx.

System query options

Description of the use case

$select

For example, $select=field1,field2,...

Using this option you can express a projection for which fields you want to request.

$filter

For example, $filter=field3 eq <value> and …

With this option you can use Boolean operators to express which entries or records you want to request.

$inlinecount

For example, inlinecount=allpages

With this option you can output the total number of entries to be extracted.

$top

For example, $top=<N>

Using this option you can restrict the entries to be extracted to the first N entries.

This option is only used for the preview.

Note

The preview is implemented via direct access without packaging and without using the operational delta queue.

$skip

For example, $skip=<M>

Using this option you can specify that extraction should start from entry M.

This option is only used for the preview.

Note

The preview is implemented via direct access without packaging and without using the operational delta queue.

$format

For example, $format=xlsx

Using this option you can specify the output format for extraction, for example json, xml or xlsx.

A URL for facts could look something like this:

http://<Host>:<Port>/sap/opu/odata/sap/<Service Name>/FactsOfZXYFADSO01?$ select=AIRLINEID,FLIGHTDATE,BOOKDATE,CALDAY,CONNECTID,CANCELLED,RECORDMODE,BOOKINGID,CUSTOMERID,CLASS,LUGGWEIGHT,PRICELOCAL,CURRENCY&$filter=FLIGHTDATE ge datetime ' 2010-01-01T00:00:00' &$top=100&$format= xlsx

If the service also contains master data, the master data can be accessed via the corresponding URLs, for example:

http://<Host>:<Port>/sap/opu/odata/sap/<Service Name>/AttrOf0AIRLINEID?$top=20&$format=xlsx
http://<Host>:<Port>/sap/opu/odata/sap/<Service Name>/TextsOf0AIRLINEID?$top=20&$format=xlsx

Using the request header Prefer for data extraction

To control a full extraction or delta extraction, the URL can be called on the corresponding entity set, which represents the ODP, by using the following request header values (standard OData):

Extraction with paging:

If you want the ODP data in packages to be retrieved, you can do this via paging by using the following header:

Header Name

Header Value

Prefer

odata.maxpagesize=<N>

For example, odata.maxpagesize=50

A background job is started for paging and the data is cached in the operational delta queue. Using the odata.maxpagesize value you can specify the quantity of packages to be retrieved from the delta queue. The end of the response contains a relative link, which can be used to retrieve the next package.
Delta extraction:

Delta extraction can be performed using the following request header value:

Header Name

Header Value

Prefer

odata.track-changes

The OData service can access the ODP data in delta mode for a delta-enabled operational data provider (ODP). When odata.track-changes is used, there is a differentiation between delta extraction and full extraction. When this value is called for the first time, a delta initialization is performed that can also be performed by package. Once the initialization is complete, the end of the response of a request in delta mode contains a relative link to the next delta query (delta link). This can be used with the next HTTP request, in order to retrieve data, which has been changed since the delta link was created.

Note that deltas are always returned with a reference to the user used by the OData client to log on to the OData service.

Header Name	Header Value
Prefer	`odata.maxpagesize=<N>` For example, `odata.maxpagesize=50`

Header Name	Header Value
Prefer	`odata.track-changes`

Note

You can combine paging and delta extraction, by listing both header values separated by commas, for example odata.maxpagesize=50,odata.track-changes.

There are two additional functions available (via function imports) as a service for delta management:

To determine whether a delta subscription exists: http://<Host>:<Port>/sap/opu/odata/sap/<Service Name>/SubscribedToFactsOf<ODP Name>

The response returns the information SubscribedFlag equals true or false. Note that the OData service name and the the name of the user logged on to the OData service must be used, in order to determine whether a delta subscription exists. This means that a user of an ODP, which is provided via various services, can have multiple subscriptions.
To log off delta extraction: http://<Host>:<Port>/sap/opu/odata/sap/<Service Name>/TerminateDeltasForFactsOf<ODP Name>

The response returns the information ResultFlag equals true or false.

Displaying the delta history and extracting data, which has been changed since a specific delta (restore)

With entity sets that can retrieve data in delta mode from the source, the changes made since the last delta link are retrieved in delta mode. However, there may also be a history of available delta links that can be displayed and used to restore the data changed since a specific delta link, if an error occurs. The help entity set DeltaLinksOf<EntitySet> is available to you here; <EntitySet> is the name of the delta-enabled entity set, for which you want to retrieve the changed data.

Displaying the delta history

You can open a history of the delta links for entity set ZXYFADSO01 via the following URL, for example:

http://<Host>:<Port>/sap/opu/odata/sap/<Service-Name>/DeltaLinksOfFactsOfZXYFADSO01

The following properties are displayed for every delta link:

Property	Meaning
DeltaToken	Returns an ID for the delta.
CreatedAt	Specifies when the data changed since the last delta link was retrieved when the current delta link was created.
IsInitialLoad	Specifies if the delta link belongs to a delta initalization (= `true`) or to a delta (= `false`).

If you only want to view deltas from a specific point in time in the history, you can filter by CreatedAt using the comparison operators "greater than" and "greater than or equal to", for example:

http://<Host>:<Port>/sap/opu/odata/sap/<Service-Name>/DeltaLinksOfFactsOfZXYFADSO01?$filter=DataAfter gt datetime'2015-10-02T11:54:22'

Accessing data that have been changed since a specific delta link

Data that have been changed since a specific delta link is accessed via the navigation ChangesAfter. The navigation is executed for an entry of the entity set DeltaLinksOf<EntitySet>. For example, for entity set ZXYFADSO01 with a delta link entry with DeltaToken D20151001131537_000052000, the URL is:

http://<Host>:<Port>/sap/opu/odata/sap/<Service-Name>/DeltaLinksOfFactsOfZXYFADSO01('D20151001131537_000052000')/ChangesAfter

Requirements for the OData client

Some ODP contexts such as BW and SAPI supports the extraction of data changes. The way in which data changes are transferred for a source (for example, BW DataSource) is specified in the delta procedure. In order to be able to receive deltas, the client must fulfill the following requirements:

It must be able to give HTTP header fields to the OData request.
It must know what a delta link. Information about support for deltas can be found in the SAP Gateway Foundation Developer Guide, section Delta Query Support.
It must understand the delta procedures of the extraction sources.

A central feature of delta procedures is record mode. This mode describes how a record needs to be updated in the delta procedures (which image is used, for example: before image, after image or reverse image). A delta procedure is made up of a subset of this information. This information is contained in table RODELTAM - the central storage of the delta procedure properties.

In order to correctly receive deltas, the developer of the OData client must understand which delta procedure is used with images of a source. The developer must understand what type of data is receives when he/she uses the delta link. In other words, he must know which images are returned by the records. He must also understand field ODQ_ENTITIYCNTR, which provides the change behavior of an ODP by using ODQ_CHANGEMODE.

Otherwise the query will run via standard OData.