$batch Processing
Clients can search for and change resources exposed by a data service in a way that each request type maps to a single HTTP request/response exchange. As these request types are based on HTTP, the usual HTTP services are also available, such as caching. In this context clients of a data service can collect or "batch up" several requests and then send that batch to the data service in a single HTTP request.
Batch Request
An OData batch request is represented as a multipart MIME v1.0 message (see
RFC2046 under http://www.rfc-editor.org/rfc/rfc2046.txt
), a
standard format allowing the representation of multiple parts, each of which may have
a different content type, within a single request.
Batch requests allow grouping of multiple operations (as described in OData:
Operations under http://www.odata.org/documentation/operations)
into a single HTTP request payload.
Batch requests are submitted as a single HTTP POST request to the
$batch endpoint of a service as described
in OData: URI Conventions under http://www.odata.org/documentation/uri-conventions.
The body of a batch request is made up of an ordered series of retrieve operations and/or change sets. A change set is an atomic unit of work that is made up of an unordered group of one or more of the insert, update or delete operations. Change sets cannot contain retrieve requests and cannot be nested, that is, a change set cannot contain a change set.
In the batch request body, each retrieve request and change set is represented as a distinct MIME part and is separated by the boundary marker defined in the Content-Type header of the request. The contents of the MIME part which represents a change set is itself a multipart MIME document with one part for each operation that makes up the change set.
Each MIME part representing a retrieve request or change set within the batch includes both Content-Type and Content-Transfer-Encoding MIME headers as seen in the examples below. The batch request boundary is the name specified in the Content-Type Header for the batch.
For more information, see http://www.odata.org/documentation/operations.
Batch Response
The batch response contains a Content-Type header specifying a content type of multipart/mixed and a batch boundary specification, which may be different from the batch boundary that was used in the corresponding request.
Within the body of the batch response is a response for each retrieve request and change set that was in the associated batch request. The order of responses in the response body must match the order of requests in the batch request. Each response includes a Content-Type header with a value of application/http, and a Content-Transfer-Encoding MIME header with a value of binary.
A response to a retrieve request is formatted exactly as it would have appeared outside of a batch.
The body of a change set response is either a response for all the successfully processed change request within the change set, formatted exactly as it would have appeared outside of a batch, or a single response indicating a failure of the entire change set.
For more information, see http://www.odata.org/documentation/operations.
Custom header ($batch response header) is supported for $batch requests.
A selection of generic HTTP headers for $batch requests are available for the data provider when processing each $batch operation.
Performance improvement for $batch change-set processing when the data providers is able to handle the entire operation of change set at once at end of change set: For this to be possible the data provider must implement the change set handling API to process all change set operations within one API (CHANGESET_PROCESS) and return the consolidated result of all operations to the SAP Gateway framework.
This handling is also called processing a change set in defer mode.
When method CHANGESET_BEGIN is called a data provider can use the changing parameter CV_DEFER_MODE to inform the framework that it can process all change set operations at once (deferred processing). Based on the list of entity set name, entity type name and action name, a data provider can dynamically set the exporting parameter mentioned above to inform the framework that it will process the current change set at once or to reset this parameter to have a single processing as usual. Default implementation is single processing. That means without any changes in a data provider each change set operation will be processed one after another as usual.
If CV_DEFER_MODE is set, the framework will call the data provider using the new method CHANGESET_PROCESS with importing parameter IT_CHANGESET_REQUEST containing a list of change set operations. Each entry of this list contains the technical request context IO_TECH_REQUEST_CONTEXT as usual but also a message container for error or information message happened during the processing. Response data of a change set operation including HTTP custom headers and ETag (if it exists) must be returned in changing parameter CT_CHANGESET_RESPONSE.
At the end of a change set the framework will call method CHANHGESET_END as usual.
All retrieve operations and change sets of $batch requests are transferred at once from the SAP Gateway hub system to the backend system for processing.
All consecutive retrieve operations (until a change set) are processed in parallel to improve performance. You can use the implementation guide (IMG) to activate or deactivate the parallelization. See also Define Parallelization of Batch Queries.
Each retrieve operation such as Read Entry or Read Feed within a $batch request will be transferred separately from the SAP Gateway hub system to the provider application in the backend system for processing.
Every change set is treated as one Logical Unit of Work (LUW), ensuring its "all or nothing" character. All operations of a change set will be sent at once from the SAP Gateway hub system to the provider application in the backend system for processing.
Results of all operations will be collected at the SAP Gateway hub system and sent as one HTTP response to the OData consumer.
If you have several operations in a change set one operation can refer to another operation by using content ID referencing, rather than using the key of an entity type instance which may not be known at that time. To define a content ID for a specific operation the following syntax needs to be used in the $batch request body: Content-ID: n where n is a string selected by the application.
To define a reference to a content ID for a specific operation the following syntax needs to be used in the $batch request body: $n where n is an existing content ID that was defined for another operation from the same change set.
Content ID referencing is supported only for change sets at once (defer mode). As described above in case of “change set at once” method CHANGESET_PROCESS is called with importing parameter IT_CHANGESET_REQUEST containing a list of change set operations. The importing parameter IT_CHANGESET_REQUEST also contains information about content IDs and content ID references (fields content_id and content_id_ref).
There is a specific business scenario with sales orders, and each sales order can have multiple sales order items. When creating sales orders a sales order ID is generated by the backend. When creating sales order items a sales order id needs to be provided. You want to create a change set with two operations:
-
Operation: create sales order
-
Operation: create sales order item
This demo business scenario has been implemented in demo service GWSAMPLE_BASIC and can be tested using the following URL and payload:
https://<host>:<port>/sap/opu/odata/IWBEP/GWSAMPLE_BASIC/$batch --batch_005056A5-09B1-1ED1-BF82-409B26A80300 Content-Type: multipart/mixed; boundary=changeset_005056A5-09B1-1ED1-BF82-409B26A80301 --changeset_005056A5-09B1-1ED1-BF82-409B26A80301 Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: 100 POST SalesOrderSet HTTP/1.1 Content-Type: application/atom+xml Content-Length: 1021 <atom:entry xmlns:atom="http://www.w3.org/2005/Atom"> <atom:content type="application/xml"> <m:properties xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"> <d:SalesOrderID></d:SalesOrderID> <d:Note>Deliver as fast as possible</d:Note> <d:NoteLanguage>EN</d:NoteLanguage> <d:CustomerID>0100000000</d:CustomerID> <d:CustomerName>SAP</d:CustomerName> <d:CurrencyCode>EUR</d:CurrencyCode> <d:GrossAmount>25867.03</d:GrossAmount> <d:NetAmount>21737.00</d:NetAmount> <d:TaxAmount>4130.03</d:TaxAmount> <d:LifecycleStatus>N</d:LifecycleStatus> <d:LifecycleStatusDescription>New</d:LifecycleStatusDescription> <d:BillingStatus/> <d:BillingStatusDescription>Initial</d:BillingStatusDescription> <d:DeliveryStatus/> <d:DeliveryStatusDescription>Initial</d:DeliveryStatusDescription> <d:CreatedAt>2015-03-22T23:00:00.0000000</d:CreatedAt> <d:ChangedAt>2015-03-22T23:00:00.0000000</d:ChangedAt> </m:properties> </atom:content> </atom:entry> --changeset_005056A5-09B1-1ED1-BF82-409B26A80301 Content-Type: application/http Content-Transfer-Encoding: binary POST $100/ToLineItems HTTP/1.1 Content-Type: application/atom+xml Content-Length: 1021 <atom:entry xmlns:atom="http://www.w3.org/2005/Atom"> <atom:content type="application/xml"> <m:properties xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"> <d:SalesOrderID></d:SalesOrderID> <d:ItemPosition></d:ItemPosition> <d:ProductID>HT-1001</d:ProductID> <d:Note>EPM DG: SO ID 0500000000 Item 0000000020</d:Note> <d:NoteLanguage>EN</d:NoteLanguage> <d:CurrencyCode>EUR</d:CurrencyCode><d:GrossAmount>2972.62</d:GrossAmount> <d:NetAmount>2498.00</d:NetAmount> <d:TaxAmount>474.62</d:TaxAmount> <d:DeliveryDate>2015-03-29T22:00:00.0000000</d:DeliveryDate> <d:Quantity>2</d:Quantity> <d:QuantityUnit>EA</d:QuantityUnit> </m:properties> </atom:content> </atom:entry> --changeset_005056A5-09B1-1ED1-BF82-409B26A80301-- --batch_005056A5-09B1-1ED1-BF82-409B26A80300--
For retrieve operations there is no special handling required. But to ensure the "all or nothing" character of a change set there are two additional methods for change set handling in interface /IWBEP/IF_MGW_APPL_SRV_RUNTIME:
-
/IWBEP/IF_MGW_APPL_SRV_RUNTIME~CHANGESET_BEGIN
All operations within a change set must be treated as a logical unit of work. This means all or nothing. Therefore, a provider must not issue COMMIT WORK or ROLLBACK WORK during change set processing. Otherwise, the framework will abandon the change set processing. If the change set contains only one operation, the check of commit or rollback is deactivated.
At the beginning of a change set processing, the provider will be called with this method. It can check the list of all involved entity types and actions contained in this change set and accept the change set handling or reject it by raising a technical exception with exception code CHANGESET_NOT_SUPPORTED. The method has a default implementation which allows only one operation per change set in order to guarantee transactional consistency. If more than one operation is required in a change set the implementation has to be overwritten by the application. The application then needs to ensure transactional consistency, for example not to have any commit or rollback in the chain of requests in a change set.
Additionally, the provider can start collecting the content of a change set in the modifying method calls, for example update entity, and finalize it within the CHANGESET_END method call described below.
-
/IWBEP/IF_MGW_APPL_SRV_RUNTIME~CHANGESET_END
If the provider only updates all modifications of a change set in internal tables, it can now update the database. A COMMIT WORK will be issued by the framework at the end of this API.
For more information on the API see the method documentation for CHANGESET_BEGIN and CHANGESET_END of /IWBEP/IF_MGW_APPL_SRV_RUNTIME.
For more information on OData operations, see
http://www.odata.org/documentation/operations.