diff --git a/doc.go b/doc.go index b667cc8b254..746696f3711 100644 --- a/doc.go +++ b/doc.go @@ -28,8 +28,50 @@ Authentication and Authorization All the clients in sub-packages support authentication via Google Application Default Credentials (see https://cloud.google.com/docs/authentication/production), or -by providing a JSON key file for a Service Account. See the authentication examples -in this package for details. +by providing a JSON key file for a Service Account. See examples below. + +Google Application Default Credentials (ADC) is the recommended way to authorize +and authenticate clients. For information on how to create and obtain +Application Default Credentials, see +https://cloud.google.com/docs/authentication/production. Here is an example +of a client using ADC to authenticate: + client, err := secretmanager.NewClient(context.Background()) + if err != nil { + // TODO: handle error. + } + _ = client // Use the client. + +You can use a file with credentials to authenticate and authorize, such as a JSON +key file associated with a Google service account. Service Account keys can be +created and downloaded from +https://console.cloud.google.com/iam-admin/serviceaccounts. This example uses +the Secret Manger client, but the same steps apply to the other client libraries +underneath this package. Example: + client, err := secretmanager.NewClient(context.Background(), + option.WithCredentialsFile("/path/to/service-account-key.json")) + if err != nil { + // TODO: handle error. + } + _ = client // Use the client. + +In some cases (for instance, you don't want to store secrets on disk), you can +create credentials from in-memory JSON and use the WithCredentials option. +The google package in this example is at golang.org/x/oauth2/google. +This example uses the Secret Manager client, but the same steps apply to +the other client libraries underneath this package. Note that scopes can be +found at https://developers.google.com/identity/protocols/oauth2/scopes, and +are also provided in all auto-generated libraries: for example, +cloud.google.com/go/secretmanager/apiv1 provides DefaultAuthScopes. Example: + ctx := context.Background() + creds, err := google.CredentialsFromJSON(ctx, []byte("JSON creds"), secretmanager.DefaultAuthScopes()...) + if err != nil { + // TODO: handle error. + } + client, err := secretmanager.NewClient(ctx, option.WithCredentials(creds)) + if err != nil { + // TODO: handle error. + } + _ = client // Use the client. Timeouts and Cancellation @@ -37,9 +79,45 @@ Timeouts and Cancellation By default, non-streaming methods, like Create or Get, will have a default deadline applied to the context provided at call time, unless a context deadline is already set. Streaming methods have no default deadline and will run indefinitely. To set timeouts or -arrange for cancellation, use contexts. See the examples for details. Transient +arrange for cancellation, use contexts. Transient errors will be retried when correctness allows. +Here is an example of how to set a timeout for an RPC, use context.WithTimeout: + ctx := context.Background() + // Do not set a timeout on the context passed to NewClient: dialing happens + // asynchronously, and the context is used to refresh credentials in the + // background. + client, err := secretmanager.NewClient(ctx) + if err != nil { + // TODO: handle error. + } + // Time out if it takes more than 10 seconds to create a dataset. + tctx, cancel := context.WithTimeout(ctx, 10*time.Second) + defer cancel() // Always call cancel. + + req := &secretmanagerpb.DeleteSecretRequest{Name: "projects/project-id/secrets/name"} + if err := client.DeleteSecret(tctx, req); err != nil { + // TODO: handle error. + } + +Here is an example of how to arrange for an RPC to be canceled, use context.WithCancel: + ctx := context.Background() + // Do not cancel the context passed to NewClient: dialing happens asynchronously, + // and the context is used to refresh credentials in the background. + client, err := secretmanager.NewClient(ctx) + if err != nil { + // TODO: handle error. + } + cctx, cancel := context.WithCancel(ctx) + defer cancel() // Always call cancel. + + // TODO: Make the cancel function available to whatever might want to cancel the + // call--perhaps a GUI button. + req := &secretmanagerpb.DeleteSecretRequest{Name: "projects/proj/secrets/name"} + if err := client.DeleteSecret(cctx, req); err != nil { + // TODO: handle error. + } + To opt out of default deadlines, set the temporary environment variable GOOGLE_API_GO_EXPERIMENTAL_DISABLE_DEFAULT_DEADLINE to "true" prior to client creation. This affects all Google Cloud Go client libraries. This opt-out diff --git a/examples_test.go b/examples_test.go deleted file mode 100644 index dc0b0dd0df1..00000000000 --- a/examples_test.go +++ /dev/null @@ -1,117 +0,0 @@ -// Copyright 2018 Google LLC -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -package cloud_test - -import ( - "context" - "time" - - secretmanager "cloud.google.com/go/secretmanager/apiv1" - "golang.org/x/oauth2/google" - "google.golang.org/api/option" - secretmanagerpb "google.golang.org/genproto/googleapis/cloud/secretmanager/v1" -) - -// To set a timeout for an RPC, use context.WithTimeout. -func Example_timeout() { - ctx := context.Background() - // Do not set a timeout on the context passed to NewClient: dialing happens - // asynchronously, and the context is used to refresh credentials in the - // background. - client, err := secretmanager.NewClient(ctx) - if err != nil { - // TODO: handle error. - } - // Time out if it takes more than 10 seconds to create a dataset. - tctx, cancel := context.WithTimeout(ctx, 10*time.Second) - defer cancel() // Always call cancel. - - req := &secretmanagerpb.DeleteSecretRequest{Name: "projects/project-id/secrets/name"} - if err := client.DeleteSecret(tctx, req); err != nil { - // TODO: handle error. - } -} - -// To arrange for an RPC to be canceled, use context.WithCancel. -func Example_cancellation() { - ctx := context.Background() - // Do not cancel the context passed to NewClient: dialing happens asynchronously, - // and the context is used to refresh credentials in the background. - client, err := secretmanager.NewClient(ctx) - if err != nil { - // TODO: handle error. - } - cctx, cancel := context.WithCancel(ctx) - defer cancel() // Always call cancel. - - // TODO: Make the cancel function available to whatever might want to cancel the - // call--perhaps a GUI button. - req := &secretmanagerpb.DeleteSecretRequest{Name: "projects/proj/secrets/name"} - if err := client.DeleteSecret(cctx, req); err != nil { - // TODO: handle error. - } -} - -// Google Application Default Credentials is the recommended way to authorize -// and authenticate clients. -// -// For information on how to create and obtain Application Default Credentials, see -// https://cloud.google.com/docs/authentication/production. -func Example_applicationDefaultCredentials() { - client, err := secretmanager.NewClient(context.Background()) - if err != nil { - // TODO: handle error. - } - _ = client // Use the client. -} - -// You can use a file with credentials to authenticate and authorize, such as a JSON -// key file associated with a Google service account. Service Account keys can be -// created and downloaded from -// https://console.cloud.google.com/iam-admin/serviceaccounts. -// -// This example uses the Datastore client, but the same steps apply to -// the other client libraries underneath this package. -func Example_credentialsFile() { - client, err := secretmanager.NewClient(context.Background(), - option.WithCredentialsFile("/path/to/service-account-key.json")) - if err != nil { - // TODO: handle error. - } - _ = client // Use the client. -} - -// In some cases (for instance, you don't want to store secrets on disk), you can -// create credentials from in-memory JSON and use the WithCredentials option. -// -// The google package in this example is at golang.org/x/oauth2/google. -// -// This example uses the Secret Manager client, but the same steps apply to -// the other client libraries underneath this package. Note that scopes can be -// found at https://developers.google.com/identity/protocols/oauth2/scopes, and -// are also provided in all auto-generated libraries: for example, -// cloud.google.com/go/secretmanager/apiv1 provides DefaultAuthScopes. -func Example_credentialsFromJSON() { - ctx := context.Background() - creds, err := google.CredentialsFromJSON(ctx, []byte("JSON creds"), secretmanager.DefaultAuthScopes()...) - if err != nil { - // TODO: handle error. - } - client, err := secretmanager.NewClient(ctx, option.WithCredentials(creds)) - if err != nil { - // TODO: handle error. - } - _ = client // Use the client. -}