package runtime

import "github.com/Azure/azure-sdk-for-go/sdk/azcore/runtime"

Package runtime contains various facilities for creating requests and handling responses. The content is intended for SDK authors.

Index ¶

• Constants
• func DecodeByteArray(s string, v *[]byte, format Base64Encoding) error
• func Drain(resp *http.Response)
• func EncodeByteArray(v []byte, format Base64Encoding) string
• func HasStatusCode(resp *http.Response, statusCodes ...int) bool
• func JoinPaths(root string, paths ...string) string
• func MarshalAsByteArray(req *policy.Request, v []byte, format Base64Encoding) error
• func MarshalAsJSON(req *policy.Request, v interface{}) error
• func MarshalAsXML(req *policy.Request, v interface{}) error
• func NewLogPolicy(o *policy.LogOptions) policy.Policy
• func NewRequest(ctx context.Context, httpMethod string, endpoint string) (*pipeline.Request, error)
• func NewRequestIdPolicy() policy.Policy
• func NewResponseError(resp *http.Response) error
• func NewRetryPolicy(o *policy.RetryOptions) policy.Policy
• func NewTelemetryPolicy(mod, ver string, o *policy.TelemetryOptions) policy.Policy
• func Payload(resp *http.Response) ([]byte, error)
• func SetMultipartFormData(req *policy.Request, formData map[string]interface{}) error
• func SkipBodyDownload(req *policy.Request)
• func UnmarshalAsByteArray(resp *http.Response, v *[]byte, format Base64Encoding) error
• func UnmarshalAsJSON(resp *http.Response, v interface{}) error
• func UnmarshalAsXML(resp *http.Response, v interface{}) error
• func WithCaptureResponse(parent context.Context, resp **http.Response) context.Context
• func WithHTTPHeader(parent context.Context, header http.Header) context.Context
• func WithRetryOptions(parent context.Context, options policy.RetryOptions) context.Context
• type Base64Encoding
• type BearerTokenPolicy
• func NewBearerTokenPolicy(cred shared.TokenCredential, scopes []string, opts *policy.BearerTokenOptions) *BearerTokenPolicy
• func (b *BearerTokenPolicy) Do(req *policy.Request) (*http.Response, error)
• type FinalStateVia
• type NewPollerFromResumeTokenOptions
• type NewPollerOptions
• type PageProcessor
• type Pager
• func NewPager[T any](processor PageProcessor[T]) *Pager[T]
• func (p *Pager[T]) More() bool
• func (p *Pager[T]) NextPage(ctx context.Context) (T, error)
• func (p *Pager[T]) UnmarshalJSON(data []byte) error
• type Pipeline
• func NewPipeline(module, version string, plOpts PipelineOptions, options *policy.ClientOptions) Pipeline
• type PipelineOptions
• type Poller
• func NewPoller[T any](resp *http.Response, pl pipeline.Pipeline, options *NewPollerOptions[T]) (*Poller[T], error)
• func NewPollerFromResumeToken[T any](token string, pl pipeline.Pipeline, options *NewPollerFromResumeTokenOptions[T]) (*Poller[T], error)
• func (p *Poller[T]) Done() bool
• func (p *Poller[T]) Poll(ctx context.Context) (*http.Response, error)
• func (p *Poller[T]) PollUntilDone(ctx context.Context, freq time.Duration) (T, error)
• func (p *Poller[T]) Result(ctx context.Context) (T, error)
• func (p *Poller[T]) ResumeToken() (string, error)

Examples ¶

• WithCaptureResponse

Constants ¶

const (
	// FinalStateViaAzureAsyncOp indicates the final payload comes from the Azure-AsyncOperation URL.
	FinalStateViaAzureAsyncOp = pollers.FinalStateViaAzureAsyncOp

	// FinalStateViaLocation indicates the final payload comes from the Location URL.
	FinalStateViaLocation = pollers.FinalStateViaLocation

	// FinalStateViaOriginalURI indicates the final payload comes from the original URL.
	FinalStateViaOriginalURI = pollers.FinalStateViaOriginalURI

	// FinalStateViaOpLocation indicates the final payload comes from the Operation-Location URL.
	FinalStateViaOpLocation = pollers.FinalStateViaOpLocation
)

