option
package
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
Stable versionWhen a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
Documentation¶
Overview¶
Package option contains options for Google API clients.
Index¶
- Constants
- 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 WithAuthCredentialsFile(credType CredentialsType, filename string) ClientOption
- func WithAuthCredentialsJSON(credType CredentialsType, json []byte) ClientOption
- func WithClientCertSource(s ClientCertSource) ClientOption
- func WithCredentials(creds *google.Credentials) ClientOption
- func WithCredentialsFile(filename string) ClientOptiondeprecated
- func WithCredentialsJSON(p []byte) ClientOptiondeprecated
- 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 WithLogger(l *slog.Logger) 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
- type CredentialsType
Constants¶
const (// ServiceAccount represents a service account file type.ServiceAccount =credentialstype.ServiceAccount// AuthorizedUser represents an authorized user credentials file type.AuthorizedUser =credentialstype.AuthorizedUser// ImpersonatedServiceAccount represents an impersonated service account file type.//// IMPORTANT:// This credential type does not validate the credential configuration. A security// risk occurs when a credential configuration configured with malicious urls// is used.// You should validate credential configurations provided by untrusted sources.// See [Security requirements when using credential configurations from an external// source]https://cloud.google.com/docs/authentication/external/externally-sourced-credentials// for more details.ImpersonatedServiceAccount =credentialstype.ImpersonatedServiceAccount// ExternalAccount represents an external account file type.//// IMPORTANT:// This credential type does not validate the credential configuration. A security// risk occurs when a credential configuration configured with malicious urls// is used.// You should validate credential configurations provided by untrusted sources.// See [Security requirements when using credential configurations from an external// source]https://cloud.google.com/docs/authentication/external/externally-sourced-credentials// for more details.ExternalAccount =credentialstype.ExternalAccount)
Variables¶
This section is empty.
Functions¶
This section is empty.
Types¶
typeClientCertSource¶added inv0.18.0
type ClientCertSource = func(*tls.CertificateRequestInfo) (*tls.Certificate,error)
ClientCertSource is a function that returns a TLS client certificate to be usedwhen 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.
typeClientOption¶
type ClientOption interface {Apply(*internal.DialSettings)}A ClientOption is an option for a Google API client.
funcImpersonateCredentialsdeprecatedadded inv0.32.0
func ImpersonateCredentials(targetstring, delegates ...string)ClientOption
ImpersonateCredentials returns a ClientOption that will impersonate thetarget service account.
In order to impersonate the target service accountthe base service account must have the Service Account Token Creator role,roles/iam.serviceAccountTokenCreator, on the target service account.Seehttps://cloud.google.com/iam/docs/understanding-service-accounts.
Optionally, delegates can be used during impersonation if the base serviceaccount lacks the token creator role on the target. When using delegates,each service account must be granted roles/iam.serviceAccountTokenCreatoron the next service account in the chain.
For example, if a base service account of SA1 is trying to impersonate targetservice account SA2 while using delegate service accounts DSA1 and DSA2,the following must be true:
- Base service account SA1 has roles/iam.serviceAccountTokenCreator onDSA1.
- 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 ofthe client being instantiating or the scopes from WithScopes if provided.Scopes are required for creating impersonated credentials, so if this optionis used while not using a NewClient/NewService function, WithScopes must alsobe explicitly passed in as well.
If the base credential is an authorized user and not a service account, or ifthe option WithQuotaProject is set, the target service account must have arole that grants the serviceusage.services.use permission such asroles/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` packageinstead with the WithTokenSource option.
funcWithAPIKey¶
func WithAPIKey(apiKeystring)ClientOption
WithAPIKey returns a ClientOption that specifies an API key to be usedas the basis for authentication.
API Keys can only be used for JSON-over-HTTP APIs, including those underthe import path google.golang.org/api/....
funcWithAudiences¶added inv0.2.0
func WithAudiences(audience ...string)ClientOption
WithAudiences returns a ClientOption that specifies an audience to be usedas the audience field ("aud") for the JWT token authentication.
funcWithAuthCredentials¶added inv0.174.0
func WithAuthCredentials(creds *auth.Credentials)ClientOption
WithAuthCredentials returns a ClientOption that specifies ancloud.google.com/go/auth.Credentials to be used as the basis forauthentication.
funcWithAuthCredentialsFile¶added inv0.258.0
func WithAuthCredentialsFile(credTypeCredentialsType, filenamestring)ClientOption
WithAuthCredentialsFile returns a ClientOption that authenticates API callswith the given JSON credentials file and credential type.
Important: If you accept a credential configuration (credentialJSON/File/Stream) from an external source for authentication to GoogleCloud Platform, you must validate it before providing it to any GoogleAPI or library. Providing an unvalidated credential configuration toGoogle APIs can compromise the security of your systems and data. Formore information, refer to [Validate credential configurations fromexternal sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
funcWithAuthCredentialsJSON¶added inv0.258.0
func WithAuthCredentialsJSON(credTypeCredentialsType, json []byte)ClientOption
WithAuthCredentialsJSON returns a ClientOption that authenticates API callswith the given JSON credentials and credential type.
Important: If you accept a credential configuration (credentialJSON/File/Stream) from an external source for authentication to GoogleCloud Platform, you must validate it before providing it to any GoogleAPI or library. Providing an unvalidated credential configuration toGoogle APIs can compromise the security of your systems and data. Formore information, refer to [Validate credential configurations fromexternal sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
funcWithClientCertSource¶added inv0.18.0
func WithClientCertSource(sClientCertSource)ClientOption
WithClientCertSource returns a ClientOption that specifies acallback function for obtaining a TLS client certificate.
This option is used for supporting mTLS authentication, where theserver validates the client certifcate when establishing a connection.
The callback function will be invoked whenever the server requests acertificate from the client. Implementations of the callback functionshould try to ensure that a valid certificate can be repeatedly returnedon demand for the entire life cycle of the transport client. If a nilCertificate is returned (i.e. no Certificate can be obtained), an errorshould be returned.
This is an EXPERIMENTAL API and may be changed or removed in the future.
funcWithCredentials¶
func WithCredentials(creds *google.Credentials)ClientOption
WithCredentials returns a ClientOption that authenticates API calls.
funcWithCredentialsFiledeprecated
func WithCredentialsFile(filenamestring)ClientOption
WithCredentialsFile returns a ClientOption that authenticatesAPI calls with the given service account or refresh token JSONcredentials file.
Deprecated: This function is being deprecated because of a potential security risk.
This function does not validate the credential configuration. The securityrisk occurs when a credential configuration is accepted from a source thatis not under your control and used without validation on your side.
If you know that you will be loading credential configurations of aspecific type, it is recommended to use a credential-type-specificoption function.This will ensure that an unexpected credential type with potential formalicious intent is not loaded unintentionally. You might still have to dovalidation for certain credential types. Please follow the recommendationfor that function. For example, if you want to load only service accounts,you can useWithAuthCredentialsFile withServiceAccount:
option.WithAuthCredentialsFile(option.ServiceAccount, "/path/to/file.json")
If you are loading your credential configuration from an untrusted source and havenot mitigated the risks (e.g. by validating the configuration yourself), makethese changes as soon as possible to prevent security risks to your environment.
Regardless of the function used, it is always your responsibility to validateconfigurations received from external sources.
funcWithCredentialsJSONdeprecated
func WithCredentialsJSON(p []byte)ClientOption
WithCredentialsJSON returns a ClientOption that authenticatesAPI calls with the given service account or refresh token JSONcredentials.
Deprecated: This function is being deprecated because of a potential security risk.
This function does not validate the credential configuration. The securityrisk occurs when a credential configuration is accepted from a source thatis not under your control and used without validation on your side.
If you know that you will be loading credential configurations of aspecific type, it is recommended to use a credential-type-specificoption function.This will ensure that an unexpected credential type with potential formalicious intent is not loaded unintentionally. You might still have to dovalidation for certain credential types. Please follow the recommendationfor that function. For example, if you want to load only service accounts,you can useWithAuthCredentialsJSON withServiceAccount:
option.WithAuthCredentialsJSON(option.ServiceAccount, json)
If you are loading your credential configuration from an untrusted source and havenot mitigated the risks (e.g. by validating the configuration yourself), makethese changes as soon as possible to prevent security risks to your environment.
Regardless of the function used, it is always your responsibility to validateconfigurations received from external sources.
funcWithEndpoint¶
func WithEndpoint(urlstring)ClientOption
WithEndpoint returns a ClientOption that overrides the default endpointto be used for a service. Please note that by default Google APIs onlyaccept HTTPS traffic.
For a gRPC client, the port number is typically included in the endpoint.Example: "us-central1-speech.googleapis.com:443".
For a REST client, the port number is typically not included. Example:"https://speech.googleapis.com".
funcWithGRPCConn¶
func WithGRPCConn(conn *grpc.ClientConn)ClientOption
WithGRPCConn returns a ClientOption that specifies the gRPC clientconnection to use as the basis of communications. This option may only beused with services that support gRPC as their communication transport. Whenused, the WithGRPCConn option takes precedent over all other suppliedoptions.
funcWithGRPCConnectionPool¶
func WithGRPCConnectionPool(sizeint)ClientOption
WithGRPCConnectionPool returns a ClientOption that creates a pool of gRPCconnections that requests will be balanced between.
funcWithGRPCDialOption¶
func WithGRPCDialOption(optgrpc.DialOption)ClientOption
WithGRPCDialOption returns a ClientOption that appends a new grpc.DialOptionto an underlying gRPC dial. It does not work with WithGRPCConn.
funcWithHTTPClient¶
func WithHTTPClient(client *http.Client)ClientOption
WithHTTPClient returns a ClientOption that specifies the HTTP client to useas the basis of communications. This option may only be used with servicesthat support HTTP as their communication transport. When used, theWithHTTPClient option takes precedent over all other supplied options.
funcWithLogger¶added inv0.206.0
func WithLogger(l *slog.Logger)ClientOption
WithLogger returns a ClientOption that sets the logger used throughout theclient library call stack. If this option is provided it takes precedenceover the value set in GOOGLE_SDK_GO_LOGGING_LEVEL. Specifying this optionenables logging at the provided logger's configured level.
funcWithQuotaProject¶added inv0.2.0
func WithQuotaProject(quotaProjectstring)ClientOption
WithQuotaProject returns a ClientOption that specifies the project usedfor quota and billing purposes.
For more information please read:https://cloud.google.com/apis/docs/system-parameters
funcWithRequestReason¶added inv0.2.0
func WithRequestReason(requestReasonstring)ClientOption
WithRequestReason returns a ClientOption that specifies a reason formaking 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
funcWithScopes¶
func WithScopes(scope ...string)ClientOption
WithScopes returns a ClientOption that overrides the default OAuth2 scopesto be used for a service.
If both WithScopes and WithTokenSource are used, scope settings from thetoken source will be used instead.
funcWithServiceAccountFiledeprecated
func WithServiceAccountFile(filenamestring)ClientOption
WithServiceAccountFile returns a ClientOption that uses a Google serviceaccount credentials file to authenticate.
Important: If you accept a credential configuration (credentialJSON/File/Stream) from an external source for authentication to GoogleCloud Platform, you must validate it before providing it to any GoogleAPI or library. Providing an unvalidated credential configuration toGoogle APIs can compromise the security of your systems and data. Formore information, refer to [Validate credential configurations fromexternal sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
Deprecated: Use WithAuthCredentialsFile instead.
funcWithTelemetryDisabled¶added inv0.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.
funcWithTokenSource¶
func WithTokenSource(soauth2.TokenSource)ClientOption
WithTokenSource returns a ClientOption that specifies an OAuth2 tokensource to be used as the basis for authentication.
funcWithUniverseDomain¶added inv0.153.0
func WithUniverseDomain(udstring)ClientOption
WithUniverseDomain returns a ClientOption that sets the universe domain.
funcWithUserAgent¶
func WithUserAgent(uastring)ClientOption
WithUserAgent returns a ClientOption that sets the User-Agent. This optionis incompatible with theWithHTTPClient option. If you wish to provide acustom client you will need to add this header via RoundTripper middleware.
funcWithoutAuthentication¶
func WithoutAuthentication()ClientOption
WithoutAuthentication returns a ClientOption that specifies that noauthentication should be used. It is suitable only for testing and foraccessing public resources, like public Google Cloud Storage buckets.It is an error to provide both WithoutAuthentication and any of WithAPIKey,WithTokenSource, WithCredentialsFile or WithServiceAccountFile.
typeCredentialsType¶added inv0.258.0
type CredentialsType =credentialstype.CredType
CredentialsType specifies the type of JSON credentials being providedto a loading function such asWithAuthCredentialsFile orWithAuthCredentialsJSON.
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. |