@azure/core-rest-pipeline package

Classes

RestError

A custom error type for failed pipeline requests.

Interfaces

AddPipelineOptions	Options when adding a policy to the pipeline. Used to express dependencies on other policies.
Agent	An interface compatible with NodeJS's http.Agent. We want to avoid publicly re-exporting the actual interface, since it might vary across runtime versions.
AuthorizeRequestOnChallengeOptions	Options sent to the authorizeRequestOnChallenge callback
AuthorizeRequestOptions	Options sent to the authorizeRequest callback
AuxiliaryAuthenticationHeaderPolicyOptions	Options to configure the auxiliaryAuthenticationHeaderPolicy
BearerTokenAuthenticationPolicyOptions	Options to configure the bearerTokenAuthenticationPolicy
BodyPart	A part of the request body in a multipart request.
ChallengeCallbacks	Options to override the processing of Continuous Access Evaluation challenges.
CreateFileFromStreamOptions	Extra options for createFile when a stream is being passed in.
CreateFileOptions	Options passed into createFile specifying metadata about the file.
DefaultRetryPolicyOptions	Options that control how to retry failed requests.
ExponentialRetryPolicyOptions	Options that control how to retry failed requests.
HttpClient	The required interface for a client that makes HTTP requests on behalf of a pipeline.
HttpHeaders	Represents a set of HTTP headers on a request/response. Header names are treated as case insensitive.
InternalPipelineOptions	Defines options that are used to configure internal options of the HTTP pipeline for an SDK client.
KeyObject	An interface compatible with NodeJS's tls.KeyObject. We want to avoid publicly re-exporting the actual interface, since it might vary across runtime versions.
LogPolicyOptions	Options to configure the logPolicy.
MultipartRequestBody	A request body consisting of multiple parts.
Pipeline	Represents a pipeline for making a HTTP request to a URL. Pipelines can have multiple policies to manage manipulating each request before and after it is made to the server.
PipelineOptions	Defines options that are used to configure the HTTP pipeline for an SDK client.
PipelinePolicy	A pipeline policy manipulates a request as it travels through the pipeline. It is conceptually a middleware that is allowed to modify the request before it is made as well as the response when it is received.
PipelineRequest	Metadata about a request being made by the pipeline.
PipelineRequestOptions	Settings to initialize a request. Almost equivalent to Partial, but url is mandatory.
PipelineResponse	Metadata about a response received by the pipeline.
PipelineRetryOptions	Options that control how to retry failed requests.
ProxySettings	Options to configure a proxy for outgoing requests (Node.js only).
PxfObject	An interface compatible with NodeJS's tls.PxfObject. We want to avoid publicly re-exporting the actual interface, since it might vary across runtime versions.
RedirectPolicyOptions	Options for how redirect responses are handled.
RestErrorOptions	The options supported by RestError.
RetryInformation	Information provided to the retry strategy about the current progress of the retry policy.
RetryModifiers	Properties that can modify the behavior of the retry policy.
RetryPolicyOptions	Options to the retryPolicy
RetryStrategy	A retry strategy is intended to define whether to retry or not, and how to retry.
SystemErrorRetryPolicyOptions	Options that control how to retry failed requests.
TelemetryOptions	Defines options that are used to configure common telemetry and tracing info
ThrottlingRetryPolicyOptions	Options that control how to retry failed requests.
TlsSettings	Represents a certificate for TLS authentication.
TracingPolicyOptions	Options to configure the tracing policy.
UserAgentPolicyOptions	Options for adding user agent details to outgoing requests.

Type Aliases

FormDataMap	A simple object that provides form data, as if from a browser form.
FormDataValue	Each form data entry can be a string, Blob, or a File. If you wish to pass a file with a name but do not have access to the File class, you can use the createFile helper to create one.
HttpMethods	Supported HTTP methods to use when making requests.
PipelinePhase	Policies are executed in phases. The execution order is: Serialize Phase Policies not in a phase Deserialize Phase Retry Phase Sign Phase
RawHttpHeaders	A HttpHeaders collection represented as a simple JSON object.
RawHttpHeadersInput	A HttpHeaders collection for input, represented as a simple JSON object.
RequestBodyType	Types of bodies supported on the request. NodeJS.ReadableStream and () => NodeJS.ReadableStream is Node only. Blob, ReadableStream, and () => ReadableStream are browser only.
SendRequest	A simple interface for making a pipeline request and receiving a response.
TransferProgressEvent	Fired in response to upload or download progress.

Functions

