@azure/core-http package

Classes

AccessTokenRefresher

Helps the core-http token authentication policies with requesting a new token if we're not currently waiting for a new token.

ApiKeyCredentials

Authenticates to a service using an API key.

BaseRequestPolicy

The base class from which all request policies derive.

BasicAuthenticationCredentials

A simple <xref:ServiceClientCredential> that authenticates with a username and a password.

DefaultHttpClient

An HTTP client that uses node-fetch.

ExpiringAccessTokenCache

Provides an AccessTokenCache implementation which clears the cached AccessToken's after the expiresOnTimestamp has passed.

HttpHeaders

A collection of HTTP header key/value pairs.

RequestPolicyOptions

Optional properties that can be used when creating a RequestPolicy.

RestError

An error resulting from an HTTP request to a service endpoint.

Serializer

Used to map raw response objects to final shapes. Helps packing and unpacking Dates and other encoded types that are not intrinsic to JSON. Also allows pulling values from headers, as well as inserting default values and constants.

ServiceClient

ServiceClient sends service requests and receives responses.

TopicCredentials

A TopicCredentials object used for Azure Event Grid.

URLBuilder

A class that handles creating, modifying, and parsing URLs.

URLQuery

A class that handles the query portion of a URLBuilder.

WebResource

Creates a new WebResource object.

This class provides an abstraction over a REST call by being library / implementation agnostic and wrapping the necessary properties to initiate a request.

Interfaces

AbortSignalLike

Allows the request to be aborted upon firing of the "abort" event. Compatible with the browser built-in AbortSignal and common polyfills.

AccessToken

Represents an access token with an expiration time.

AccessTokenCache

Provides a cache for an AccessToken that was that was returned from a TokenCredential.

ApiKeyCredentialOptions

Describes the options to be provided while creating an instance of ApiKeyCredentials

BaseMapper

The base definition of a mapper. Can be used for XML and plain JavaScript objects.

CompositeMapper

A mapper composed of other mappers.

CompositeMapperType

Helps build a mapper that describes how to map a set of properties of an object based on other mappers.

Only one of the following properties should be present: className, modelProperties and additionalProperties.

DeserializationContentTypes

The content-types that will indicate that an operation response should be deserialized in a particular way.

DeserializationOptions

Options to configure API response deserialization.

DictionaryMapper

A mapper describing plain JavaScript objects used as key/value pairs.

DictionaryMapperType

Helps build a mapper that describes how to parse a dictionary of mapped values.

EnumMapper

A mapper describing an enum value.

EnumMapperType

Helps build a mapper that describes how to parse an enum value.

GetTokenOptions

Defines options for TokenCredential.getToken.

HttpClient

An interface that can send HttpRequests and receive promised HttpResponses.

HttpHeader

An individual header within a HttpHeaders collection.

HttpHeadersLike

A collection of HTTP header key/value pairs.

HttpOperationResponse

Wrapper object for http request and response. Deserialized object is stored in the parsedBody property when the response body is received in JSON or XML.

HttpPipelineLogger

A Logger that can be added to a HttpPipeline. This enables each RequestPolicy to log messages that can be used for debugging purposes.

HttpResponse

The properties on an HTTP response which will always be present.

InternalPipelineOptions

Defines options that are used to configure internal options of the HTTP pipeline for an SDK client.

KeepAliveOptions

Options for how HTTP connections should be maintained for future requests.

LogPolicyOptions

Options to pass to the logPolicy. By default only a set list of headers are logged, though this can be configured. Request and response bodies are never logged.

MapperConstraints

Description of various value constraints such as integer ranges and string regex.

OperationArguments

A collection of properties that apply to a single invocation of an operation.

OperationOptions

The base options type for all operations.

OperationParameter

A common interface that all Operation parameter's extend.

OperationQueryParameter

A parameter for an operation that will be added as a query parameter to the operation's HTTP request.

OperationRequestOptions

Options that allow configuring the handling of HTTP requests made by an SDK operation.