Functions ¶

func DecodeByteArray ¶

func DecodeByteArray(s string, v *[]byte, format Base64Encoding) error

DecodeByteArray will base-64 decode the provided string into v.

func Drain ¶

func Drain(resp *http.Response)

Drain reads the response body to completion then closes it. The bytes read are discarded.

func EncodeByteArray ¶

func EncodeByteArray(v []byte, format Base64Encoding) string

EncodeByteArray will base-64 encode the byte slice v.

func HasStatusCode ¶

func HasStatusCode(resp *http.Response, statusCodes ...int) bool

HasStatusCode returns true if the Response's status code is one of the specified values.

func JoinPaths ¶

func JoinPaths(root string, paths ...string) string

JoinPaths concatenates multiple URL path segments into one path, inserting path separation characters as required. JoinPaths will preserve query parameters in the root path

func MarshalAsByteArray ¶

func MarshalAsByteArray(req *policy.Request, v []byte, format Base64Encoding) error

MarshalAsByteArray will base-64 encode the byte slice v, then calls SetBody. The encoded value is treated as a JSON string.

func MarshalAsJSON ¶

func MarshalAsJSON(req *policy.Request, v interface{}) error

MarshalAsJSON calls json.Marshal() to get the JSON encoding of v then calls SetBody.

func MarshalAsXML ¶

func MarshalAsXML(req *policy.Request, v interface{}) error

MarshalAsXML calls xml.Marshal() to get the XML encoding of v then calls SetBody.

func NewLogPolicy ¶

func NewLogPolicy(o *policy.LogOptions) policy.Policy

NewLogPolicy creates a request/response logging policy object configured using the specified options. Pass nil to accept the default values; this is the same as passing a zero-value options.

func NewRequest ¶

func NewRequest(ctx context.Context, httpMethod string, endpoint string) (*pipeline.Request, error)

NewRequest creates a new policy.Request with the specified input.

func NewRequestIdPolicy ¶

func NewRequestIdPolicy() policy.Policy

NewRequestIdPolicy returns a policy that add the x-ms-client-request-id header

func NewResponseError ¶

func NewResponseError(resp *http.Response) error

NewResponseError creates an *azcore.ResponseError from the provided HTTP response. Call this when a service request returns a non-successful status code.

func NewRetryPolicy ¶

func NewRetryPolicy(o *policy.RetryOptions) policy.Policy

NewRetryPolicy creates a policy object configured using the specified options. Pass nil to accept the default values; this is the same as passing a zero-value options.

func NewTelemetryPolicy ¶

func NewTelemetryPolicy(mod, ver string, o *policy.TelemetryOptions) policy.Policy

NewTelemetryPolicy creates a telemetry policy object that adds telemetry information to outgoing HTTP requests. The format is [<application_id> ]azsdk-go-<mod>/<ver> <platform_info>. Pass nil to accept the default values; this is the same as passing a zero-value options.

func Payload ¶

func Payload(resp *http.Response) ([]byte, error)

Payload reads and returns the response body or an error. On a successful read, the response body is cached. Subsequent reads will access the cached value.

func SetMultipartFormData ¶

func SetMultipartFormData(req *policy.Request, formData map[string]interface{}) error

SetMultipartFormData writes the specified keys/values as multi-part form fields with the specified value. File content must be specified as a ReadSeekCloser. All other values are treated as string values.

func SkipBodyDownload ¶

func SkipBodyDownload(req *policy.Request)

SkipBodyDownload will disable automatic downloading of the response body.

func UnmarshalAsByteArray ¶

func UnmarshalAsByteArray(resp *http.Response, v *[]byte, format Base64Encoding) error