auxiliaryAuthenticationHeaderPolicy(AuxiliaryAuthenticationHeaderPolicyOptions)	A policy for external tokens to x-ms-authorization-auxiliary header. This header will be used when creating a cross-tenant application we may need to handle authentication requests for resources that are in different tenants. You could see ARM docs for a rundown of how this feature works
bearerTokenAuthenticationPolicy(BearerTokenAuthenticationPolicyOptions)	A policy that can request a token from a TokenCredential implementation and then apply it to the Authorization header of a request as a Bearer token.
createDefaultHttpClient()	Create the correct HttpClient for the current environment.
createEmptyPipeline()	Creates a totally empty pipeline. Useful for testing or creating a custom one.
createFile(Uint8Array, string, CreateFileOptions)	Create an object that implements the File interface. This object is intended to be passed into RequestBodyType.formData, and is not guaranteed to work as expected in other situations. Use this function create a File object for use in RequestBodyType.formData in environments where the global File object is unavailable.
createFileFromStream(() => ReadableStream<Uint8Array> | ReadableStream, string, CreateFileFromStreamOptions)	Create an object that implements the File interface. This object is intended to be passed into RequestBodyType.formData, and is not guaranteed to work as expected in other situations. Use this function to: Create a File object for use in RequestBodyType.formData in environments where the global File object is unavailable. Create a File-like object from a readable stream without reading the stream into memory.
createHttpHeaders(RawHttpHeadersInput)	Creates an object that satisfies the HttpHeaders interface.
createPipelineFromOptions(InternalPipelineOptions)	Create a new pipeline with a default set of customizable policies.
createPipelineRequest(PipelineRequestOptions)	Creates a new pipeline request with the given options. This method is to allow for the easy setting of default values and not required.
decompressResponsePolicy()	A policy to enable response decompression according to Accept-Encoding header https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding
defaultRetryPolicy(DefaultRetryPolicyOptions)	A policy that retries according to three strategies: When the server sends a 429 response with a Retry-After header. When there are errors in the underlying transport layer (e.g. DNS lookup failures). Or otherwise if the outgoing request fails, it will retry with an exponentially increasing delay.
exponentialRetryPolicy(ExponentialRetryPolicyOptions)	A policy that attempts to retry requests while introducing an exponentially increasing delay.
formDataPolicy()	A policy that encodes FormData on the request into the body.
getDefaultProxySettings(string)	This method converts a proxy url into ProxySettings for use with ProxyPolicy. If no argument is given, it attempts to parse a proxy URL from the environment variables HTTPS_PROXY or HTTP_PROXY.
isRestError(unknown)	Typeguard for RestError
logPolicy(LogPolicyOptions)	A policy that logs all requests and responses.
multipartPolicy()	Pipeline policy for multipart requests
ndJsonPolicy()	ndJsonPolicy is a policy used to control keep alive settings for every request.
proxyPolicy(ProxySettings, { customNoProxyList?: string[] })	A policy that allows one to apply proxy settings to all requests. If not passed static settings, they will be retrieved from the HTTPS_PROXY or HTTP_PROXY environment variables.
redirectPolicy(RedirectPolicyOptions)	A policy to follow Location headers from the server in order to support server-side redirection. In the browser, this policy is not used.
retryPolicy(RetryStrategy[], RetryPolicyOptions)	retryPolicy is a generic policy to enable retrying requests when certain conditions are met
setClientRequestIdPolicy(string)	Each PipelineRequest gets a unique id upon creation. This policy passes that unique id along via an HTTP header to enable better telemetry and tracing.
systemErrorRetryPolicy(SystemErrorRetryPolicyOptions)	A retry policy that specifically seeks to handle errors in the underlying transport layer (e.g. DNS lookup failures) rather than retryable error codes from the server itself.
throttlingRetryPolicy(ThrottlingRetryPolicyOptions)	A policy that retries when the server sends a 429 response with a Retry-After header. To learn more, please refer to https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-request-limits, https://docs.microsoft.com/en-us/azure/azure-subscription-service-limits and https://docs.microsoft.com/en-us/azure/virtual-machines/troubleshooting/troubleshooting-throttling-errors
tlsPolicy(TlsSettings)	Gets a pipeline policy that adds the client certificate to the HttpClient agent for authentication.
tracingPolicy(TracingPolicyOptions)	A simple policy to create OpenTelemetry Spans for each request made by the pipeline that has SpanOptions with a parent. Requests made without a parent Span will not be recorded.
userAgentPolicy(UserAgentPolicyOptions)	A policy that sets the User-Agent header (or equivalent) to reflect the library version.

Function Details

auxiliaryAuthenticationHeaderPolicy(AuxiliaryAuthenticationHeaderPolicyOptions)

A policy for external tokens to x-ms-authorization-auxiliary header. This header will be used when creating a cross-tenant application we may need to handle authentication requests for resources that are in different tenants. You could see ARM docs for a rundown of how this feature works

function auxiliaryAuthenticationHeaderPolicy(options: AuxiliaryAuthenticationHeaderPolicyOptions): PipelinePolicy