OperationResponse

An OperationResponse that can be returned from an operation request for a single status code.

OperationSpec

A specification that defines how to perform a particular service operation over HTTP, including how to properly serialize request information into and deserialize response information into an object payload returnable by the ServiceClient.

OperationURLParameter

A parameter for an operation that will be substituted into the operation's request URL.

ParameterValue

The Parameter value provided for path or query parameters in RequestPrepareOptions

PipelineOptions

Defines options that are used to configure the HTTP pipeline for an SDK client.

PolymorphicDiscriminator

Used to disambiguate discriminated type unions. For example, if response can have many shapes but also includes a 'kind' field (or similar), that field can be used to determine how to deserialize the response to the correct type.

ProxySettings

Options to configure a proxy for outgoing requests (Node.js only).

RedirectOptions

Options for how redirect responses are handled.

RequestOptionsBase

Describes the base structure of the options object that will be used in every operation.

RequestPolicy

The underlying structure of a request policy.

RequestPolicyOptionsLike

Optional properties that can be used when creating a RequestPolicy.

RequestPrepareOptions

Options to prepare an outgoing HTTP request.

RestResponse

The flattened response to a REST call. Contains the underlying HttpOperationResponse as well as the merged properties of the parsedBody, parsedHeaders, etc.

RetryOptions

Options that control how to retry failed requests.

SequenceMapper

A mapper describing arrays.

SequenceMapperType

Helps build a mapper that describes how to parse a sequence of mapped values.

SerializerOptions

Options to govern behavior of xml parser and builder.

ServiceCallback
ServiceClientCredentials

Represents an object or class with a signRequest method which will sign outgoing requests (for example, by setting the Authorization header).

ServiceClientOptions

Options to be provided while creating the client.

SimpleMapperType

The type of a simple mapper.

TokenCredential

Represents a credential capable of providing an authentication token.

TracingPolicyOptions

Options to customize the tracing policy.

UrlParameterValue

An interface representing an URL parameter value.

UserAgentOptions

Options for adding user agent details to outgoing requests.

WebResourceLike

A description of a HTTP request to be made to a remote server.

Type Aliases

Authenticator

A function that receives a challenge and resolves a promise with a string token.

CommonRequestInfo

String URLs used when calling to fetch().

CommonRequestInit

An object containing information about the outgoing HTTP request.

CommonResponse

An object containing information about the incoming HTTP response.

HttpMethods

List of supported HTTP methods.

HttpRequestBody

Possible HTTP request body types

Mapper

Mappers are definitions of the data models used in the library. These data models are part of the Operation or Client definitions in the responses or parameters.

MapperType

Type of the mapper. Includes known mappers.

ParameterPath

A path which describes how to access a particular property in a given object data source. May be a single property name, an array that denotes nested property names, or a set of multiple named properties with paths in the case of complex object values.

ProxyOptions

An alias of ProxySettings for future use.

RawHttpHeaders

A HttpHeaders collection represented as a simple JSON object.

RequestPolicyFactory

Creates a new RequestPolicy per-request that uses the provided nextPolicy.

TelemetryInfo

Telemetry information. Key/value pairs to include inside the User-Agent string.

TransferProgressEvent

Fired in response to upload or download progress.

Enums

HttpPipelineLogLevel

The different levels of logs that can be used with the HttpPipelineLogger.

QueryCollectionFormat

The format that will be used to join an array of values together for a query parameter value.

RetryMode

Describes the Retry Mode type. Currently supporting only Exponential.

Functions

applyMixins(unknown, any[])

Applies the properties on the prototype of sourceCtors to the prototype of targetCtor

bearerTokenAuthenticationPolicy(TokenCredential, string | string[])

Creates a new factory for a RequestPolicy that applies a bearer token to the requests' Authorization headers.

createPipelineFromOptions(InternalPipelineOptions, RequestPolicyFactory)

Creates an HTTP pipeline based on the given options.

delay(number, DelayOptions)

