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