UnmarshalAsByteArray will base-64 decode the received payload and place the result into the value pointed to by v.

func UnmarshalAsJSON ¶

func UnmarshalAsJSON(resp *http.Response, v interface{}) error

UnmarshalAsJSON calls json.Unmarshal() to unmarshal the received payload into the value pointed to by v.

func UnmarshalAsXML ¶

func UnmarshalAsXML(resp *http.Response, v interface{}) error

UnmarshalAsXML calls xml.Unmarshal() to unmarshal the received payload into the value pointed to by v.

func WithCaptureResponse ¶

func WithCaptureResponse(parent context.Context, resp **http.Response) context.Context

WithCaptureResponse applies the HTTP response retrieval annotation to the parent context. The resp parameter will contain the HTTP response after the request has completed.

{
	var respFromCtx *http.Response
	WithCaptureResponse(context.Background(), &respFromCtx)
}

func WithHTTPHeader ¶

func WithHTTPHeader(parent context.Context, header http.Header) context.Context

WithHTTPHeader adds the specified http.Header to the parent context. Use this to specify custom HTTP headers at the API-call level. Any overlapping headers will have their values replaced with the values specified here.

func WithRetryOptions ¶

func WithRetryOptions(parent context.Context, options policy.RetryOptions) context.Context

WithRetryOptions adds the specified RetryOptions to the parent context. Use this to specify custom RetryOptions at the API-call level.

Types ¶

type Base64Encoding ¶

type Base64Encoding int

Base64Encoding is usesd to specify which base-64 encoder/decoder to use when encoding/decoding a slice of bytes to/from a string.

const (
	// Base64StdFormat uses base64.StdEncoding for encoding and decoding payloads.
	Base64StdFormat Base64Encoding = 0

	// Base64URLFormat uses base64.RawURLEncoding for encoding and decoding payloads.
	Base64URLFormat Base64Encoding = 1
)

type BearerTokenPolicy ¶

type BearerTokenPolicy struct {
	// contains filtered or unexported fields
}

BearerTokenPolicy authorizes requests with bearer tokens acquired from a TokenCredential.

func NewBearerTokenPolicy ¶

func NewBearerTokenPolicy(cred shared.TokenCredential, scopes []string, opts *policy.BearerTokenOptions) *BearerTokenPolicy

NewBearerTokenPolicy creates a policy object that authorizes requests with bearer tokens. cred: an azcore.TokenCredential implementation such as a credential object from azidentity scopes: the list of permission scopes required for the token. opts: optional settings. Pass nil to accept default values; this is the same as passing a zero-value options.

func (*BearerTokenPolicy) Do ¶

func (b *BearerTokenPolicy) Do(req *policy.Request) (*http.Response, error)

Do authorizes a request with a bearer token

type FinalStateVia ¶

type FinalStateVia = pollers.FinalStateVia

FinalStateVia is the enumerated type for the possible final-state-via values.

type NewPollerFromResumeTokenOptions ¶

type NewPollerFromResumeTokenOptions[T any] struct {
	// Response contains a preconstructed response type.
	// The final payload will be unmarshaled into it and returned.
	Response *T
}

NewPollerFromResumeTokenOptions contains the optional parameters for NewPollerFromResumeToken.

type NewPollerOptions ¶

type NewPollerOptions[T any] struct {
	// FinalStateVia contains the final-state-via value for the LRO.
	FinalStateVia FinalStateVia

	// Response contains a preconstructed response type.
	// The final payload will be unmarshaled into it and returned.
	Response *T
}

NewPollerOptions contains the optional parameters for NewPoller.

type PageProcessor ¶

type PageProcessor[T any] struct {
	// More returns a boolean indicating if there are more pages to fetch.
	// It uses the provided page to make the determination.
	More func(T) bool

	// Fetcher fetches the first and subsequent pages.
	Fetcher func(context.Context, *T) (T, error)
}

PageProcessor contains the required data for constructing a Pager.

type Pager ¶

