azcore

package module
v0.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 29, 2021 License: MIT Imports: 24 Imported by: 1,326

README

Azure Core Client Module for Go

PkgGoDev Build Status Code Coverage

The azcore module provides a set of common interfaces and types for Go SDK client modules. These modules follow the Azure SDK Design Guidelines for Go.

Getting started

This project uses Go modules for versioning and dependency management.

Typically, you will not need to explicitly install azcore as it will be installed as a client module dependency. To add the latest version to your go.mod file, execute the following command.

go get -u github.com/Azure/azure-sdk-for-go/sdk/azcore

General documentation and examples can be found on pkg.go.dev.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Documentation

Overview

Package azcore implements an HTTP request/response middleware pipeline.

The middleware consists of three components.

  • One or more Policy instances.
  • A Transport instance.
  • A Pipeline instance that combines the Policy and Transport instances.

Implementing the Policy Interface

A Policy can be implemented in two ways; as a first-class function for a stateless Policy, or as a method on a type for a stateful Policy. Note that HTTP requests made via the same pipeline share the same Policy instances, so if a Policy mutates its state it MUST be properly synchronized to avoid race conditions.

A Policy's Do method is called when an HTTP request wants to be sent over the network. The Do method can perform any operation(s) it desires. For example, it can log the outgoing request, mutate the URL, headers, and/or query parameters, inject a failure, etc. Once the Policy has successfully completed its request work, it must call the Next() method on the *azcore.Request instance in order to pass the request to the next Policy in the chain.

When an HTTP response comes back, the Policy then gets a chance to process the response/error. The Policy instance can log the response, retry the operation if it failed due to a transient error or timeout, unmarshal the response body, etc. Once the Policy has successfully completed its response work, it must return the *azcore.Response and error instances to its caller.

Template for implementing a stateless Policy: 

func NewMyStatelessPolicy() Policy {
   return azcore.PolicyFunc(func(req *azcore.Request) (*azcore.Response, error) {
      // TODO: mutate/process Request here

      // forward Request to next Policy & get Response/error
      resp, err := req.Next()

      // TODO: mutate/process Response/error here

      // return Response/error to previous Policy
      return resp, err
   })
}

Template for implementing a stateful Policy: 

type MyStatefulPolicy struct {
   // TODO: add configuration/setting fields here
}

// TODO: add initialization args to NewMyStatefulPolicy()
func NewMyStatefulPolicy() Policy {
   return &MyStatefulPolicy{
      // TODO: initialize configuration/setting fields here
   }
}

func (p *MyStatefulPolicy) Do(req *azcore.Request) (resp *azcore.Response, err error) {
      // TODO: mutate/process Request here

      // forward Request to next Policy & get Response/error
      resp, err := req.Next()

      // TODO: mutate/process Response/error here

      // return Response/error to previous Policy
      return resp, err
}

Implementing the Transport Interface

The Transport interface is responsible for sending the HTTP request and returning the corresponding HTTP response or error. The Transport is invoked by the last Policy in the chain. The default Transport implementation uses a shared http.Client from the standard library.

The same stateful/stateless rules for Policy implementations apply to Transport implementations.

Using Policy and Transport Instances Via a Pipeline

To use the Policy and Transport instances, an application passes them to the NewPipeline function. 

func NewPipeline(transport Transport, policies ...Policy) Pipeline

The specified Policy instances form a chain and are invoked in the order provided to NewPipeline followed by the Transport.

Once the Pipeline has been created, create a Request instance and pass it to Pipeline's Do method. 

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

func (p Pipeline) Do(req *Request) (*Response, error)

The Pipeline.Do method sends the specified Request through the chain of Policy and Transport instances. The response/error is then sent through the same chain of Policy instances in reverse order. For example, assuming there are Policy types PolicyA, PolicyB, and PolicyC along with TransportA. 

pipeline := NewPipeline(TransportA, PolicyA, PolicyB, PolicyC)

The flow of Request and Response looks like the following: 

azcore.Request -> PolicyA -> PolicyB -> PolicyC -> TransportA -----+
                                                                   |
                                                            HTTP(s) endpoint
                                                                   |
