Share via


@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:

  1. Serialize Phase
  2. Policies not in a phase
  3. Deserialize Phase
  4. Retry Phase
  5. 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

Returns

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

Returns

createDefaultHttpClient()

Create the correct HttpClient for the current environment.

function createDefaultHttpClient(): HttpClient

Returns

createEmptyPipeline()

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

function createEmptyPipeline(): Pipeline

Returns

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

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

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

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

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

Returns

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

formDataPolicy()

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

function formDataPolicy(): PipelinePolicy

Returns

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

multipartPolicy()

Pipeline policy for multipart requests

function multipartPolicy(): PipelinePolicy

Returns

ndJsonPolicy()

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

function ndJsonPolicy(): PipelinePolicy

Returns

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

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

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[]

Returns

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

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

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

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

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

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