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<@microsoft/sp-http!default:class>

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
@microsoft/sp-http!default:class

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<@microsoft/sp-http!default:class>

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
@microsoft/sp-http!default:class

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<@microsoft/sp-http!default:class>

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
@microsoft/sp-http!default:class

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<@microsoft/sp-http!default:class>

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.