| // Copyright 2019 Google LLC. All rights reserved. | |
| // Use of this source code is governed by a BSD-style | |
| // license that can be found in the LICENSE file. | |
| // Package api is the root of the packages used to access Google Cloud | |
| // Services. See https://godoc.org/google.golang.org/api for a full list of | |
| // sub-packages. | |
| // | |
| // Within api there exist numerous clients which connect to Google APIs, | |
| // and various utility packages. | |
| // | |
| // # Client Options | |
| // | |
| // All clients in sub-packages are configurable via client options. These | |
| // options are described here: https://godoc.org/google.golang.org/api/option. | |
| // | |
| // # 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 | |
| // https://godoc.org/google.golang.org/api/transport for more details. | |
| // | |
| // # Versioning and Stability | |
| // | |
| // Due to the auto-generated nature of this collection of libraries, complete | |
| // APIs or specific versions can appear or go away without notice. As a result, | |
| // you should always locally vendor any API(s) that your code relies upon. | |
| // | |
| // Google APIs follow semver as specified by | |
| // https://cloud.google.com/apis/design/versioning. The code generator and | |
| // the code it produces - the libraries in the google.golang.org/api/... | |
| // subpackages - are beta. | |
| // | |
| // Note that versioning and stability is strictly not communicated through Go | |
| // modules. Go modules are used only for dependency management. | |
| // | |
| // # Integers | |
| // | |
| // Many parameters are specified using ints. However, underlying APIs might | |
| // operate on a finer granularity, expecting int64, int32, uint64, or uint32, | |
| // all of whom have different maximum values. Subsequently, specifying an int | |
| // parameter in one of these clients may result in an error from the API | |
| // because the value is too large. | |
| // | |
| // To see the exact type of int that the API expects, you can inspect the API's | |
| // discovery doc. A global catalogue pointing to the discovery doc of APIs can | |
| // be found at https://www.googleapis.com/discovery/v1/apis. | |
| // | |
| // # ForceSendFields | |
| // | |
| // This field can be found on all Request/Response structs in the generated | |
| // clients. All of these types have the JSON `omitempty` field tag present on | |
| // their fields. This means if a type is set to its default value it will not be | |
| // marshalled. Sometimes you may actually want to send a default value, for | |
| // instance sending an int of `0`. In this case you can override the `omitempty` | |
| // feature by adding the field name to the `ForceSendFields` slice. See docs on | |
| // any struct for more details. This may be used to include empty fields in | |
| // Patch requests. | |
| // | |
| // # NullFields | |
| // | |
| // This field can be found on all Request/Response structs in the generated | |
| // clients. It can be be used to send JSON null values for the listed fields. | |
| // By default, fields with empty values are omitted from API requests because of | |
| // the presence of the `omitempty` field tag on all fields. However, any field | |
| // with an empty value appearing in NullFields will be sent to the server as | |
| // null. It is an error if a field in this list has a non-empty value. This may | |
| // be used to include null fields in Patch requests. | |
| // | |
| // # Inspecting errors | |
| // | |
| // An error returned by a client's Do method may be cast to a *googleapi.Error | |
| // or unwrapped to an *apierror.APIError. | |
| // | |
| // The https://pkg.go.dev/google.golang.org/api/googleapi#Error type is useful | |
| // for getting the HTTP status code: | |
| // | |
| // if _, err := svc.FooCall().Do(); err != nil { | |
| // if gErr, ok := err.(*googleapi.Error); ok { | |
| // fmt.Println("Status code: %v", gErr.Code) | |
| // } | |
| // } | |
| // | |
| // The https://pkg.go.dev/github.com/googleapis/gax-go/v2/apierror#APIError type | |
| // is useful for inspecting structured details of the underlying API response, | |
| // such as the reason for the error and the error domain, which is typically the | |
| // registered service name of the tool or product that generated the error: | |
| // | |
| // if _, err := svc.FooCall().Do(); err != nil { | |
| // var aErr *apierror.APIError | |
| // if ok := errors.As(err, &aErr); ok { | |
| // fmt.Println("Reason: %s", aErr.Reason()) | |
| // fmt.Println("Domain: %s", aErr.Domain()) | |
| // } | |
| // } | |
| // | |
| // # Polling Operations | |
| // | |
| // If an API call returns an Operation, that means it could take some time to | |
| // complete the work initiated by the API call. Applications that are interested | |
| // in the end result of the operation they initiated should wait until the | |
| // Operation.Done field indicates it is finished. To do this, use the service's | |
| // Operation client, and a loop, like so: | |
| // | |
| // import ( | |
| // gax "github.com/googleapis/gax-go/v2" | |
| // ) | |
| // | |
| // // existing application code... | |
| // | |
| // // API call that returns an Operation. | |
| // op, err := myApiClient.CalculateFoo().Do() | |
| // if err != nil { | |
| // // handle err | |
| // } | |
| // | |
| // operationsService = myapi.NewOperationsService(myApiClient) | |
| // pollingBackoff := gax.Backoff{ | |
| // Initial: time.Second, | |
| // Max: time.Minute, // Max time between polling attempts. | |
| // Multiplier: 2, | |
| // } | |
| // for { | |
| // if op.Done { | |
| // break | |
| // } | |
| // // not done, sleep with backoff, then poll again | |
| // if err := gax.Sleep(ctx, pollingBackoff.Pause()); err != nil { | |
| // // handle error | |
| // } | |
| // op, err := operationsService.Get(op.Name).Do() | |
| // if err != nil { | |
| // // handle error | |
| // } | |
| // } | |
| // | |
| // if op.Error != nil { | |
| // // handle operation err | |
| // } | |
| // | |
| // // Do something with the response | |
| // fmt.Println(op.Response) | |
| package api |