A wrapper for setTimeout that resolves a promise after timeInMs milliseconds.

deserializationPolicy(DeserializationContentTypes, SerializerOptions)

Create a new serialization RequestPolicyCreator that will serialized HTTP request bodies as they pass through the HTTP pipeline.

deserializeResponseBody(string[], string[], HttpOperationResponse, SerializerOptions)

Given a particular set of content types to parse as either JSON or XML, consumes the HTTP response to produce the result object defined by the request's OperationSpec.

disableResponseDecompressionPolicy()

Returns a request policy factory that can be used to create an instance of <xref:DisableResponseDecompressionPolicy>.

encodeUri(string)

Encodes an URI.

executePromisesSequentially(any[], unknown)

Executes an array of promises sequentially. Inspiration of this method is here: https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html. An awesome blog on promises!

exponentialRetryPolicy(number, number, number)

Policy that retries the request as many times as configured for as long as the max retry time interval specified, each retry waiting longer to begin than the last time.

flattenResponse(HttpOperationResponse, undefined | OperationResponse)

Parses an HttpOperationResponse into a normalized HTTP response object (RestResponse).

generateClientRequestIdPolicy(string)

Creates a policy that assigns a unique request id to outgoing requests.

generateUuid()

Generated UUID

getDefaultProxySettings(string)

Converts a given URL of a proxy server into ProxySettings or attempts to retrieve ProxySettings from the current environment if one is not passed.

getDefaultUserAgentValue()

The default approach to generate user agents. Uses static information from this package, plus system information available from the runtime.

isDuration(string)

Indicates whether the given string is in ISO 8601 format.

isTokenCredential(unknown)

Tests an object to determine whether it implements TokenCredential.

isValidUuid(string)

Validates the given uuid as a string

keepAlivePolicy(KeepAliveOptions)

Creates a policy that controls whether HTTP connections are maintained on future requests.

logPolicy(LogPolicyOptions)

Creates a policy that logs information about the outgoing request and the incoming responses.

operationOptionsToRequestOptionsBase<T>(T)

Converts an OperationOptions to a RequestOptionsBase

parseXML(string, SerializerOptions)

Converts given XML string into JSON

promiseToCallback(Promise<any>)

Converts a Promise to a callback.

promiseToServiceCallback<T>(Promise<HttpOperationResponse>)

Converts a Promise to a service callback.

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(number)

Creates a redirect policy, which sends a repeats the request to a new destination if a response arrives with a "location" header, and a status code between 300 and 307.

serializeObject(unknown)

Utility function that serializes an object that might contain binary information into a plain object, array or a string.

signingPolicy(ServiceClientCredentials)

Creates a policy that signs outgoing requests by calling to the provided authenticationProvider's signRequest method.

stringifyXML(unknown, SerializerOptions)

Converts given JSON object to XML string

stripRequest(WebResourceLike)

Returns a stripped version of the Http Request that does not contain the Authorization header.

stripResponse(HttpOperationResponse)

Returns a stripped version of the Http Response which only contains body, headers and the status.

systemErrorRetryPolicy(number, number, number, number)

A policy that retries when there's a system error, identified by the codes "ETIMEDOUT", "ESOCKETTIMEDOUT", "ECONNREFUSED", "ECONNRESET" or "ENOENT".

throttlingRetryPolicy()

Creates a policy that re-sends the request if the response indicates the request failed because of throttling reasons. For example, if the response contains a Retry-After header, it will retry sending the request based on the value of that 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

tracingPolicy(TracingPolicyOptions)

Creates a policy that wraps outgoing requests with a tracing span.

userAgentPolicy(TelemetryInfo)

Returns a policy that adds the user agent header to outgoing requests based on the given TelemetryInfo.

Function Details

applyMixins(unknown, any[])

Applies the properties on the prototype of sourceCtors to the prototype of targetCtor

function applyMixins(targetCtorParam: unknown, sourceCtors: any[])

Parameters

targetCtorParam

unknown

sourceCtors

any[]