caller <--------- PolicyA <- PolicyB <- PolicyC <- azcore.Response-+

Creating a Request Instance

The Request instance passed to Pipeline's Do method is a wrapper around an *http.Request. It also contains some internal state and provides various convenience methods. You create a Request instance by calling the NewRequest function: 

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

If the Request should contain a body, call the SetBody method. 

func (req *Request) SetBody(body ReadSeekCloser, contentType string) error

A seekable stream is required so that upon retry, the retry Policy instance can seek the stream back to the beginning before retrying the network request and re-uploading the body.

Sending an Explicit Null

Operations like JSON-MERGE-PATCH send a JSON null to indicate a value should be deleted. 

{
   "delete-me": null
}

This requirement conflicts with the SDK's default marshalling that specifies "omitempty" as a means to resolve the ambiguity between a field to be excluded and its zero-value. 

type Widget struct {
   Name  *string `json:",omitempty"`
   Count *int    `json:",omitempty"`
}

In the above example, Name and Count are defined as pointer-to-type to disambiguate between a missing value (nil) and a zero-value (0) which might have semantic differences.

In a PATCH operation, any fields left as `nil` are to have their values preserved. When updating a Widget's count, one simply specifies the new value for Count, leaving Name nil.

To fulfill the requirement for sending a JSON null, the NullValue() function can be used. 

w := Widget{
   Count: azcore.NullValue(0).(*int),
}

This sends an explict "null" for Count, indicating that any current value for Count should be deleted.

Processing the Response

When the HTTP response is received, the underlying *http.Response is wrapped in a Response type. The Response type contains various convenience methods, like testing the HTTP response code and unmarshalling the response body in a particular format.

The Response is returned through all the Policy instances. Each Policy instance can inspect/mutate the embedded *http.Response.

Index

Examples

Constants

View Source 
const (
	// UserAgent is the string to be used in the user agent string when making requests.
	UserAgent = "azcore/" + Version

	// Version is the semantic version (see http://semver.org) of this module.
	Version = "v0.18.0"
)

Variables

View Source 
var (
	// ErrNoMorePolicies is returned from Request.Next() if there are no more policies in the pipeline.
	ErrNoMorePolicies = errors.New("no more policies")
)
View Source 
var (
	// StackFrameCount contains the number of stack frames to include when a trace is being collected.
	StackFrameCount = 32
)
View Source 
var (
	// StatusCodesForRetry is the default set of HTTP status code for which the policy will retry.
	// Changing its value will affect future created clients that use the default values.
	StatusCodesForRetry = []int{
		http.StatusRequestTimeout,
		http.StatusInternalServerError,
		http.StatusBadGateway,
		http.StatusServiceUnavailable,
		http.StatusGatewayTimeout,
	}
)

Functions

func DecodeByteArray added in v0.16.2 

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

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

func EncodeByteArray added in v0.16.2 

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

EncodeByteArray will base-64 encode the byte slice v.

func IsNullValue added in v0.14.2 

func IsNullValue(v interface{}) bool

IsNullValue returns true if the field contains a null sentinel value. This is used by custom marshallers to properly encode a null value.

func JoinPaths added in v0.10.0 

func JoinPaths(paths ...string) string

JoinPaths concatenates multiple URL path segments into one path, inserting path separation characters as required.

func NewResponseBodyProgress 

func NewResponseBodyProgress(responseBody io.ReadCloser, pr ProgressReceiver) io.ReadCloser

NewResponseBodyProgress adds progress reporting to an HTTP response's body stream.

func NewResponseError added in v0.11.0 

func NewResponseError(inner error, resp *http.Response) error

NewResponseError wraps the specified error with an error that provides access to an HTTP response. If an HTTP request returns a non-successful status code, wrap the response and the associated error in this error type so that callers can access the underlying *http.Response as required. DO NOT wrap failed HTTP requests that returned an error and no response with this type.

func NullValue added in v0.14.2 

func NullValue(v interface{}) interface{}

NullValue is used to send an explicit 'null' within a request. This is typically used in JSON-MERGE-PATCH operations to delete a value.

Example 
package main