Parameters

options

AuxiliaryAuthenticationHeaderPolicyOptions

Returns

PipelinePolicy

bearerTokenAuthenticationPolicy(BearerTokenAuthenticationPolicyOptions)

A policy that can request a token from a TokenCredential implementation and then apply it to the Authorization header of a request as a Bearer token.

function bearerTokenAuthenticationPolicy(options: BearerTokenAuthenticationPolicyOptions): PipelinePolicy

Parameters

options

BearerTokenAuthenticationPolicyOptions

Returns

PipelinePolicy

createDefaultHttpClient()

Create the correct HttpClient for the current environment.

function createDefaultHttpClient(): HttpClient

Returns

HttpClient

createEmptyPipeline()

Creates a totally empty pipeline. Useful for testing or creating a custom one.

function createEmptyPipeline(): Pipeline

Returns

Pipeline

createFile(Uint8Array, string, CreateFileOptions)

Create an object that implements the File interface. This object is intended to be passed into RequestBodyType.formData, and is not guaranteed to work as expected in other situations.

Use this function create a File object for use in RequestBodyType.formData in environments where the global File object is unavailable.

function createFile(content: Uint8Array, name: string, options?: CreateFileOptions): File

Parameters

content

Uint8Array

the content of the file as a Uint8Array in memory.

name

string

the name of the file.

options

CreateFileOptions

optional metadata about the file, e.g. file name, file size, MIME type.

Returns

File

createFileFromStream(() => ReadableStream<Uint8Array> | ReadableStream, string, CreateFileFromStreamOptions)

Create an object that implements the File interface. This object is intended to be passed into RequestBodyType.formData, and is not guaranteed to work as expected in other situations.

Use this function to:

• Create a File object for use in RequestBodyType.formData in environments where the global File object is unavailable.
• Create a File-like object from a readable stream without reading the stream into memory.

function createFileFromStream(stream: () => ReadableStream<Uint8Array> | ReadableStream, name: string, options?: CreateFileFromStreamOptions): File

Parameters

stream

() => ReadableStream<Uint8Array> | ReadableStream

the content of the file as a callback returning a stream. When a File object made using createFile is passed in a request's form data map, the stream will not be read into memory and instead will be streamed when the request is made. In the event of a retry, the stream needs to be read again, so this callback SHOULD return a fresh stream if possible.

name

string

the name of the file.

options

CreateFileFromStreamOptions

optional metadata about the file, e.g. file name, file size, MIME type.

Returns

File

createHttpHeaders(RawHttpHeadersInput)

Creates an object that satisfies the HttpHeaders interface.

function createHttpHeaders(rawHeaders?: RawHttpHeadersInput): HttpHeaders

Parameters

rawHeaders

RawHttpHeadersInput

A simple object representing initial headers

Returns

HttpHeaders

createPipelineFromOptions(InternalPipelineOptions)

Create a new pipeline with a default set of customizable policies.

function createPipelineFromOptions(options: InternalPipelineOptions): Pipeline

Parameters

options

InternalPipelineOptions

Options to configure a custom pipeline.

Returns

Pipeline

createPipelineRequest(PipelineRequestOptions)

Creates a new pipeline request with the given options. This method is to allow for the easy setting of default values and not required.

function createPipelineRequest(options: PipelineRequestOptions): PipelineRequest

Parameters

options

PipelineRequestOptions

The options to create the request with.

Returns

PipelineRequest

decompressResponsePolicy()

A policy to enable response decompression according to Accept-Encoding header https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding

function decompressResponsePolicy(): PipelinePolicy

Returns

PipelinePolicy

defaultRetryPolicy(DefaultRetryPolicyOptions)

A policy that retries according to three strategies:

• When the server sends a 429 response with a Retry-After header.
• When there are errors in the underlying transport layer (e.g. DNS lookup failures).
• Or otherwise if the outgoing request fails, it will retry with an exponentially increasing delay.

function defaultRetryPolicy(options?: DefaultRetryPolicyOptions): PipelinePolicy

Parameters

options

DefaultRetryPolicyOptions

Returns

PipelinePolicy

exponentialRetryPolicy(ExponentialRetryPolicyOptions)

A policy that attempts to retry requests while introducing an exponentially increasing delay.

function exponentialRetryPolicy(options?: ExponentialRetryPolicyOptions): PipelinePolicy

Parameters

options

ExponentialRetryPolicyOptions

Options that configure retry logic.

Returns

PipelinePolicy

formDataPolicy()

A policy that encodes FormData on the request into the body.

function formDataPolicy(): PipelinePolicy

Returns

PipelinePolicy

getDefaultProxySettings(string)

Warning

This API is now deprecated.

• Internally this method is no longer necessary when setting proxy information.