An array of source objects from which the properties need to be taken.

bearerTokenAuthenticationPolicy(TokenCredential, string | string[])

Creates a new factory for a RequestPolicy that applies a bearer token to the requests' Authorization headers.

function bearerTokenAuthenticationPolicy(credential: TokenCredential, scopes: string | string[]): RequestPolicyFactory

Parameters

credential
TokenCredential

The TokenCredential implementation that can supply the bearer token.

scopes

string | string[]

The scopes for which the bearer token applies.

Returns

createPipelineFromOptions(InternalPipelineOptions, RequestPolicyFactory)

Creates an HTTP pipeline based on the given options.

function createPipelineFromOptions(pipelineOptions: InternalPipelineOptions, authPolicyFactory?: RequestPolicyFactory): ServiceClientOptions

Parameters

pipelineOptions
InternalPipelineOptions

Defines options that are used to configure policies in the HTTP pipeline for an SDK client.

authPolicyFactory
RequestPolicyFactory

An optional authentication policy factory to use for signing requests.

Returns

A set of options that can be passed to create a new ServiceClient.

delay(number, DelayOptions)

A wrapper for setTimeout that resolves a promise after timeInMs milliseconds.

function delay(timeInMs: number, options?: DelayOptions): Promise<void>

Parameters

timeInMs

number

The number of milliseconds to be delayed.

options
DelayOptions

The options for delay - currently abort options

Returns

Promise<void>

Promise that is resolved after timeInMs

deserializationPolicy(DeserializationContentTypes, SerializerOptions)

Create a new serialization RequestPolicyCreator that will serialized HTTP request bodies as they pass through the HTTP pipeline.

function deserializationPolicy(deserializationContentTypes?: DeserializationContentTypes, parsingOptions?: SerializerOptions): RequestPolicyFactory

Parameters

deserializationContentTypes
DeserializationContentTypes
parsingOptions
SerializerOptions

Returns

deserializeResponseBody(string[], string[], HttpOperationResponse, SerializerOptions)

Given a particular set of content types to parse as either JSON or XML, consumes the HTTP response to produce the result object defined by the request's OperationSpec.

function deserializeResponseBody(jsonContentTypes: string[], xmlContentTypes: string[], response: HttpOperationResponse, options?: SerializerOptions): Promise<HttpOperationResponse>

Parameters

jsonContentTypes

string[]

Response content types to parse the body as JSON.

xmlContentTypes

string[]

Response content types to parse the body as XML.

response
HttpOperationResponse

HTTP Response from the pipeline.

options
SerializerOptions

Options to the serializer, mostly for configuring the XML parser if needed.

Returns

A parsed HttpOperationResponse object that can be returned by the ServiceClient.

disableResponseDecompressionPolicy()

Returns a request policy factory that can be used to create an instance of <xref:DisableResponseDecompressionPolicy>.

function disableResponseDecompressionPolicy(): RequestPolicyFactory

Returns

encodeUri(string)

Encodes an URI.

function encodeUri(uri: string): string

Parameters

uri

string

The URI to be encoded.

Returns

string

The encoded URI.

executePromisesSequentially(any[], unknown)

Executes an array of promises sequentially. Inspiration of this method is here: https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html. An awesome blog on promises!

function executePromisesSequentially(promiseFactories: any[], kickstart: unknown): Promise<any>

Parameters

promiseFactories

any[]

An array of promise factories(A function that return a promise)

kickstart

unknown

Input to the first promise that is used to kickstart the promise chain. If not provided then the promise chain starts with undefined.

Returns

Promise<any>

A chain of resolved or rejected promises

exponentialRetryPolicy(number, number, number)

Policy that retries the request as many times as configured for as long as the max retry time interval specified, each retry waiting longer to begin than the last time.

function exponentialRetryPolicy(retryCount?: number, retryInterval?: number, maxRetryInterval?: number): RequestPolicyFactory

Parameters

retryCount

number

Maximum number of retries.

retryInterval

number