import (
	"encoding/json"
	"fmt"

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

type Widget struct {
	Name  *string `json:",omitempty"`
	Count *int    `json:",omitempty"`
}

func (w Widget) MarshalJSON() ([]byte, error) {
	msg := map[string]interface{}{}
	if azcore.IsNullValue(w.Name) {
		msg["name"] = nil
	} else if w.Name != nil {
		msg["name"] = w.Name
	}
	if azcore.IsNullValue(w.Count) {
		msg["count"] = nil
	} else if w.Count != nil {
		msg["count"] = w.Count
	}
	return json.Marshal(msg)
}

func main() {
	w := Widget{
		Count: azcore.NullValue(0).(*int),
	}
	b, _ := json.Marshal(w)
	fmt.Println(string(b))
}

Output:

{"count":null}

func RetryAfter added in v0.7.0 

func RetryAfter(resp *http.Response) time.Duration

RetryAfter returns non-zero if the response contains a Retry-After header value.

func SetClassifications added in v0.18.0 

func SetClassifications(cls ...LogClassification)

SetClassifications is used to control which classifications are written to the log. By default all log classifications are writen.

func SetListener added in v0.18.0 

func SetListener(lst Listener)

SetListener will set the Logger to write to the specified Listener.

func WithHTTPHeader added in v0.9.3 

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 added in v0.4.0 

func WithRetryOptions(parent context.Context, options 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 AccessToken 

type AccessToken struct {
	Token     string
	ExpiresOn time.Time
}

AccessToken represents an Azure service bearer access token with expiry information.

type AuthenticationOptions added in v0.17.0 

type AuthenticationOptions struct {
	// TokenRequest is a TokenRequestOptions that includes a scopes field which contains
	// the list of OAuth2 authentication scopes used when requesting a token.
	// This field is ignored for other forms of authentication (e.g. shared key).
	TokenRequest TokenRequestOptions
	// AuxiliaryTenants contains a list of additional tenant IDs to be used to authenticate
	// in cross-tenant applications.
	AuxiliaryTenants []string
}

AuthenticationOptions contains various options used to create a credential policy.

type Base64Encoding added in v0.8.0 

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 Credential 

type Credential interface {
	// AuthenticationPolicy returns a policy that requests the credential and applies it to the HTTP request.
	NewAuthenticationPolicy(options AuthenticationOptions) Policy
}

Credential represents any credential type.

func NewAnonymousCredential added in v0.17.0 

func NewAnonymousCredential() Credential

NewAnonymousCredential is for use with HTTP(S) requests that read public resource or for use with Shared Access Signatures (SAS).

type ErrorUnmarshaller added in v0.16.1 

type ErrorUnmarshaller func(*Response) error

ErrorUnmarshaller is the func to invoke when the endpoint returns an error response that requires unmarshalling.

type HTTPResponse added in v0.9.0 

type HTTPResponse interface {
	RawResponse() *http.Response
}

HTTPResponse provides access to an HTTP response when available. Errors returned from failed API calls will implement this interface. Use errors.As() to access this interface in the error chain. If there was no HTTP response then this interface will be omitted from any error in the chain.

type LROPoller added in v0.16.1 

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

LROPoller encapsulates state and logic for polling on long-running operations. NOTE: this is only meant for internal use in generated code.

func NewLROPoller added in v0.16.1 

func NewLROPoller(pollerID string, resp *Response, pl Pipeline, eu ErrorUnmarshaller) (*LROPoller, error)

NewLROPoller creates an LROPoller based on the provided initial response. pollerID - a unique identifier for an LRO. it's usually the client.Method string. NOTE: this is only meant for internal use in generated code.

func NewLROPollerFromResumeToken added in v0.16.1 

func NewLROPollerFromResumeToken(pollerID string, token string, pl Pipeline, eu ErrorUnmarshaller) (*LROPoller, error)

NewLROPollerFromResumeToken creates an LROPoller from a resume token string. pollerID - a unique identifier for an LRO. it's usually the client.Method string. NOTE: this is only meant for internal use in generated code.

func (*LROPoller) Done added in v0.16.1 

func (l *LROPoller) Done() bool

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

func (*LROPoller) FinalResponse added in v0.16.1 

func (l *LROPoller) FinalResponse(ctx context.Context, respType interface{}) (*http.Response, error)

FinalResponse will perform a final GET request and return the final HTTP response for the polling operation and unmarshall the content of the payload into the respType interface that is provided.

func (*LROPoller) Poll added in v0.16.1 

func (l *LROPoller) Poll(ctx context.Context) (*http.Response, error)

Poll sends a polling request to the polling endpoint and returns the response or error.

func (*LROPoller) PollUntilDone added in v0.16.1 

func (l *LROPoller) PollUntilDone(ctx context.Context, freq time.Duration, respType interface{}) (*http.Response, error)

PollUntilDone will handle the entire span of the polling operation until a terminal state is reached, then return the final HTTP response for the polling operation and unmarshal the content of the payload into the respType interface that is provided.

func (*LROPoller) ResumeToken added in v0.16.1 

func (l *LROPoller) ResumeToken() (string, error)

ResumeToken returns a token string that can be used to resume a poller that has not yet reached a terminal state.

type Listener 

type Listener func(LogClassification, string)

Listener is the function signature invoked when writing log entries. A Listener is required to perform its own synchronization if it's expected to be called from multiple Go routines

type LogClassification 

type LogClassification logger.LogClassification

LogClassification is used to group entries. Each group can be toggled on or off 

const (
	// LogRequest entries contain information about HTTP requests.
	// This includes information like the URL, query parameters, and headers.
	LogRequest LogClassification = "Request"

	// LogResponse entries contain information about HTTP responses.
	// This includes information like the HTTP status code, headers, and request URL.
	LogResponse LogClassification = "Response"

	// LogRetryPolicy entries contain information specific to the retry policy in use.
	LogRetryPolicy LogClassification = "RetryPolicy"

	// LogLongRunningOperation entries contain information specific to long-running operations.
	// This includes information like polling location, operation state and sleep intervals.
	LogLongRunningOperation LogClassification = "LongRunningOperation"
)

type LogOptions added in v0.12.0 

type LogOptions struct {
	// IncludeBody indicates if request and response bodies should be included in logging.
	// The default value is false.
	// NOTE: enabling this can lead to disclosure of sensitive information, use with care.
	IncludeBody bool
}

LogOptions configures the logging policy's behavior.

type NonRetriableError added in v0.10.0 

type NonRetriableError interface {
	error
	NonRetriable()
}

NonRetriableError represents a non-transient error. This works in conjunction with the retry policy, indicating that the error condition is idempotent, so no retries will be attempted. Use errors.As() to access this interface in the error chain.

type Pager added in v0.14.1 

type Pager interface {
	// NextPage returns true if the pager advanced to the next page.
	// Returns false if there are no more pages or an error occurred.
	NextPage(context.Context) bool

	// Err returns the last error encountered while paging.
	Err() error
}

Pager provides operations for iterating over paged responses.

type Pipeline 

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

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(transport Transport, policies ...Policy) Pipeline

NewPipeline creates a new Pipeline object from the specified Transport and Policies. If no transport is provided then the default *http.Client transport will be used.

func (Pipeline) Do 

func (p Pipeline) Do(req *Request) (*Response, error)

Do is called for each and every HTTP request. It passes the request through all the Policy objects (which can transform the Request's URL/query parameters/headers) and ultimately sends the transformed HTTP request over the network.

Example 
package main

import (
	"context"
	"fmt"
	"io/ioutil"
	"log"
	"net/http"

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

func main() {
	req, err := azcore.NewRequest(context.Background(), http.MethodGet, "https://github.com/robots.txt")
	if err != nil {
		log.Fatal(err)
	}
	pipeline := azcore.NewPipeline(nil)
	resp, err := pipeline.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	robots, err := ioutil.ReadAll(resp.Body)
	resp.Body.Close()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s", robots)
}

Output:

type Policy 

type Policy interface {
	// Do applies the policy to the specified Request.  When implementing a Policy, mutate the
	// request before calling req.Next() to move on to the next policy, and respond to the result
	// before returning to the caller.
	Do(req *Request) (*Response, error)
}

Policy represents an extensibility point for the Pipeline that can mutate the specified Request and react to the received Response.

func NewLogPolicy added in v0.12.0 

func NewLogPolicy(o *LogOptions) Policy

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

func NewRetryPolicy 

func NewRetryPolicy(o *RetryOptions) 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(o *TelemetryOptions) Policy

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

type PolicyFunc 

type PolicyFunc func(*Request) (*Response, error)

PolicyFunc is a type that implements the Policy interface. Use this type when implementing a stateless policy as a first-class function.

func (PolicyFunc) Do 

func (pf PolicyFunc) Do(req *Request) (*Response, error)

Do implements the Policy interface on PolicyFunc.

type Poller added in v0.14.1 

type Poller interface {
	// Done returns true if the LRO has reached a terminal state.
	Done() bool

	// 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 update 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.
	Poll(context.Context) (*http.Response, 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.
	ResumeToken() (string, error)
}

Poller provides operations for checking the state of a long-running operation. An LRO can be in either a non-terminal or terminal state. A non-terminal state indicates the LRO is still in progress. A terminal state indicates the LRO has completed successfully, failed, or was cancelled.

type ProgressReceiver 

type ProgressReceiver func(bytesTransferred int64)

ProgressReceiver defines the signature of a callback function invoked as progress is reported.

type ReadSeekCloser 

type ReadSeekCloser interface {
	io.ReadCloser
	io.Seeker
}

ReadSeekCloser is the interface that groups the io.ReadCloser and io.Seeker interfaces.

func NewRequestBodyProgress 

func NewRequestBodyProgress(requestBody ReadSeekCloser, pr ProgressReceiver) ReadSeekCloser

NewRequestBodyProgress adds progress reporting to an HTTP request's body stream.

func NopCloser 

func NopCloser(rs io.ReadSeeker) ReadSeekCloser

NopCloser returns a ReadSeekCloser with a no-op close method wrapping the provided io.ReadSeeker.

type Request 

type Request struct {
	*http.Request
	// contains filtered or unexported fields
}

Request is an abstraction over the creation of an HTTP request as it passes through the pipeline. Don't use this type directly, use NewRequest() instead.

func NewRequest 

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

NewRequest creates a new Request with the specified input.

func (*Request) Close 

func (req *Request) Close() error

Close closes the request body.

func (*Request) MarshalAsByteArray added in v0.7.1 

func (req *Request) MarshalAsByteArray(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 (*Request) MarshalAsJSON added in v0.2.0 

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

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

func (*Request) MarshalAsXML 

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

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

func (*Request) Next 

func (req *Request) Next() (*Response, error)

Next calls the next policy in the pipeline. If there are no more policies, nil and ErrNoMorePolicies are returned. This method is intended to be called from pipeline policies. To send a request through a pipeline call Pipeline.Do().

func (*Request) OperationValue 

func (req *Request) OperationValue(value interface{}) bool

OperationValue looks for a value set by SetOperationValue().

func (*Request) RewindBody 

func (req *Request) RewindBody() error

RewindBody seeks the request's Body stream back to the beginning so it can be resent when retrying an operation.

func (*Request) SetBody 

func (req *Request) SetBody(body ReadSeekCloser, contentType string) error

SetBody sets the specified ReadSeekCloser as the HTTP request body.

Example 
package main

import (
	"context"
	"log"
	"net/http"
	"strings"

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

func main() {
	req, err := azcore.NewRequest(context.Background(), http.MethodPut, "https://contoso.com/some/endpoint")
	if err != nil {
		log.Fatal(err)
	}
	body := strings.NewReader("this is seekable content to be uploaded")
	err = req.SetBody(azcore.NopCloser(body), "text/plain")
	if err != nil {
		log.Fatal(err)
	}
}

Output:

func (*Request) SetMultipartFormData added in v0.14.3 

func (req *Request) SetMultipartFormData(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 (*Request) SetOperationValue 

func (req *Request) SetOperationValue(value interface{})

SetOperationValue adds/changes a mutable key/value associated with a single operation.

func (*Request) SkipBodyDownload 

func (req *Request) SkipBodyDownload()

SkipBodyDownload will disable automatic downloading of the response body.

func (*Request) Telemetry added in v0.13.1 

func (req *Request) Telemetry(v string)

Telemetry adds telemetry data to the request. If telemetry reporting is disabled the value is discarded.

type Response 

type Response struct {
	*http.Response
}

Response represents the response from an HTTP request.

func (*Response) Drain 

func (r *Response) Drain()

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

func (*Response) HasStatusCode 

func (r *Response) HasStatusCode(statusCodes ...int) bool

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

func (*Response) Payload 

func (r *Response) Payload() ([]byte, error)

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

func (*Response) UnmarshalAsByteArray added in v0.7.1 

func (r *Response) UnmarshalAsByteArray(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 (*Response) UnmarshalAsJSON added in v0.2.0 

func (r *Response) UnmarshalAsJSON(v interface{}) error

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

func (*Response) UnmarshalAsXML 

func (r *Response) UnmarshalAsXML(v interface{}) error

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

type RetryOptions 

type RetryOptions struct {
	// MaxRetries specifies the maximum number of attempts a failed operation will be retried
	// before producing an error.
	// The default value is three.  A value less than zero means one try and no retries.
	MaxRetries int32

	// TryTimeout indicates the maximum time allowed for any single try of an HTTP request.
	// This is disabled by default.  Specify a value greater than zero to enable.
	// NOTE: Setting this to a small value might cause premature HTTP request time-outs.
	TryTimeout time.Duration

	// RetryDelay specifies the initial amount of delay to use before retrying an operation.
	// The delay increases exponentially with each retry up to the maximum specified by MaxRetryDelay.
	// The default value is four seconds.  A value less than zero means no delay between retries.
	RetryDelay time.Duration

	// MaxRetryDelay specifies the maximum delay allowed before retrying an operation.
	// Typically the value is greater than or equal to the value specified in RetryDelay.
	// The default Value is 120 seconds.  A value less than zero means there is no cap.
	MaxRetryDelay time.Duration

	// StatusCodes specifies the HTTP status codes that indicate the operation should be retried.
	// The default value is the status codes in StatusCodesForRetry.
	// Specifying an empty slice will cause retries to happen only for transport errors.
	StatusCodes []int
}

RetryOptions configures the retry policy's behavior. All zero-value fields will be initialized with their default values.

type TelemetryOptions 

type TelemetryOptions struct {
	// Value is a string prepended to each request's User-Agent and sent to the service.
	// The service records the user-agent in logs for diagnostics and tracking of client requests.
	Value string

	// ApplicationID is an application-specific identification string used in telemetry.
	// It has a maximum length of 24 characters and must not contain any spaces.
	ApplicationID string

	// Disabled will prevent the addition of any telemetry data to the User-Agent.
	Disabled bool
}

TelemetryOptions configures the telemetry policy's behavior.

type TokenCredential 

type TokenCredential interface {
	Credential
	// GetToken requests an access token for the specified set of scopes.
	GetToken(ctx context.Context, options TokenRequestOptions) (*AccessToken, error)
}

TokenCredential represents a credential capable of providing an OAuth token.

type TokenRequestOptions 

type TokenRequestOptions struct {
	// Scopes contains the list of permission scopes required for the token.
	Scopes []string
	// TenantID contains the tenant ID to use in a multi-tenant authentication scenario, if TenantID is set
	// it will override the tenant ID that was added at credential creation time.
	TenantID string
}

TokenRequestOptions contain specific parameter that may be used by credentials types when attempting to get a token.

type Transport 

type Transport interface {
	// Do sends the HTTP request and returns the HTTP response or error.
	Do(req *http.Request) (*http.Response, error)
}

Transport represents an HTTP pipeline transport used to send HTTP requests and receive responses.

type TransportFunc added in v0.5.0 

type TransportFunc func(*http.Request) (*http.Response, error)

TransportFunc is a type that implements the Transport interface. Use this type when implementing a stateless transport as a first-class function.

func (TransportFunc) Do added in v0.5.0 

func (tf TransportFunc) Do(req *http.Request) (*http.Response, error)

Do implements the Transport interface on TransportFunc.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.