@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 |
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: |
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 |
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 |
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 |
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 |
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
apply |
Applies the properties on the prototype of sourceCtors to the prototype of targetCtor |
bearer |
Creates a new factory for a RequestPolicy that applies a bearer token to
the requests' |
create |
Creates an HTTP pipeline based on the given options. |
delay(number, Delay |
A wrapper for setTimeout that resolves a promise after timeInMs milliseconds. |
deserialization |
Create a new serialization RequestPolicyCreator that will serialized HTTP request bodies as they pass through the HTTP pipeline. |
deserialize |
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. |
disable |
Returns a request policy factory that can be used to create an instance of <xref:DisableResponseDecompressionPolicy>. |
encode |
Encodes an URI. |
execute |
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! |
exponential |
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. |
flatten |
Parses an HttpOperationResponse into a normalized HTTP response object (RestResponse). |
generate |
Creates a policy that assigns a unique request id to outgoing requests. |
generate |
Generated UUID |
get |
Converts a given URL of a proxy server into |
get |
The default approach to generate user agents. Uses static information from this package, plus system information available from the runtime. |
is |
Indicates whether the given string is in ISO 8601 format. |
is |
Tests an object to determine whether it implements TokenCredential. |
is |
Validates the given uuid as a string |
keep |
Creates a policy that controls whether HTTP connections are maintained on future requests. |
log |
Creates a policy that logs information about the outgoing request and the incoming responses. |
operation |
Converts an OperationOptions to a RequestOptionsBase |
parseXML(string, Serializer |
Converts given XML string into JSON |
promise |
Converts a Promise to a callback. |
promise |
Converts a Promise to a service callback. |
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 |
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. |
serialize |
Utility function that serializes an object that might contain binary information into a plain object, array or a string. |
signing |
Creates a policy that signs outgoing requests by calling to the provided |
stringifyXML(unknown, Serializer |
Converts given JSON object to XML string |
strip |
Returns a stripped version of the Http Request that does not contain the Authorization header. |
strip |
Returns a stripped version of the Http Response which only contains body, headers and the status. |
system |
A policy that retries when there's a system error, identified by the codes "ETIMEDOUT", "ESOCKETTIMEDOUT", "ECONNREFUSED", "ECONNRESET" or "ENOENT". |
throttling |
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 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 |
tracing |
Creates a policy that wraps outgoing requests with a tracing span. |
user |
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
Promise<HttpOperationResponse>
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>.