Base time between retries.

maxRetryInterval

number

Maximum time to wait between retries.

Returns

flattenResponse(HttpOperationResponse, undefined | OperationResponse)

Parses an HttpOperationResponse into a normalized HTTP response object (RestResponse).

function flattenResponse(_response: HttpOperationResponse, responseSpec: undefined | OperationResponse): RestResponse

Parameters

_response
HttpOperationResponse

Wrapper object for http response.

responseSpec

undefined | OperationResponse

Mappers for how to parse the response properties.

Returns

  • A normalized response object.

generateClientRequestIdPolicy(string)

Creates a policy that assigns a unique request id to outgoing requests.

function generateClientRequestIdPolicy(requestIdHeaderName?: string): RequestPolicyFactory

Parameters

requestIdHeaderName

string

The name of the header to use when assigning the unique id to the request.

Returns

generateUuid()

Generated UUID

function generateUuid(): string

Returns

string

RFC4122 v4 UUID.

getDefaultProxySettings(string)

Converts a given URL of a proxy server into ProxySettings or attempts to retrieve ProxySettings from the current environment if one is not passed.

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

Parameters

proxyUrl

string

URL of the proxy

Returns

ProxySettings | undefined

The default proxy settings, or undefined.

getDefaultUserAgentValue()

The default approach to generate user agents. Uses static information from this package, plus system information available from the runtime.

function getDefaultUserAgentValue(): string

Returns

string

isDuration(string)

Indicates whether the given string is in ISO 8601 format.

function isDuration(value: string): boolean

Parameters

value

string

The value to be validated for ISO 8601 duration format.

Returns

boolean

true if valid, false otherwise.

isTokenCredential(unknown)

Tests an object to determine whether it implements TokenCredential.

function isTokenCredential(credential: unknown): credential

Parameters

credential

unknown

The assumed TokenCredential to be tested.

Returns

credential

isValidUuid(string)

Validates the given uuid as a string

function isValidUuid(uuid: string): boolean

Parameters

uuid

string

The uuid as a string that needs to be validated

Returns

boolean

True if the uuid is valid; false otherwise.

keepAlivePolicy(KeepAliveOptions)

Creates a policy that controls whether HTTP connections are maintained on future requests.

function keepAlivePolicy(keepAliveOptions?: KeepAliveOptions): RequestPolicyFactory

Parameters

keepAliveOptions
KeepAliveOptions

Keep alive options. By default, HTTP connections are maintained for future requests.

Returns

An instance of the <xref:KeepAlivePolicy>

logPolicy(LogPolicyOptions)

Creates a policy that logs information about the outgoing request and the incoming responses.

function logPolicy(loggingOptions?: LogPolicyOptions): RequestPolicyFactory

Parameters

loggingOptions
LogPolicyOptions

Logging options.

Returns

An instance of the <xref:LogPolicy>

operationOptionsToRequestOptionsBase<T>(T)

Converts an OperationOptions to a RequestOptionsBase

function operationOptionsToRequestOptionsBase<T>(opts: T): RequestOptionsBase

Parameters

opts

T

OperationOptions object to convert to RequestOptionsBase

Returns

parseXML(string, SerializerOptions)

Converts given XML string into JSON

function parseXML(str: string, opts?: SerializerOptions): Promise<any>

Parameters

str

string

String containing the XML content to be parsed into JSON

opts
SerializerOptions

Options that govern the parsing of given xml string

Returns

Promise<any>

promiseToCallback(Promise<any>)

Warning

This API is now deprecated.

generated code should instead depend on responseToBody

Converts a Promise to a callback.

function promiseToCallback(promise: Promise<any>): (cb: Function) => void

Parameters

promise

Promise<any>

The Promise to be converted to a callback

Returns

(cb: Function) => void

A function that takes the callback (cb: Function) => void

promiseToServiceCallback<T>(Promise<HttpOperationResponse>)

Converts a Promise to a service callback.

