1 // Copyright 2019 Google LLC. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package api is the root of the packages used to access Google Cloud 6 // Services. See https://godoc.org/google.golang.org/api for a full list of 7 // sub-packages. 8 // 9 // Within api there exist numerous clients which connect to Google APIs, 10 // and various utility packages. 11 // 12 // # Client Options 13 // 14 // All clients in sub-packages are configurable via client options. These 15 // options are described here: https://godoc.org/google.golang.org/api/option. 16 // 17 // # Authentication and Authorization 18 // 19 // All the clients in sub-packages support authentication via Google 20 // Application Default Credentials (see 21 // https://cloud.google.com/docs/authentication/production), or by providing a 22 // JSON key file for a Service Account. See the authentication examples in 23 // https://godoc.org/google.golang.org/api/transport for more details. 24 // 25 // # Versioning and Stability 26 // 27 // Due to the auto-generated nature of this collection of libraries, complete 28 // APIs or specific versions can appear or go away without notice. As a result, 29 // you should always locally vendor any API(s) that your code relies upon. 30 // 31 // Google APIs follow semver as specified by 32 // https://cloud.google.com/apis/design/versioning. The code generator and 33 // the code it produces - the libraries in the google.golang.org/api/... 34 // subpackages - are beta. 35 // 36 // Note that versioning and stability is strictly not communicated through Go 37 // modules. Go modules are used only for dependency management. 38 // 39 // # Integers 40 // 41 // Many parameters are specified using ints. However, underlying APIs might 42 // operate on a finer granularity, expecting int64, int32, uint64, or uint32, 43 // all of whom have different maximum values. Subsequently, specifying an int 44 // parameter in one of these clients may result in an error from the API 45 // because the value is too large. 46 // 47 // To see the exact type of int that the API expects, you can inspect the API's 48 // discovery doc. A global catalogue pointing to the discovery doc of APIs can 49 // be found at https://www.googleapis.com/discovery/v1/apis. 50 // 51 // # ForceSendFields 52 // 53 // This field can be found on all Request/Response structs in the generated 54 // clients. All of these types have the JSON `omitempty` field tag present on 55 // their fields. This means if a type is set to its default value it will not be 56 // marshalled. Sometimes you may actually want to send a default value, for 57 // instance sending an int of `0`. In this case you can override the `omitempty` 58 // feature by adding the field name to the `ForceSendFields` slice. See docs on 59 // any struct for more details. This may be used to include empty fields in 60 // Patch requests. 61 // 62 // # NullFields 63 // 64 // This field can be found on all Request/Response structs in the generated 65 // clients. It can be be used to send JSON null values for the listed fields. 66 // By default, fields with empty values are omitted from API requests because of 67 // the presence of the `omitempty` field tag on all fields. However, any field 68 // with an empty value appearing in NullFields will be sent to the server as 69 // null. It is an error if a field in this list has a non-empty value. This may 70 // be used to include null fields in Patch requests. 71 // 72 // # Inspecting errors 73 // 74 // An error returned by a client's Do method may be cast to a *googleapi.Error 75 // or unwrapped to an *apierror.APIError. 76 // 77 // The https://pkg.go.dev/google.golang.org/api/googleapi#Error type is useful 78 // for getting the HTTP status code: 79 // 80 // if _, err := svc.FooCall().Do(); err != nil { 81 // if gErr, ok := err.(*googleapi.Error); ok { 82 // fmt.Println("Status code: %v", gErr.Code) 83 // } 84 // } 85 // 86 // The https://pkg.go.dev/github.com/googleapis/gax-go/v2/apierror#APIError type 87 // is useful for inspecting structured details of the underlying API response, 88 // such as the reason for the error and the error domain, which is typically the 89 // registered service name of the tool or product that generated the error: 90 // 91 // if _, err := svc.FooCall().Do(); err != nil { 92 // var aErr *apierror.APIError 93 // if ok := errors.As(err, &aErr); ok { 94 // fmt.Println("Reason: %s", aErr.Reason()) 95 // fmt.Println("Domain: %s", aErr.Domain()) 96 // } 97 // } 98 // 99 // # Polling Operations 100 // 101 // If an API call returns an Operation, that means it could take some time to 102 // complete the work initiated by the API call. Applications that are interested 103 // in the end result of the operation they initiated should wait until the 104 // Operation.Done field indicates it is finished. To do this, use the service's 105 // Operation client, and a loop, like so: 106 // 107 // import ( 108 // gax "github.com/googleapis/gax-go/v2" 109 // ) 110 // 111 // // existing application code... 112 // 113 // // API call that returns an Operation. 114 // op, err := myApiClient.CalculateFoo().Do() 115 // if err != nil { 116 // // handle err 117 // } 118 // 119 // operationsService = myapi.NewOperationsService(myApiClient) 120 // pollingBackoff := gax.Backoff{ 121 // Initial: time.Second, 122 // Max: time.Minute, // Max time between polling attempts. 123 // Multiplier: 2, 124 // } 125 // for { 126 // if op.Done { 127 // break 128 // } 129 // // not done, sleep with backoff, then poll again 130 // if err := gax.Sleep(ctx, pollingBackoff.Pause()); err != nil { 131 // // handle error 132 // } 133 // op, err := operationsService.Get(op.Name).Do() 134 // if err != nil { 135 // // handle error 136 // } 137 // } 138 // 139 // if op.Error != nil { 140 // // handle operation err 141 // } 142 // 143 // // Do something with the response 144 // fmt.Println(op.Response) 145 package api 146 147 import ( 148 // Force dependency on main module to ensure it is unambiguous during 149 // module resolution. 150 // See: https://github.com/googleapis/google-api-go-client/issues/2559. 151 _ "cloud.google.com/go/civil" 152 ) 153