This method converts a proxy url into ProxySettings for use with ProxyPolicy. If no argument is given, it attempts to parse a proxy URL from the environment variables HTTPS_PROXY or HTTP_PROXY.

function getDefaultProxySettings(proxyUrl?: string): ProxySettings | undefined

Parameters

proxyUrl

string

The url of the proxy to use. May contain authentication information.

Returns

ProxySettings | undefined

isRestError(unknown)

Typeguard for RestError

function isRestError(e: unknown): e

Parameters

e

unknown

Something caught by a catch clause.

Returns

e

logPolicy(LogPolicyOptions)

A policy that logs all requests and responses.

function logPolicy(options?: LogPolicyOptions): PipelinePolicy

Parameters

options

LogPolicyOptions

Options to configure logPolicy.

Returns

PipelinePolicy

multipartPolicy()

Pipeline policy for multipart requests

function multipartPolicy(): PipelinePolicy

Returns

PipelinePolicy

ndJsonPolicy()

ndJsonPolicy is a policy used to control keep alive settings for every request.

function ndJsonPolicy(): PipelinePolicy

Returns

PipelinePolicy

proxyPolicy(ProxySettings, { customNoProxyList?: string[] })

A policy that allows one to apply proxy settings to all requests. If not passed static settings, they will be retrieved from the HTTPS_PROXY or HTTP_PROXY environment variables.

function proxyPolicy(proxySettings?: ProxySettings, options?: { customNoProxyList?: string[] }): PipelinePolicy

Parameters

proxySettings

ProxySettings

ProxySettings to use on each request.

options

{ customNoProxyList?: string[] }

additional settings, for example, custom NO_PROXY patterns

Returns

PipelinePolicy

redirectPolicy(RedirectPolicyOptions)

A policy to follow Location headers from the server in order to support server-side redirection. In the browser, this policy is not used.

function redirectPolicy(options?: RedirectPolicyOptions): PipelinePolicy

Parameters

options

RedirectPolicyOptions

Options to control policy behavior.

Returns

PipelinePolicy

retryPolicy(RetryStrategy[], RetryPolicyOptions)

retryPolicy is a generic policy to enable retrying requests when certain conditions are met

function retryPolicy(strategies: RetryStrategy[], options?: RetryPolicyOptions): PipelinePolicy

Parameters

strategies

RetryStrategy[]

options

RetryPolicyOptions

Returns

PipelinePolicy

setClientRequestIdPolicy(string)

Each PipelineRequest gets a unique id upon creation. This policy passes that unique id along via an HTTP header to enable better telemetry and tracing.

function setClientRequestIdPolicy(requestIdHeaderName?: string): PipelinePolicy

Parameters

requestIdHeaderName

string

The name of the header to pass the request ID to.

Returns

PipelinePolicy

systemErrorRetryPolicy(SystemErrorRetryPolicyOptions)

A retry policy that specifically seeks to handle errors in the underlying transport layer (e.g. DNS lookup failures) rather than retryable error codes from the server itself.

function systemErrorRetryPolicy(options?: SystemErrorRetryPolicyOptions): PipelinePolicy

Parameters

options

SystemErrorRetryPolicyOptions

Options that customize the policy.

Returns

PipelinePolicy

throttlingRetryPolicy(ThrottlingRetryPolicyOptions)

A policy that retries when the server sends a 429 response with a Retry-After header.

To learn more, please refer to https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-request-limits, https://docs.microsoft.com/en-us/azure/azure-subscription-service-limits and https://docs.microsoft.com/en-us/azure/virtual-machines/troubleshooting/troubleshooting-throttling-errors

function throttlingRetryPolicy(options?: ThrottlingRetryPolicyOptions): PipelinePolicy

Parameters

options

ThrottlingRetryPolicyOptions

Options that configure retry logic.

Returns

PipelinePolicy

tlsPolicy(TlsSettings)

Gets a pipeline policy that adds the client certificate to the HttpClient agent for authentication.

function tlsPolicy(tlsSettings?: TlsSettings): PipelinePolicy

Parameters

tlsSettings

TlsSettings

Returns

PipelinePolicy

tracingPolicy(TracingPolicyOptions)

A simple policy to create OpenTelemetry Spans for each request made by the pipeline that has SpanOptions with a parent. Requests made without a parent Span will not be recorded.

function tracingPolicy(options?: TracingPolicyOptions): PipelinePolicy

Parameters

options

TracingPolicyOptions

Options to configure the telemetry logged by the tracing policy.

Returns

PipelinePolicy

userAgentPolicy(UserAgentPolicyOptions)

A policy that sets the User-Agent header (or equivalent) to reflect the library version.

function userAgentPolicy(options?: UserAgentPolicyOptions): PipelinePolicy

Parameters

options

UserAgentPolicyOptions

Options to customize the user agent value.

Returns

PipelinePolicy