type Pager[T any] struct {
	// contains filtered or unexported fields
}

Pager provides operations for iterating over paged responses.

func NewPager ¶

func NewPager[T any](processor PageProcessor[T]) *Pager[T]

NewPager creates an instance of Pager using the specified PageProcessor. Pass a non-nil T for firstPage if the first page has already been retrieved.

func (*Pager[T]) More ¶

func (p *Pager[T]) More() bool

More returns true if there are more pages to retrieve.

func (*Pager[T]) NextPage ¶

func (p *Pager[T]) NextPage(ctx context.Context) (T, error)

NextPage advances the pager to the next page.

func (*Pager[T]) UnmarshalJSON ¶

func (p *Pager[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for Pager[T].

type Pipeline ¶

type Pipeline = pipeline.Pipeline

Pipeline represents a primitive for sending HTTP requests and receiving responses. Its behavior can be extended by specifying policies during construction.

func NewPipeline ¶

func NewPipeline(module, version string, plOpts PipelineOptions, options *policy.ClientOptions) Pipeline

NewPipeline creates a pipeline from connection options, with any additional policies as specified. module, version: used by the telemetry policy, when enabled perCall: additional policies to invoke once per request perRetry: additional policies to invoke once per request and once per retry of that request

type PipelineOptions ¶

type PipelineOptions struct {
	AllowedHeaders, AllowedQueryParameters []string
	PerCall, PerRetry                      []policy.Policy
}

PipelineOptions contains Pipeline options for SDK developers

type Poller ¶

type Poller[T any] struct {
	// contains filtered or unexported fields
}

Poller encapsulates a long-running operation, providing polling facilities until the operation reaches a terminal state.

func NewPoller ¶

func NewPoller[T any](resp *http.Response, pl pipeline.Pipeline, options *NewPollerOptions[T]) (*Poller[T], error)

NewPoller creates a Poller based on the provided initial response.

func NewPollerFromResumeToken ¶

func NewPollerFromResumeToken[T any](token string, pl pipeline.Pipeline, options *NewPollerFromResumeTokenOptions[T]) (*Poller[T], error)

NewPollerFromResumeToken creates a Poller from a resume token string.

func (*Poller[T]) Done ¶

func (p *Poller[T]) Done() bool

Done returns true if the LRO has reached a terminal state.

func (*Poller[T]) Poll ¶

func (p *Poller[T]) Poll(ctx context.Context) (*http.Response, error)

Poll fetches the latest state of the LRO. It returns an HTTP response or error. If the LRO has completed successfully, the poller's state is updated and the HTTP response is returned. If the LRO has completed with failure or was cancelled, the poller's state is updated and the error is returned. If the LRO has not reached a terminal state, the poller's state is updated and the latest HTTP response is returned. If Poll fails, the poller's state is unmodified and the error is returned. Calling Poll on an LRO that has reached a terminal state will return the final HTTP response or error.

func (*Poller[T]) PollUntilDone ¶

func (p *Poller[T]) PollUntilDone(ctx context.Context, freq time.Duration) (T, error)

PollUntilDone will poll the service endpoint until a terminal state is reached, an error is received, or the context expires. freq: the time to wait between intervals in absence of a Retry-After header. Allowed minimum is one second.

func (*Poller[T]) Result ¶

func (p *Poller[T]) Result(ctx context.Context) (T, error)

Result returns the result of the LRO and is meant to be used in conjunction with Poll and Done. Calling this on an LRO in a non-terminal state will return an error.

func (*Poller[T]) ResumeToken ¶

func (p *Poller[T]) ResumeToken() (string, error)

ResumeToken returns a value representing the poller that can be used to resume the LRO at a later time. ResumeTokens are unique per service operation.

Source Files ¶

doc.go errors.go pager.go pipeline.go policy_bearer_token.go policy_body_download.go policy_http_header.go policy_include_response.go policy_logging.go policy_request_id.go policy_retry.go policy_telemetry.go poller.go request.go response.go transport_default_http_client.go