@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 |
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 |
ChallengeCallbacks |
Options to override the processing of Continuous Access Evaluation challenges. |
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 |
LogPolicyOptions |
Options to configure the logPolicy. |
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 |
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 or (in the browser) a Blob. |
HttpMethods |
Supported HTTP methods to use when making requests. |
PipelinePhase |
Policies are executed in phases. The execution order is:
|
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
auxiliary |
A policy for external tokens to |
bearer |
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. |
create |
Create the correct HttpClient for the current environment. |
create |
Creates a totally empty pipeline. Useful for testing or creating a custom one. |
create |
Creates an object that satisfies the |
create |
Create a new pipeline with a default set of customizable policies. |
create |
Creates a new pipeline request with the given options. This method is to allow for the easy setting of default values and not required. |
decompress |
A policy to enable response decompression according to Accept-Encoding header https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding |
default |
A policy that retries according to three strategies:
|
exponential |
A policy that attempts to retry requests while introducing an exponentially increasing delay. |
form |
A policy that encodes FormData on the request into the body. |
get |
This method converts a proxy url into |
is |
Typeguard for RestError |
log |
A policy that logs all requests and responses. |
nd |
ndJsonPolicy is a policy used to control keep alive settings for every request. |
proxy |
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. |
redirect |
A policy to follow Location headers from the server in order to support server-side redirection. In the browser, this policy is not used. |
retry |
retryPolicy is a generic policy to enable retrying requests when certain conditions are met |
set |
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. |
system |
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. |
throttling |
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 |
tls |
Gets a pipeline policy that adds the client certificate to the HttpClient agent for authentication. |
tracing |
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. |
user |
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
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
- options
- DefaultRetryPolicyOptions
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)
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
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
- options
- RetryPolicyOptions
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.