SPHttpClient class
SPHttpClient is used to perform REST calls against SharePoint. It adds default headers, manages the digest needed for writes, and collects telemetry that helps the service to monitor the performance of an application.
Remarks
This class is marked as @sealed. Subclasses should not extend it.
For communicating with other internet services, use the HttpClient class.
Constructors
| (constructor)(service |
Constructs a new instance of the |
Properties
| configurations | The standard predefined SPHttpClientConfiguration objects for use with the SPHttpClient class. |
| is |
|
| service |
The service key for SPHttpClient. |
Methods
| _fetch(url, configuration, options) | |
| begin |
Begins an ODATA batch, which allows multiple REST queries to be bundled into a single web request. |
| fetch(url, configuration, options) | Perform a REST service call. |
| get(url, configuration, options) | Calls fetch(), but sets the method to "GET". |
| get |
Use a heuristic to infer the base URL for authentication. |
| post(url, configuration, options) | Calls fetch(), but sets the method to "POST". |
Constructor Details
(constructor)(serviceScope)
Constructs a new instance of the SPHttpClient class
constructor(serviceScope: ServiceScope);Parameters
- serviceScope
- ServiceScope
Property Details
configurations
The standard predefined SPHttpClientConfiguration objects for use with the SPHttpClient class.
static readonly configurations: ISPHttpClientConfigurations;Property Value
isNavigate
get isNavigate(): boolean;
set isNavigate(isNavigate: boolean);Property Value
boolean
serviceKey
The service key for SPHttpClient.
static readonly serviceKey: ServiceKey<SPHttpClient>;Property Value
Method Details
_fetch(url, configuration, options)
protected _fetch(url: string, configuration: SPHttpClientConfiguration, options: ISPHttpClientOptions): Promise<SPHttpClientResponse>;Parameters
- url
-
string
- configuration
- SPHttpClientConfiguration
- options
- ISPHttpClientOptions
Returns
Promise<SPHttpClientResponse>
beginBatch(batchCreationOptions)
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.
Begins an ODATA batch, which allows multiple REST queries to be bundled into a single web request.
beginBatch(batchCreationOptions?: ISPHttpClientBatchCreationOptions): SPHttpClientBatch;Parameters
- batchCreationOptions
- ISPHttpClientBatchCreationOptions
Returns
An SPHttpClientBatch object used to manage the batch operation.
fetch(url, configuration, options)
Perform a REST service call.
fetch(url: string, configuration: SPHttpClientConfiguration, options: ISPHttpClientOptions): Promise<SPHttpClientResponse>;Parameters
- url
-
string
the URL to fetch
- configuration
- SPHttpClientConfiguration
determines the default behavior of SPHttpClient; normally this should be the latest version number from SPHttpClientConfigurations
- options
- ISPHttpClientOptions
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
Generally, the parameters and semantics for SPHttpClient.fetch() are essentially the same as the WHATWG API standard that is documented here: https://fetch.spec.whatwg.org/
The SPHttpClient subclass adds some additional behaviors that are convenient when working with SharePoint ODATA API's (which can be avoided by using HttpClient instead):
Default "Accept" and "Content-Type" headers are added if not explicitly specified.
For write operations, an "X-RequestDigest" header is automatically added
The request digest token is automatically fetched and stored in a cache, with support for preloading
For a write operation, SPHttpClient will automatically add the "X-RequestDigest" header, which may need to be obtained by issuing a separate request such as "https://example.com/sites/sample/_api/contextinfo". Typically the appropriate SPWeb URL can be guessed by looking for a reserved URL segment such as "_api" in the original URL passed to fetch(); if not, use ISPHttpClientOptions.webUrl to specify it explicitly.
get(url, configuration, options)
Calls fetch(), but sets the method to "GET".
get(url: string, configuration: SPHttpClientConfiguration, options?: ISPHttpClientOptions): Promise<SPHttpClientResponse>;Parameters
- url
-
string
the URL to fetch
- configuration
- SPHttpClientConfiguration
determines the default behavior of SPHttpClient; normally this should be the latest version number from SPHttpClientConfigurations
- options
- ISPHttpClientOptions
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.
getWebUrlFromRequestUrl(requestUrl)
Use a heuristic to infer the base URL for authentication.
static getWebUrlFromRequestUrl(requestUrl: string): string;Parameters
- requestUrl
-
string
The URL for a SharePoint REST service
Returns
string
the inferred SPWeb URL
Remarks
Attempts to infer the SPWeb URL associated with the provided REST URL, by looking for common SharePoint path components such as "_api", "_layouts", or "_vit_bin". This is necessary for operations such as the X-RequestDigest and ODATA batching, which require POSTing to a separate REST endpoint in order to complete a request.
For example, if the requestUrl is "/sites/site/web/_api/service", the returned URL would be "/sites/site/web". Or if the requestUrl is "http://example.com/_layouts/service", the returned URL would be "http://example.com".
If the URL cannot be determined, an exception is thrown.
post(url, configuration, options)
Calls fetch(), but sets the method to "POST".
post(url: string, configuration: SPHttpClientConfiguration, options: ISPHttpClientOptions): Promise<SPHttpClientResponse>;Parameters
- url
-
string
the URL to fetch
- configuration
- SPHttpClientConfiguration
determines the default behavior of SPHttpClient; normally this should be the latest version number from SPHttpClientConfigurations
- options
- ISPHttpClientOptions
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.