1// Copyright 2019 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// https://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15// Code generated by gapic-generator. DO NOT EDIT. 16 17package instance 18 19import ( 20 "context" 21 "fmt" 22 "math" 23 "time" 24 25 "cloud.google.com/go/longrunning" 26 lroauto "cloud.google.com/go/longrunning/autogen" 27 "github.com/golang/protobuf/proto" 28 gax "github.com/googleapis/gax-go/v2" 29 "google.golang.org/api/iterator" 30 "google.golang.org/api/option" 31 "google.golang.org/api/transport" 32 iampb "google.golang.org/genproto/googleapis/iam/v1" 33 longrunningpb "google.golang.org/genproto/googleapis/longrunning" 34 instancepb "google.golang.org/genproto/googleapis/spanner/admin/instance/v1" 35 "google.golang.org/grpc" 36 "google.golang.org/grpc/codes" 37 "google.golang.org/grpc/metadata" 38) 39 40// InstanceAdminCallOptions contains the retry settings for each method of InstanceAdminClient. 41type InstanceAdminCallOptions struct { 42 ListInstanceConfigs []gax.CallOption 43 GetInstanceConfig []gax.CallOption 44 ListInstances []gax.CallOption 45 GetInstance []gax.CallOption 46 CreateInstance []gax.CallOption 47 UpdateInstance []gax.CallOption 48 DeleteInstance []gax.CallOption 49 SetIamPolicy []gax.CallOption 50 GetIamPolicy []gax.CallOption 51 TestIamPermissions []gax.CallOption 52} 53 54func defaultInstanceAdminClientOptions() []option.ClientOption { 55 return []option.ClientOption{ 56 option.WithEndpoint("spanner.googleapis.com:443"), 57 option.WithScopes(DefaultAuthScopes()...), 58 } 59} 60 61func defaultInstanceAdminCallOptions() *InstanceAdminCallOptions { 62 retry := map[[2]string][]gax.CallOption{ 63 {"default", "idempotent"}: { 64 gax.WithRetry(func() gax.Retryer { 65 return gax.OnCodes([]codes.Code{ 66 codes.DeadlineExceeded, 67 codes.Unavailable, 68 }, gax.Backoff{ 69 Initial: 1000 * time.Millisecond, 70 Max: 32000 * time.Millisecond, 71 Multiplier: 1.3, 72 }) 73 }), 74 }, 75 } 76 return &InstanceAdminCallOptions{ 77 ListInstanceConfigs: retry[[2]string{"default", "idempotent"}], 78 GetInstanceConfig: retry[[2]string{"default", "idempotent"}], 79 ListInstances: retry[[2]string{"default", "idempotent"}], 80 GetInstance: retry[[2]string{"default", "idempotent"}], 81 CreateInstance: retry[[2]string{"default", "non_idempotent"}], 82 UpdateInstance: retry[[2]string{"default", "non_idempotent"}], 83 DeleteInstance: retry[[2]string{"default", "idempotent"}], 84 SetIamPolicy: retry[[2]string{"default", "non_idempotent"}], 85 GetIamPolicy: retry[[2]string{"default", "idempotent"}], 86 TestIamPermissions: retry[[2]string{"default", "non_idempotent"}], 87 } 88} 89 90// InstanceAdminClient is a client for interacting with Cloud Spanner Instance Admin API. 91// 92// Methods, except Close, may be called concurrently. However, fields must not be modified concurrently with method calls. 93type InstanceAdminClient struct { 94 // The connection to the service. 95 conn *grpc.ClientConn 96 97 // The gRPC API client. 98 instanceAdminClient instancepb.InstanceAdminClient 99 100 // LROClient is used internally to handle longrunning operations. 101 // It is exposed so that its CallOptions can be modified if required. 102 // Users should not Close this client. 103 LROClient *lroauto.OperationsClient 104 105 // The call options for this service. 106 CallOptions *InstanceAdminCallOptions 107 108 // The x-goog-* metadata to be sent with each request. 109 xGoogMetadata metadata.MD 110} 111 112// NewInstanceAdminClient creates a new instance admin client. 113// 114// Cloud Spanner Instance Admin API 115// 116// The Cloud Spanner Instance Admin API can be used to create, delete, 117// modify and list instances. Instances are dedicated Cloud Spanner serving 118// and storage resources to be used by Cloud Spanner databases. 119// 120// Each instance has a "configuration", which dictates where the 121// serving resources for the Cloud Spanner instance are located (e.g., 122// US-central, Europe). Configurations are created by Google based on 123// resource availability. 124// 125// Cloud Spanner billing is based on the instances that exist and their 126// sizes. After an instance exists, there are no additional 127// per-database or per-operation charges for use of the instance 128// (though there may be additional network bandwidth charges). 129// Instances offer isolation: problems with databases in one instance 130// will not affect other instances. However, within an instance 131// databases can affect each other. For example, if one database in an 132// instance receives a lot of requests and consumes most of the 133// instance resources, fewer resources are available for other 134// databases in that instance, and their performance may suffer. 135func NewInstanceAdminClient(ctx context.Context, opts ...option.ClientOption) (*InstanceAdminClient, error) { 136 conn, err := transport.DialGRPC(ctx, append(defaultInstanceAdminClientOptions(), opts...)...) 137 if err != nil { 138 return nil, err 139 } 140 c := &InstanceAdminClient{ 141 conn: conn, 142 CallOptions: defaultInstanceAdminCallOptions(), 143 144 instanceAdminClient: instancepb.NewInstanceAdminClient(conn), 145 } 146 c.setGoogleClientInfo() 147 148 c.LROClient, err = lroauto.NewOperationsClient(ctx, option.WithGRPCConn(conn)) 149 if err != nil { 150 // This error "should not happen", since we are just reusing old connection 151 // and never actually need to dial. 152 // If this does happen, we could leak conn. However, we cannot close conn: 153 // If the user invoked the function with option.WithGRPCConn, 154 // we would close a connection that's still in use. 155 // TODO(pongad): investigate error conditions. 156 return nil, err 157 } 158 return c, nil 159} 160 161// Connection returns the client's connection to the API service. 162func (c *InstanceAdminClient) Connection() *grpc.ClientConn { 163 return c.conn 164} 165 166// Close closes the connection to the API service. The user should invoke this when 167// the client is no longer required. 168func (c *InstanceAdminClient) Close() error { 169 return c.conn.Close() 170} 171 172// setGoogleClientInfo sets the name and version of the application in 173// the `x-goog-api-client` header passed on each request. Intended for 174// use by Google-written clients. 175func (c *InstanceAdminClient) setGoogleClientInfo(keyval ...string) { 176 kv := append([]string{"gl-go", versionGo()}, keyval...) 177 kv = append(kv, "gapic", versionClient, "gax", gax.Version, "grpc", grpc.Version) 178 c.xGoogMetadata = metadata.Pairs("x-goog-api-client", gax.XGoogHeader(kv...)) 179} 180 181// ListInstanceConfigs lists the supported instance configurations for a given project. 182func (c *InstanceAdminClient) ListInstanceConfigs(ctx context.Context, req *instancepb.ListInstanceConfigsRequest, opts ...gax.CallOption) *InstanceConfigIterator { 183 md := metadata.Pairs("x-goog-request-params", fmt.Sprintf("%s=%v", "parent", req.GetParent())) 184 ctx = insertMetadata(ctx, c.xGoogMetadata, md) 185 opts = append(c.CallOptions.ListInstanceConfigs[0:len(c.CallOptions.ListInstanceConfigs):len(c.CallOptions.ListInstanceConfigs)], opts...) 186 it := &InstanceConfigIterator{} 187 req = proto.Clone(req).(*instancepb.ListInstanceConfigsRequest) 188 it.InternalFetch = func(pageSize int, pageToken string) ([]*instancepb.InstanceConfig, string, error) { 189 var resp *instancepb.ListInstanceConfigsResponse 190 req.PageToken = pageToken 191 if pageSize > math.MaxInt32 { 192 req.PageSize = math.MaxInt32 193 } else { 194 req.PageSize = int32(pageSize) 195 } 196 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 197 var err error 198 resp, err = c.instanceAdminClient.ListInstanceConfigs(ctx, req, settings.GRPC...) 199 return err 200 }, opts...) 201 if err != nil { 202 return nil, "", err 203 } 204 return resp.InstanceConfigs, resp.NextPageToken, nil 205 } 206 fetch := func(pageSize int, pageToken string) (string, error) { 207 items, nextPageToken, err := it.InternalFetch(pageSize, pageToken) 208 if err != nil { 209 return "", err 210 } 211 it.items = append(it.items, items...) 212 return nextPageToken, nil 213 } 214 it.pageInfo, it.nextFunc = iterator.NewPageInfo(fetch, it.bufLen, it.takeBuf) 215 it.pageInfo.MaxSize = int(req.PageSize) 216 it.pageInfo.Token = req.PageToken 217 return it 218} 219 220// GetInstanceConfig gets information about a particular instance configuration. 221func (c *InstanceAdminClient) GetInstanceConfig(ctx context.Context, req *instancepb.GetInstanceConfigRequest, opts ...gax.CallOption) (*instancepb.InstanceConfig, error) { 222 md := metadata.Pairs("x-goog-request-params", fmt.Sprintf("%s=%v", "name", req.GetName())) 223 ctx = insertMetadata(ctx, c.xGoogMetadata, md) 224 opts = append(c.CallOptions.GetInstanceConfig[0:len(c.CallOptions.GetInstanceConfig):len(c.CallOptions.GetInstanceConfig)], opts...) 225 var resp *instancepb.InstanceConfig 226 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 227 var err error 228 resp, err = c.instanceAdminClient.GetInstanceConfig(ctx, req, settings.GRPC...) 229 return err 230 }, opts...) 231 if err != nil { 232 return nil, err 233 } 234 return resp, nil 235} 236 237// ListInstances lists all instances in the given project. 238func (c *InstanceAdminClient) ListInstances(ctx context.Context, req *instancepb.ListInstancesRequest, opts ...gax.CallOption) *InstanceIterator { 239 md := metadata.Pairs("x-goog-request-params", fmt.Sprintf("%s=%v", "parent", req.GetParent())) 240 ctx = insertMetadata(ctx, c.xGoogMetadata, md) 241 opts = append(c.CallOptions.ListInstances[0:len(c.CallOptions.ListInstances):len(c.CallOptions.ListInstances)], opts...) 242 it := &InstanceIterator{} 243 req = proto.Clone(req).(*instancepb.ListInstancesRequest) 244 it.InternalFetch = func(pageSize int, pageToken string) ([]*instancepb.Instance, string, error) { 245 var resp *instancepb.ListInstancesResponse 246 req.PageToken = pageToken 247 if pageSize > math.MaxInt32 { 248 req.PageSize = math.MaxInt32 249 } else { 250 req.PageSize = int32(pageSize) 251 } 252 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 253 var err error 254 resp, err = c.instanceAdminClient.ListInstances(ctx, req, settings.GRPC...) 255 return err 256 }, opts...) 257 if err != nil { 258 return nil, "", err 259 } 260 return resp.Instances, resp.NextPageToken, nil 261 } 262 fetch := func(pageSize int, pageToken string) (string, error) { 263 items, nextPageToken, err := it.InternalFetch(pageSize, pageToken) 264 if err != nil { 265 return "", err 266 } 267 it.items = append(it.items, items...) 268 return nextPageToken, nil 269 } 270 it.pageInfo, it.nextFunc = iterator.NewPageInfo(fetch, it.bufLen, it.takeBuf) 271 it.pageInfo.MaxSize = int(req.PageSize) 272 it.pageInfo.Token = req.PageToken 273 return it 274} 275 276// GetInstance gets information about a particular instance. 277func (c *InstanceAdminClient) GetInstance(ctx context.Context, req *instancepb.GetInstanceRequest, opts ...gax.CallOption) (*instancepb.Instance, error) { 278 md := metadata.Pairs("x-goog-request-params", fmt.Sprintf("%s=%v", "name", req.GetName())) 279 ctx = insertMetadata(ctx, c.xGoogMetadata, md) 280 opts = append(c.CallOptions.GetInstance[0:len(c.CallOptions.GetInstance):len(c.CallOptions.GetInstance)], opts...) 281 var resp *instancepb.Instance 282 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 283 var err error 284 resp, err = c.instanceAdminClient.GetInstance(ctx, req, settings.GRPC...) 285 return err 286 }, opts...) 287 if err != nil { 288 return nil, err 289 } 290 return resp, nil 291} 292 293// CreateInstance creates an instance and begins preparing it to begin serving. The 294// returned [long-running operation][google.longrunning.Operation] 295// can be used to track the progress of preparing the new 296// instance. The instance name is assigned by the caller. If the 297// named instance already exists, CreateInstance returns 298// ALREADY_EXISTS. 299// 300// Immediately upon completion of this request: 301// 302// The instance is readable via the API, with all requested attributes 303// but no allocated resources. Its state is CREATING. 304// 305// Until completion of the returned operation: 306// 307// Cancelling the operation renders the instance immediately unreadable 308// via the API. 309// 310// The instance can be deleted. 311// 312// All other attempts to modify the instance are rejected. 313// 314// Upon completion of the returned operation: 315// 316// Billing for all successfully-allocated resources begins (some types 317// may have lower than the requested levels). 318// 319// Databases can be created in the instance. 320// 321// The instance's allocated resource levels are readable via the API. 322// 323// The instance's state becomes READY. 324// 325// The returned [long-running operation][google.longrunning.Operation] will 326// have a name of the format <instance_name>/operations/<operation_id> and 327// can be used to track creation of the instance. The 328// [metadata][google.longrunning.Operation.metadata] field type is 329// [CreateInstanceMetadata][google.spanner.admin.instance.v1.CreateInstanceMetadata]. 330// The [response][google.longrunning.Operation.response] field type is 331// [Instance][google.spanner.admin.instance.v1.Instance], if successful. 332func (c *InstanceAdminClient) CreateInstance(ctx context.Context, req *instancepb.CreateInstanceRequest, opts ...gax.CallOption) (*CreateInstanceOperation, error) { 333 md := metadata.Pairs("x-goog-request-params", fmt.Sprintf("%s=%v", "parent", req.GetParent())) 334 ctx = insertMetadata(ctx, c.xGoogMetadata, md) 335 opts = append(c.CallOptions.CreateInstance[0:len(c.CallOptions.CreateInstance):len(c.CallOptions.CreateInstance)], opts...) 336 var resp *longrunningpb.Operation 337 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 338 var err error 339 resp, err = c.instanceAdminClient.CreateInstance(ctx, req, settings.GRPC...) 340 return err 341 }, opts...) 342 if err != nil { 343 return nil, err 344 } 345 return &CreateInstanceOperation{ 346 lro: longrunning.InternalNewOperation(c.LROClient, resp), 347 }, nil 348} 349 350// UpdateInstance updates an instance, and begins allocating or releasing resources 351// as requested. The returned [long-running 352// operation][google.longrunning.Operation] can be used to track the 353// progress of updating the instance. If the named instance does not 354// exist, returns NOT_FOUND. 355// 356// Immediately upon completion of this request: 357// 358// For resource types for which a decrease in the instance's allocation 359// has been requested, billing is based on the newly-requested level. 360// 361// Until completion of the returned operation: 362// 363// Cancelling the operation sets its metadata's 364// [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], 365// and begins restoring resources to their pre-request values. The 366// operation is guaranteed to succeed at undoing all resource changes, 367// after which point it terminates with a CANCELLED status. 368// 369// All other attempts to modify the instance are rejected. 370// 371// Reading the instance via the API continues to give the pre-request 372// resource levels. 373// 374// Upon completion of the returned operation: 375// 376// Billing begins for all successfully-allocated resources (some types 377// may have lower than the requested levels). 378// 379// All newly-reserved resources are available for serving the instance's 380// tables. 381// 382// The instance's new resource levels are readable via the API. 383// 384// The returned [long-running operation][google.longrunning.Operation] will 385// have a name of the format <instance_name>/operations/<operation_id> and 386// can be used to track the instance modification. The 387// [metadata][google.longrunning.Operation.metadata] field type is 388// [UpdateInstanceMetadata][google.spanner.admin.instance.v1.UpdateInstanceMetadata]. 389// The [response][google.longrunning.Operation.response] field type is 390// [Instance][google.spanner.admin.instance.v1.Instance], if successful. 391// 392// Authorization requires spanner.instances.update permission on 393// resource [name][google.spanner.admin.instance.v1.Instance.name]. 394func (c *InstanceAdminClient) UpdateInstance(ctx context.Context, req *instancepb.UpdateInstanceRequest, opts ...gax.CallOption) (*UpdateInstanceOperation, error) { 395 md := metadata.Pairs("x-goog-request-params", fmt.Sprintf("%s=%v", "instance.name", req.GetInstance().GetName())) 396 ctx = insertMetadata(ctx, c.xGoogMetadata, md) 397 opts = append(c.CallOptions.UpdateInstance[0:len(c.CallOptions.UpdateInstance):len(c.CallOptions.UpdateInstance)], opts...) 398 var resp *longrunningpb.Operation 399 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 400 var err error 401 resp, err = c.instanceAdminClient.UpdateInstance(ctx, req, settings.GRPC...) 402 return err 403 }, opts...) 404 if err != nil { 405 return nil, err 406 } 407 return &UpdateInstanceOperation{ 408 lro: longrunning.InternalNewOperation(c.LROClient, resp), 409 }, nil 410} 411 412// DeleteInstance deletes an instance. 413// 414// Immediately upon completion of the request: 415// 416// Billing ceases for all of the instance's reserved resources. 417// 418// Soon afterward: 419// 420// The instance and all of its databases immediately and 421// irrevocably disappear from the API. All data in the databases 422// is permanently deleted. 423func (c *InstanceAdminClient) DeleteInstance(ctx context.Context, req *instancepb.DeleteInstanceRequest, opts ...gax.CallOption) error { 424 md := metadata.Pairs("x-goog-request-params", fmt.Sprintf("%s=%v", "name", req.GetName())) 425 ctx = insertMetadata(ctx, c.xGoogMetadata, md) 426 opts = append(c.CallOptions.DeleteInstance[0:len(c.CallOptions.DeleteInstance):len(c.CallOptions.DeleteInstance)], opts...) 427 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 428 var err error 429 _, err = c.instanceAdminClient.DeleteInstance(ctx, req, settings.GRPC...) 430 return err 431 }, opts...) 432 return err 433} 434 435// SetIamPolicy sets the access control policy on an instance resource. Replaces any 436// existing policy. 437// 438// Authorization requires spanner.instances.setIamPolicy on 439// [resource][google.iam.v1.SetIamPolicyRequest.resource]. 440func (c *InstanceAdminClient) SetIamPolicy(ctx context.Context, req *iampb.SetIamPolicyRequest, opts ...gax.CallOption) (*iampb.Policy, error) { 441 md := metadata.Pairs("x-goog-request-params", fmt.Sprintf("%s=%v", "resource", req.GetResource())) 442 ctx = insertMetadata(ctx, c.xGoogMetadata, md) 443 opts = append(c.CallOptions.SetIamPolicy[0:len(c.CallOptions.SetIamPolicy):len(c.CallOptions.SetIamPolicy)], opts...) 444 var resp *iampb.Policy 445 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 446 var err error 447 resp, err = c.instanceAdminClient.SetIamPolicy(ctx, req, settings.GRPC...) 448 return err 449 }, opts...) 450 if err != nil { 451 return nil, err 452 } 453 return resp, nil 454} 455 456// GetIamPolicy gets the access control policy for an instance resource. Returns an empty 457// policy if an instance exists but does not have a policy set. 458// 459// Authorization requires spanner.instances.getIamPolicy on 460// [resource][google.iam.v1.GetIamPolicyRequest.resource]. 461func (c *InstanceAdminClient) GetIamPolicy(ctx context.Context, req *iampb.GetIamPolicyRequest, opts ...gax.CallOption) (*iampb.Policy, error) { 462 md := metadata.Pairs("x-goog-request-params", fmt.Sprintf("%s=%v", "resource", req.GetResource())) 463 ctx = insertMetadata(ctx, c.xGoogMetadata, md) 464 opts = append(c.CallOptions.GetIamPolicy[0:len(c.CallOptions.GetIamPolicy):len(c.CallOptions.GetIamPolicy)], opts...) 465 var resp *iampb.Policy 466 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 467 var err error 468 resp, err = c.instanceAdminClient.GetIamPolicy(ctx, req, settings.GRPC...) 469 return err 470 }, opts...) 471 if err != nil { 472 return nil, err 473 } 474 return resp, nil 475} 476 477// TestIamPermissions returns permissions that the caller has on the specified instance resource. 478// 479// Attempting this RPC on a non-existent Cloud Spanner instance resource will 480// result in a NOT_FOUND error if the user has spanner.instances.list 481// permission on the containing Google Cloud Project. Otherwise returns an 482// empty set of permissions. 483func (c *InstanceAdminClient) TestIamPermissions(ctx context.Context, req *iampb.TestIamPermissionsRequest, opts ...gax.CallOption) (*iampb.TestIamPermissionsResponse, error) { 484 md := metadata.Pairs("x-goog-request-params", fmt.Sprintf("%s=%v", "resource", req.GetResource())) 485 ctx = insertMetadata(ctx, c.xGoogMetadata, md) 486 opts = append(c.CallOptions.TestIamPermissions[0:len(c.CallOptions.TestIamPermissions):len(c.CallOptions.TestIamPermissions)], opts...) 487 var resp *iampb.TestIamPermissionsResponse 488 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 489 var err error 490 resp, err = c.instanceAdminClient.TestIamPermissions(ctx, req, settings.GRPC...) 491 return err 492 }, opts...) 493 if err != nil { 494 return nil, err 495 } 496 return resp, nil 497} 498 499// InstanceConfigIterator manages a stream of *instancepb.InstanceConfig. 500type InstanceConfigIterator struct { 501 items []*instancepb.InstanceConfig 502 pageInfo *iterator.PageInfo 503 nextFunc func() error 504 505 // InternalFetch is for use by the Google Cloud Libraries only. 506 // It is not part of the stable interface of this package. 507 // 508 // InternalFetch returns results from a single call to the underlying RPC. 509 // The number of results is no greater than pageSize. 510 // If there are no more results, nextPageToken is empty and err is nil. 511 InternalFetch func(pageSize int, pageToken string) (results []*instancepb.InstanceConfig, nextPageToken string, err error) 512} 513 514// PageInfo supports pagination. See the google.golang.org/api/iterator package for details. 515func (it *InstanceConfigIterator) PageInfo() *iterator.PageInfo { 516 return it.pageInfo 517} 518 519// Next returns the next result. Its second return value is iterator.Done if there are no more 520// results. Once Next returns Done, all subsequent calls will return Done. 521func (it *InstanceConfigIterator) Next() (*instancepb.InstanceConfig, error) { 522 var item *instancepb.InstanceConfig 523 if err := it.nextFunc(); err != nil { 524 return item, err 525 } 526 item = it.items[0] 527 it.items = it.items[1:] 528 return item, nil 529} 530 531func (it *InstanceConfigIterator) bufLen() int { 532 return len(it.items) 533} 534 535func (it *InstanceConfigIterator) takeBuf() interface{} { 536 b := it.items 537 it.items = nil 538 return b 539} 540 541// InstanceIterator manages a stream of *instancepb.Instance. 542type InstanceIterator struct { 543 items []*instancepb.Instance 544 pageInfo *iterator.PageInfo 545 nextFunc func() error 546 547 // InternalFetch is for use by the Google Cloud Libraries only. 548 // It is not part of the stable interface of this package. 549 // 550 // InternalFetch returns results from a single call to the underlying RPC. 551 // The number of results is no greater than pageSize. 552 // If there are no more results, nextPageToken is empty and err is nil. 553 InternalFetch func(pageSize int, pageToken string) (results []*instancepb.Instance, nextPageToken string, err error) 554} 555 556// PageInfo supports pagination. See the google.golang.org/api/iterator package for details. 557func (it *InstanceIterator) PageInfo() *iterator.PageInfo { 558 return it.pageInfo 559} 560 561// Next returns the next result. Its second return value is iterator.Done if there are no more 562// results. Once Next returns Done, all subsequent calls will return Done. 563func (it *InstanceIterator) Next() (*instancepb.Instance, error) { 564 var item *instancepb.Instance 565 if err := it.nextFunc(); err != nil { 566 return item, err 567 } 568 item = it.items[0] 569 it.items = it.items[1:] 570 return item, nil 571} 572 573func (it *InstanceIterator) bufLen() int { 574 return len(it.items) 575} 576 577func (it *InstanceIterator) takeBuf() interface{} { 578 b := it.items 579 it.items = nil 580 return b 581} 582 583// CreateInstanceOperation manages a long-running operation from CreateInstance. 584type CreateInstanceOperation struct { 585 lro *longrunning.Operation 586} 587 588// CreateInstanceOperation returns a new CreateInstanceOperation from a given name. 589// The name must be that of a previously created CreateInstanceOperation, possibly from a different process. 590func (c *InstanceAdminClient) CreateInstanceOperation(name string) *CreateInstanceOperation { 591 return &CreateInstanceOperation{ 592 lro: longrunning.InternalNewOperation(c.LROClient, &longrunningpb.Operation{Name: name}), 593 } 594} 595 596// Wait blocks until the long-running operation is completed, returning the response and any errors encountered. 597// 598// See documentation of Poll for error-handling information. 599func (op *CreateInstanceOperation) Wait(ctx context.Context, opts ...gax.CallOption) (*instancepb.Instance, error) { 600 var resp instancepb.Instance 601 if err := op.lro.WaitWithInterval(ctx, &resp, 45000*time.Millisecond, opts...); err != nil { 602 return nil, err 603 } 604 return &resp, nil 605} 606 607// Poll fetches the latest state of the long-running operation. 608// 609// Poll also fetches the latest metadata, which can be retrieved by Metadata. 610// 611// If Poll fails, the error is returned and op is unmodified. If Poll succeeds and 612// the operation has completed with failure, the error is returned and op.Done will return true. 613// If Poll succeeds and the operation has completed successfully, 614// op.Done will return true, and the response of the operation is returned. 615// If Poll succeeds and the operation has not completed, the returned response and error are both nil. 616func (op *CreateInstanceOperation) Poll(ctx context.Context, opts ...gax.CallOption) (*instancepb.Instance, error) { 617 var resp instancepb.Instance 618 if err := op.lro.Poll(ctx, &resp, opts...); err != nil { 619 return nil, err 620 } 621 if !op.Done() { 622 return nil, nil 623 } 624 return &resp, nil 625} 626 627// Metadata returns metadata associated with the long-running operation. 628// Metadata itself does not contact the server, but Poll does. 629// To get the latest metadata, call this method after a successful call to Poll. 630// If the metadata is not available, the returned metadata and error are both nil. 631func (op *CreateInstanceOperation) Metadata() (*instancepb.CreateInstanceMetadata, error) { 632 var meta instancepb.CreateInstanceMetadata 633 if err := op.lro.Metadata(&meta); err == longrunning.ErrNoMetadata { 634 return nil, nil 635 } else if err != nil { 636 return nil, err 637 } 638 return &meta, nil 639} 640 641// Done reports whether the long-running operation has completed. 642func (op *CreateInstanceOperation) Done() bool { 643 return op.lro.Done() 644} 645 646// Name returns the name of the long-running operation. 647// The name is assigned by the server and is unique within the service from which the operation is created. 648func (op *CreateInstanceOperation) Name() string { 649 return op.lro.Name() 650} 651 652// UpdateInstanceOperation manages a long-running operation from UpdateInstance. 653type UpdateInstanceOperation struct { 654 lro *longrunning.Operation 655} 656 657// UpdateInstanceOperation returns a new UpdateInstanceOperation from a given name. 658// The name must be that of a previously created UpdateInstanceOperation, possibly from a different process. 659func (c *InstanceAdminClient) UpdateInstanceOperation(name string) *UpdateInstanceOperation { 660 return &UpdateInstanceOperation{ 661 lro: longrunning.InternalNewOperation(c.LROClient, &longrunningpb.Operation{Name: name}), 662 } 663} 664 665// Wait blocks until the long-running operation is completed, returning the response and any errors encountered. 666// 667// See documentation of Poll for error-handling information. 668func (op *UpdateInstanceOperation) Wait(ctx context.Context, opts ...gax.CallOption) (*instancepb.Instance, error) { 669 var resp instancepb.Instance 670 if err := op.lro.WaitWithInterval(ctx, &resp, 45000*time.Millisecond, opts...); err != nil { 671 return nil, err 672 } 673 return &resp, nil 674} 675 676// Poll fetches the latest state of the long-running operation. 677// 678// Poll also fetches the latest metadata, which can be retrieved by Metadata. 679// 680// If Poll fails, the error is returned and op is unmodified. If Poll succeeds and 681// the operation has completed with failure, the error is returned and op.Done will return true. 682// If Poll succeeds and the operation has completed successfully, 683// op.Done will return true, and the response of the operation is returned. 684// If Poll succeeds and the operation has not completed, the returned response and error are both nil. 685func (op *UpdateInstanceOperation) Poll(ctx context.Context, opts ...gax.CallOption) (*instancepb.Instance, error) { 686 var resp instancepb.Instance 687 if err := op.lro.Poll(ctx, &resp, opts...); err != nil { 688 return nil, err 689 } 690 if !op.Done() { 691 return nil, nil 692 } 693 return &resp, nil 694} 695 696// Metadata returns metadata associated with the long-running operation. 697// Metadata itself does not contact the server, but Poll does. 698// To get the latest metadata, call this method after a successful call to Poll. 699// If the metadata is not available, the returned metadata and error are both nil. 700func (op *UpdateInstanceOperation) Metadata() (*instancepb.UpdateInstanceMetadata, error) { 701 var meta instancepb.UpdateInstanceMetadata 702 if err := op.lro.Metadata(&meta); err == longrunning.ErrNoMetadata { 703 return nil, nil 704 } else if err != nil { 705 return nil, err 706 } 707 return &meta, nil 708} 709 710// Done reports whether the long-running operation has completed. 711func (op *UpdateInstanceOperation) Done() bool { 712 return op.lro.Done() 713} 714 715// Name returns the name of the long-running operation. 716// The name is assigned by the server and is unique within the service from which the operation is created. 717func (op *UpdateInstanceOperation) Name() string { 718 return op.lro.Name() 719} 720