SPHttpClientBatch class
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
The SPHttpClientBatch class accumulates a number of REST service calls and transmits them as a single ODATA batch. This protocol is documented here: http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html
The usage is to call SPHttpClientBatch.fetch() to queue each individual request, and then call SPHttpClientBatch.execute() to execute the batch operation. The execute() method returns a promise that resolves when the real REST call has completed. Each call to fetch() also returns a promise that will resolve with an SPHttpClientResponse object for that particular request.
Remarks
The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the SPHttpClientBatch class.
Properties
| configurations | The standard predefined SPHttpClientBatchConfigurations objects for use with the SPHttpClientBatch class. |
Methods
| execute() | Executes the batched queries that were queued using SPHttpClientBatch.fetch(). |
| fetch(url, configuration, options) | Queues a new request, and returns a promise that can be used to access the server response (after execute() has completed). |
| get(url, configuration, options) | Calls fetch(), but sets the method to 'GET'. |
| post(url, configuration, options) | Calls fetch(), but sets the method to 'POST'. |
Property Details
configurations
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
The standard predefined SPHttpClientBatchConfigurations objects for use with the SPHttpClientBatch class.
static readonly configurations: ISPHttpClientBatchConfigurations;Property Value
Method Details
execute()
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Executes the batched queries that were queued using SPHttpClientBatch.fetch().
execute(): Promise<SPHttpClientBatch>;Returns
Promise<SPHttpClientBatch>
fetch(url, configuration, options)
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Queues a new request, and returns a promise that can be used to access the server response (after execute() has completed).
fetch(url: string, configuration: SPHttpClientBatchConfiguration, options?: ISPHttpClientBatchOptions): Promise<SPHttpClientResponse>;Parameters
- url
-
string
the URL to fetch
- configuration
- SPHttpClientBatchConfiguration
determines the default behavior of this request; normally this should be the latest version number from SPHttpClientBatchConfigurations
- options
- ISPHttpClientBatchOptions
additional options that affect the request
Returns
Promise<SPHttpClientResponse>
A promise with behavior similar to WHATWG fetch(). This promise will resolve normally (with HttpClientResponse.ok being false) for error status codes such as HTTP 404 or 500. The promise will only reject for network failures or other errors that prevent communication with the server.
Remarks
The parameters for this function are basically the same as the WHATWG API standard documented here:
https://fetch.spec.whatwg.org/
However, be aware that certain REST headers are ignored or not allowed inside a batch. See the ODATA documentation for details.
When execute() is called, it will POST to a URL such as "http://example.com/sites/sample/_api/$batch". Typically SPHttpClientBatch can successfully guess the appropriate SPWeb URL by looking for a reserved URL segment such as "_api" in the first URL passed to fetch(). If not, use ISPHttpClientBatchCreationOptions.webUrl to specify it explicitly.
get(url, configuration, options)
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Calls fetch(), but sets the method to 'GET'.
get(url: string, configuration: SPHttpClientBatchConfiguration, options?: ISPHttpClientBatchOptions): Promise<SPHttpClientResponse>;Parameters
- url
-
string
the URL to fetch
- configuration
- SPHttpClientBatchConfiguration
determines the default behavior of this request; normally this should be the latest version number from SPHttpClientBatchConfigurations
- options
- ISPHttpClientBatchOptions
additional options that affect the request
Returns
Promise<SPHttpClientResponse>
A promise with behavior similar to WHATWG fetch(). This promise will resolve normally (with HttpClientResponse.ok being false) for error status codes such as HTTP 404 or 500. The promise will only reject for network failures or other errors that prevent communication with the server.
post(url, configuration, options)
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Calls fetch(), but sets the method to 'POST'.
post(url: string, configuration: SPHttpClientBatchConfiguration, options: ISPHttpClientBatchOptions): Promise<SPHttpClientResponse>;Parameters
- url
-
string
the URL to fetch
- configuration
- SPHttpClientBatchConfiguration
determines the default behavior of this request; normally this should be the latest version number from SPHttpClientBatchConfigurations
- options
- ISPHttpClientBatchOptions
additional options that affect the request
Returns
Promise<SPHttpClientResponse>
A promise with behavior similar to WHATWG fetch(). This promise will resolve normally (with HttpClientResponse.ok being false) for error status codes such as HTTP 404 or 500. The promise will only reject for network failures or other errors that prevent communication with the server.