function promiseToServiceCallback<T>(promise: Promise<HttpOperationResponse>): (cb: ServiceCallback<T>) => void

Parameters

promise

Promise<HttpOperationResponse>

The Promise of HttpOperationResponse to be converted to a service callback

Returns

(cb: ServiceCallback<T>) => void

A function that takes the service callback (cb: ServiceCallback): void

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[] }): RequestPolicyFactory

Parameters

proxySettings
ProxySettings

ProxySettings to use on each request.

options

{ customNoProxyList?: string[] }

additional settings, for example, custom NO_PROXY patterns

Returns

redirectPolicy(number)

Creates a redirect policy, which sends a repeats the request to a new destination if a response arrives with a "location" header, and a status code between 300 and 307.

function redirectPolicy(maximumRetries?: number): RequestPolicyFactory

Parameters

maximumRetries

number

Maximum number of redirects to follow.

Returns

An instance of the <xref:RedirectPolicy>

serializeObject(unknown)

Utility function that serializes an object that might contain binary information into a plain object, array or a string.

function serializeObject(toSerialize: unknown): any

Parameters

toSerialize

unknown

Returns

any

signingPolicy(ServiceClientCredentials)

Creates a policy that signs outgoing requests by calling to the provided authenticationProvider's signRequest method.

function signingPolicy(authenticationProvider: ServiceClientCredentials): RequestPolicyFactory

Parameters

authenticationProvider
ServiceClientCredentials

The authentication provider.

Returns

An instance of the <xref:SigningPolicy>.

stringifyXML(unknown, SerializerOptions)

Converts given JSON object to XML string

function stringifyXML(obj: unknown, opts?: SerializerOptions): string

Parameters

obj

unknown

JSON object to be converted into XML string

opts
SerializerOptions

Options that govern the parsing of given JSON object

Returns

string

stripRequest(WebResourceLike)

Returns a stripped version of the Http Request that does not contain the Authorization header.

function stripRequest(request: WebResourceLike): WebResourceLike

Parameters

request
WebResourceLike

The Http Request object

Returns

The stripped version of Http Request.

stripResponse(HttpOperationResponse)

Returns a stripped version of the Http Response which only contains body, headers and the status.

function stripResponse(response: HttpOperationResponse): any

Parameters

response
HttpOperationResponse

The Http Response

Returns

any

The stripped version of Http Response.

systemErrorRetryPolicy(number, number, number, number)

A policy that retries when there's a system error, identified by the codes "ETIMEDOUT", "ESOCKETTIMEDOUT", "ECONNREFUSED", "ECONNRESET" or "ENOENT".

function systemErrorRetryPolicy(retryCount?: number, retryInterval?: number, minRetryInterval?: number, maxRetryInterval?: number): RequestPolicyFactory

Parameters

retryCount

number

Maximum number of retries.

retryInterval

number

The client retry interval, in milliseconds.

minRetryInterval

number

The minimum retry interval, in milliseconds.

maxRetryInterval

number

The maximum retry interval, in milliseconds.

Returns

An instance of the <xref:SystemErrorRetryPolicy>

throttlingRetryPolicy()

Creates a policy that re-sends the request if the response indicates the request failed because of throttling reasons. For example, if the response contains a Retry-After header, it will retry sending the request based on the value of that 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(): RequestPolicyFactory

Returns

tracingPolicy(TracingPolicyOptions)

Creates a policy that wraps outgoing requests with a tracing span.

function tracingPolicy(tracingOptions?: TracingPolicyOptions): RequestPolicyFactory

Parameters

tracingOptions
TracingPolicyOptions

Tracing options.

Returns

An instance of the <xref:TracingPolicy> class.

userAgentPolicy(TelemetryInfo)

Returns a policy that adds the user agent header to outgoing requests based on the given TelemetryInfo.

function userAgentPolicy(userAgentData?: TelemetryInfo): RequestPolicyFactory

Parameters

userAgentData
TelemetryInfo

Telemetry information.

Returns

A new <xref:UserAgentPolicy>.