Documentation
¶
Overview ¶
Package option contains options for Google API clients.
Index ¶
- type ClientCertSource
- type ClientOption
- func ImpersonateCredentials(target string, delegates ...string) ClientOptiondeprecated
- func WithAPIKey(apiKey string) ClientOption
- func WithAudiences(audience ...string) ClientOption
- func WithAuthCredentials(creds *auth.Credentials) ClientOption
- func WithClientCertSource(s ClientCertSource) ClientOption
- func WithCredentials(creds *google.Credentials) ClientOption
- func WithCredentialsFile(filename string) ClientOption
- func WithCredentialsJSON(p []byte) ClientOption
- func WithEndpoint(url string) ClientOption
- func WithGRPCConn(conn *grpc.ClientConn) ClientOption
- func WithGRPCConnectionPool(size int) ClientOption
- func WithGRPCDialOption(opt grpc.DialOption) ClientOption
- func WithHTTPClient(client *http.Client) ClientOption
- func WithQuotaProject(quotaProject string) ClientOption
- func WithRequestReason(requestReason string) ClientOption
- func WithScopes(scope ...string) ClientOption
- func WithServiceAccountFile(filename string) ClientOptiondeprecated
- func WithTelemetryDisabled() ClientOption
- func WithTokenSource(s oauth2.TokenSource) ClientOption
- func WithUniverseDomain(ud string) ClientOption
- func WithUserAgent(ua string) ClientOption
- func WithoutAuthentication() ClientOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ClientCertSource ¶ added in v0.18.0
type ClientCertSource = func(*tls.CertificateRequestInfo) (*tls.Certificate, error)
ClientCertSource is a function that returns a TLS client certificate to be used when opening TLS connections.
It follows the same semantics as crypto/tls.Config.GetClientCertificate.
This is an EXPERIMENTAL API and may be changed or removed in the future.
type ClientOption ¶
type ClientOption interface {
Apply(*internal.DialSettings)
}
A ClientOption is an option for a Google API client.
func ImpersonateCredentials
deprecated
added in
v0.32.0
func ImpersonateCredentials(target string, delegates ...string) ClientOption
ImpersonateCredentials returns a ClientOption that will impersonate the target service account.
In order to impersonate the target service account the base service account must have the Service Account Token Creator role, roles/iam.serviceAccountTokenCreator, on the target service account. See https://cloud.google.com/iam/docs/understanding-service-accounts.
Optionally, delegates can be used during impersonation if the base service account lacks the token creator role on the target. When using delegates, each service account must be granted roles/iam.serviceAccountTokenCreator on the next service account in the chain.
For example, if a base service account of SA1 is trying to impersonate target service account SA2 while using delegate service accounts DSA1 and DSA2, the following must be true:
- Base service account SA1 has roles/iam.serviceAccountTokenCreator on DSA1.
- DSA1 has roles/iam.serviceAccountTokenCreator on DSA2.
- DSA2 has roles/iam.serviceAccountTokenCreator on target SA2.
The resulting impersonated credential will either have the default scopes of the client being instantiating or the scopes from WithScopes if provided. Scopes are required for creating impersonated credentials, so if this option is used while not using a NewClient/NewService function, WithScopes must also be explicitly passed in as well.
If the base credential is an authorized user and not a service account, or if the option WithQuotaProject is set, the target service account must have a role that grants the serviceusage.services.use permission such as roles/serviceusage.serviceUsageConsumer.
This is an EXPERIMENTAL API and may be changed or removed in the future.
Deprecated: This option has been replaced by `impersonate` package: `google.golang.org/api/impersonate`. Please use the `impersonate` package instead with the WithTokenSource option.
func WithAPIKey ¶
func WithAPIKey(apiKey string) ClientOption
WithAPIKey returns a ClientOption that specifies an API key to be used as the basis for authentication.
API Keys can only be used for JSON-over-HTTP APIs, including those under the import path google.golang.org/api/....
func WithAudiences ¶ added in v0.2.0
func WithAudiences(audience ...string) ClientOption
WithAudiences returns a ClientOption that specifies an audience to be used as the audience field ("aud") for the JWT token authentication.
func WithAuthCredentials ¶ added in v0.174.0
func WithAuthCredentials(creds *auth.Credentials) ClientOption
WithAuthCredentials returns a ClientOption that specifies an cloud.google.com/go/auth.Credentials to be used as the basis for authentication.
func WithClientCertSource ¶ added in v0.18.0
func WithClientCertSource(s ClientCertSource) ClientOption
WithClientCertSource returns a ClientOption that specifies a callback function for obtaining a TLS client certificate.
This option is used for supporting mTLS authentication, where the server validates the client certifcate when establishing a connection.
The callback function will be invoked whenever the server requests a certificate from the client. Implementations of the callback function should try to ensure that a valid certificate can be repeatedly returned on demand for the entire life cycle of the transport client. If a nil Certificate is returned (i.e. no Certificate can be obtained), an error should be returned.
This is an EXPERIMENTAL API and may be changed or removed in the future.
func WithCredentials ¶
func WithCredentials(creds *google.Credentials) ClientOption
WithCredentials returns a ClientOption that authenticates API calls.
func WithCredentialsFile ¶
func WithCredentialsFile(filename string) ClientOption
WithCredentialsFile returns a ClientOption that authenticates API calls with the given service account or refresh token JSON credentials file.
func WithCredentialsJSON ¶
func WithCredentialsJSON(p []byte) ClientOption
WithCredentialsJSON returns a ClientOption that authenticates API calls with the given service account or refresh token JSON credentials.
func WithEndpoint ¶
func WithEndpoint(url string) ClientOption
WithEndpoint returns a ClientOption that overrides the default endpoint to be used for a service.
func WithGRPCConn ¶
func WithGRPCConn(conn *grpc.ClientConn) ClientOption
WithGRPCConn returns a ClientOption that specifies the gRPC client connection to use as the basis of communications. This option may only be used with services that support gRPC as their communication transport. When used, the WithGRPCConn option takes precedent over all other supplied options.
func WithGRPCConnectionPool ¶
func WithGRPCConnectionPool(size int) ClientOption
WithGRPCConnectionPool returns a ClientOption that creates a pool of gRPC connections that requests will be balanced between.
func WithGRPCDialOption ¶
func WithGRPCDialOption(opt grpc.DialOption) ClientOption
WithGRPCDialOption returns a ClientOption that appends a new grpc.DialOption to an underlying gRPC dial. It does not work with WithGRPCConn.
func WithHTTPClient ¶
func WithHTTPClient(client *http.Client) ClientOption
WithHTTPClient returns a ClientOption that specifies the HTTP client to use as the basis of communications. This option may only be used with services that support HTTP as their communication transport. When used, the WithHTTPClient option takes precedent over all other supplied options.
func WithQuotaProject ¶ added in v0.2.0
func WithQuotaProject(quotaProject string) ClientOption
WithQuotaProject returns a ClientOption that specifies the project used for quota and billing purposes.
For more information please read: https://cloud.google.com/apis/docs/system-parameters
func WithRequestReason ¶ added in v0.2.0
func WithRequestReason(requestReason string) ClientOption
WithRequestReason returns a ClientOption that specifies a reason for making the request, which is intended to be recorded in audit logging. An example reason would be a support-case ticket number.
For more information please read: https://cloud.google.com/apis/docs/system-parameters
func WithScopes ¶
func WithScopes(scope ...string) ClientOption
WithScopes returns a ClientOption that overrides the default OAuth2 scopes to be used for a service.
If both WithScopes and WithTokenSource are used, scope settings from the token source will be used instead.
func WithServiceAccountFile
deprecated
func WithServiceAccountFile(filename string) ClientOption
WithServiceAccountFile returns a ClientOption that uses a Google service account credentials file to authenticate.
Deprecated: Use WithCredentialsFile instead.
func WithTelemetryDisabled ¶ added in v0.14.0
func WithTelemetryDisabled() ClientOption
WithTelemetryDisabled returns a ClientOption that disables default telemetry (OpenCensus) settings on gRPC and HTTP clients. An example reason would be to bind custom telemetry that overrides the defaults.
func WithTokenSource ¶
func WithTokenSource(s oauth2.TokenSource) ClientOption
WithTokenSource returns a ClientOption that specifies an OAuth2 token source to be used as the basis for authentication.
func WithUniverseDomain ¶ added in v0.153.0
func WithUniverseDomain(ud string) ClientOption
WithUniverseDomain returns a ClientOption that sets the universe domain.
func WithUserAgent ¶
func WithUserAgent(ua string) ClientOption
WithUserAgent returns a ClientOption that sets the User-Agent. This option is incompatible with the WithHTTPClient option. If you wish to provide a custom client you will need to add this header via RoundTripper middleware.
func WithoutAuthentication ¶
func WithoutAuthentication() ClientOption
WithoutAuthentication returns a ClientOption that specifies that no authentication should be used. It is suitable only for testing and for accessing public resources, like public Google Cloud Storage buckets. It is an error to provide both WithoutAuthentication and any of WithAPIKey, WithTokenSource, WithCredentialsFile or WithServiceAccountFile.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package internaloption contains options used internally by Google client code.
|
Package internaloption contains options used internally by Google client code. |