1// Copyright 2020 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 admin 18 19import ( 20 "context" 21 "math" 22 "time" 23 24 "cloud.google.com/go/longrunning" 25 lroauto "cloud.google.com/go/longrunning/autogen" 26 "github.com/golang/protobuf/proto" 27 gax "github.com/googleapis/gax-go/v2" 28 "google.golang.org/api/iterator" 29 "google.golang.org/api/option" 30 gtransport "google.golang.org/api/transport/grpc" 31 adminpb "google.golang.org/genproto/googleapis/datastore/admin/v1" 32 longrunningpb "google.golang.org/genproto/googleapis/longrunning" 33 "google.golang.org/grpc" 34 "google.golang.org/grpc/codes" 35 "google.golang.org/grpc/metadata" 36) 37 38var newDatastoreAdminClientHook clientHook 39 40// DatastoreAdminCallOptions contains the retry settings for each method of DatastoreAdminClient. 41type DatastoreAdminCallOptions struct { 42 ExportEntities []gax.CallOption 43 ImportEntities []gax.CallOption 44 GetIndex []gax.CallOption 45 ListIndexes []gax.CallOption 46} 47 48func defaultDatastoreAdminClientOptions() []option.ClientOption { 49 return []option.ClientOption{ 50 option.WithEndpoint("datastore.googleapis.com:443"), 51 option.WithGRPCDialOption(grpc.WithDisableServiceConfig()), 52 option.WithScopes(DefaultAuthScopes()...), 53 option.WithGRPCDialOption(grpc.WithDefaultCallOptions( 54 grpc.MaxCallRecvMsgSize(math.MaxInt32))), 55 } 56} 57 58func defaultDatastoreAdminCallOptions() *DatastoreAdminCallOptions { 59 return &DatastoreAdminCallOptions{ 60 ExportEntities: []gax.CallOption{}, 61 ImportEntities: []gax.CallOption{}, 62 GetIndex: []gax.CallOption{ 63 gax.WithRetry(func() gax.Retryer { 64 return gax.OnCodes([]codes.Code{ 65 codes.Unavailable, 66 codes.DeadlineExceeded, 67 }, gax.Backoff{ 68 Initial: 100 * time.Millisecond, 69 Max: 60000 * time.Millisecond, 70 Multiplier: 1.30, 71 }) 72 }), 73 }, 74 ListIndexes: []gax.CallOption{ 75 gax.WithRetry(func() gax.Retryer { 76 return gax.OnCodes([]codes.Code{ 77 codes.Unavailable, 78 codes.DeadlineExceeded, 79 }, gax.Backoff{ 80 Initial: 100 * time.Millisecond, 81 Max: 60000 * time.Millisecond, 82 Multiplier: 1.30, 83 }) 84 }), 85 }, 86 } 87} 88 89// DatastoreAdminClient is a client for interacting with Cloud Datastore API. 90// 91// Methods, except Close, may be called concurrently. However, fields must not be modified concurrently with method calls. 92type DatastoreAdminClient struct { 93 // Connection pool of gRPC connections to the service. 94 connPool gtransport.ConnPool 95 96 // The gRPC API client. 97 datastoreAdminClient adminpb.DatastoreAdminClient 98 99 // LROClient is used internally to handle longrunning operations. 100 // It is exposed so that its CallOptions can be modified if required. 101 // Users should not Close this client. 102 LROClient *lroauto.OperationsClient 103 104 // The call options for this service. 105 CallOptions *DatastoreAdminCallOptions 106 107 // The x-goog-* metadata to be sent with each request. 108 xGoogMetadata metadata.MD 109} 110 111// NewDatastoreAdminClient creates a new datastore admin client. 112// 113// Google Cloud Datastore Admin API 114// 115// The Datastore Admin API provides several admin services for Cloud Datastore. 116// 117// ConceptsProject, namespace, kind, and entity as defined in the Google Cloud Datastore 118// API. 119// 120// Operation: An Operation represents work being performed in the background. 121// 122// EntityFilter: Allows specifying a subset of entities in a project. This is 123// specified as a combination of kinds and namespaces (either or both of which 124// may be all). 125// 126// ServicesExport/ImportThe Export/Import service provides the ability to copy all or a subset of 127// entities to/from Google Cloud Storage. 128// 129// Exported data may be imported into Cloud Datastore for any Google Cloud 130// Platform project. It is not restricted to the export source project. It is 131// possible to export from one project and then import into another. 132// 133// Exported data can also be loaded into Google BigQuery for analysis. 134// 135// Exports and imports are performed asynchronously. An Operation resource is 136// created for each export/import. The state (including any errors encountered) 137// of the export/import may be queried via the Operation resource. 138// 139// IndexThe index service manages Cloud Datastore composite indexes. 140// 141// Index creation and deletion are performed asynchronously. 142// An Operation resource is created for each such asynchronous operation. 143// The state of the operation (including any errors encountered) 144// may be queried via the Operation resource. 145// 146// OperationThe Operations collection provides a record of actions performed for the 147// specified project (including any operations in progress). Operations are not 148// created directly but through calls on other collections or resources. 149// 150// An operation that is not yet done may be cancelled. The request to cancel is 151// asynchronous and the operation may continue to run for some time after the 152// request to cancel is made. 153// 154// An operation that is done may be deleted so that it is no longer listed as 155// part of the Operation collection. 156// 157// ListOperations returns all pending operations, but not completed operations. 158// 159// Operations are created by service DatastoreAdmin, 160// but are accessed via service google.longrunning.Operations. 161func NewDatastoreAdminClient(ctx context.Context, opts ...option.ClientOption) (*DatastoreAdminClient, error) { 162 clientOpts := defaultDatastoreAdminClientOptions() 163 164 if newDatastoreAdminClientHook != nil { 165 hookOpts, err := newDatastoreAdminClientHook(ctx, clientHookParams{}) 166 if err != nil { 167 return nil, err 168 } 169 clientOpts = append(clientOpts, hookOpts...) 170 } 171 172 connPool, err := gtransport.DialPool(ctx, append(clientOpts, opts...)...) 173 if err != nil { 174 return nil, err 175 } 176 c := &DatastoreAdminClient{ 177 connPool: connPool, 178 CallOptions: defaultDatastoreAdminCallOptions(), 179 180 datastoreAdminClient: adminpb.NewDatastoreAdminClient(connPool), 181 } 182 c.setGoogleClientInfo() 183 184 c.LROClient, err = lroauto.NewOperationsClient(ctx, gtransport.WithConnPool(connPool)) 185 if err != nil { 186 // This error "should not happen", since we are just reusing old connection pool 187 // and never actually need to dial. 188 // If this does happen, we could leak connp. However, we cannot close conn: 189 // If the user invoked the constructor with option.WithGRPCConn, 190 // we would close a connection that's still in use. 191 // TODO: investigate error conditions. 192 return nil, err 193 } 194 return c, nil 195} 196 197// Connection returns a connection to the API service. 198// 199// Deprecated. 200func (c *DatastoreAdminClient) Connection() *grpc.ClientConn { 201 return c.connPool.Conn() 202} 203 204// Close closes the connection to the API service. The user should invoke this when 205// the client is no longer required. 206func (c *DatastoreAdminClient) Close() error { 207 return c.connPool.Close() 208} 209 210// setGoogleClientInfo sets the name and version of the application in 211// the `x-goog-api-client` header passed on each request. Intended for 212// use by Google-written clients. 213func (c *DatastoreAdminClient) setGoogleClientInfo(keyval ...string) { 214 kv := append([]string{"gl-go", versionGo()}, keyval...) 215 kv = append(kv, "gapic", versionClient, "gax", gax.Version, "grpc", grpc.Version) 216 c.xGoogMetadata = metadata.Pairs("x-goog-api-client", gax.XGoogHeader(kv...)) 217} 218 219// ExportEntities exports a copy of all or a subset of entities from Google Cloud Datastore 220// to another storage system, such as Google Cloud Storage. Recent updates to 221// entities may not be reflected in the export. The export occurs in the 222// background and its progress can be monitored and managed via the 223// Operation resource that is created. The output of an export may only be 224// used once the associated operation is done. If an export operation is 225// cancelled before completion it may leave partial data behind in Google 226// Cloud Storage. 227func (c *DatastoreAdminClient) ExportEntities(ctx context.Context, req *adminpb.ExportEntitiesRequest, opts ...gax.CallOption) (*ExportEntitiesOperation, error) { 228 ctx = insertMetadata(ctx, c.xGoogMetadata) 229 opts = append(c.CallOptions.ExportEntities[0:len(c.CallOptions.ExportEntities):len(c.CallOptions.ExportEntities)], opts...) 230 var resp *longrunningpb.Operation 231 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 232 var err error 233 resp, err = c.datastoreAdminClient.ExportEntities(ctx, req, settings.GRPC...) 234 return err 235 }, opts...) 236 if err != nil { 237 return nil, err 238 } 239 return &ExportEntitiesOperation{ 240 lro: longrunning.InternalNewOperation(c.LROClient, resp), 241 }, nil 242} 243 244// ImportEntities imports entities into Google Cloud Datastore. Existing entities with the 245// same key are overwritten. The import occurs in the background and its 246// progress can be monitored and managed via the Operation resource that is 247// created. If an ImportEntities operation is cancelled, it is possible 248// that a subset of the data has already been imported to Cloud Datastore. 249func (c *DatastoreAdminClient) ImportEntities(ctx context.Context, req *adminpb.ImportEntitiesRequest, opts ...gax.CallOption) (*ImportEntitiesOperation, error) { 250 ctx = insertMetadata(ctx, c.xGoogMetadata) 251 opts = append(c.CallOptions.ImportEntities[0:len(c.CallOptions.ImportEntities):len(c.CallOptions.ImportEntities)], opts...) 252 var resp *longrunningpb.Operation 253 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 254 var err error 255 resp, err = c.datastoreAdminClient.ImportEntities(ctx, req, settings.GRPC...) 256 return err 257 }, opts...) 258 if err != nil { 259 return nil, err 260 } 261 return &ImportEntitiesOperation{ 262 lro: longrunning.InternalNewOperation(c.LROClient, resp), 263 }, nil 264} 265 266// GetIndex gets an index. 267func (c *DatastoreAdminClient) GetIndex(ctx context.Context, req *adminpb.GetIndexRequest, opts ...gax.CallOption) (*adminpb.Index, error) { 268 ctx = insertMetadata(ctx, c.xGoogMetadata) 269 opts = append(c.CallOptions.GetIndex[0:len(c.CallOptions.GetIndex):len(c.CallOptions.GetIndex)], opts...) 270 var resp *adminpb.Index 271 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 272 var err error 273 resp, err = c.datastoreAdminClient.GetIndex(ctx, req, settings.GRPC...) 274 return err 275 }, opts...) 276 if err != nil { 277 return nil, err 278 } 279 return resp, nil 280} 281 282// ListIndexes lists the indexes that match the specified filters. Datastore uses an 283// eventually consistent query to fetch the list of indexes and may 284// occasionally return stale results. 285func (c *DatastoreAdminClient) ListIndexes(ctx context.Context, req *adminpb.ListIndexesRequest, opts ...gax.CallOption) *IndexIterator { 286 ctx = insertMetadata(ctx, c.xGoogMetadata) 287 opts = append(c.CallOptions.ListIndexes[0:len(c.CallOptions.ListIndexes):len(c.CallOptions.ListIndexes)], opts...) 288 it := &IndexIterator{} 289 req = proto.Clone(req).(*adminpb.ListIndexesRequest) 290 it.InternalFetch = func(pageSize int, pageToken string) ([]*adminpb.Index, string, error) { 291 var resp *adminpb.ListIndexesResponse 292 req.PageToken = pageToken 293 if pageSize > math.MaxInt32 { 294 req.PageSize = math.MaxInt32 295 } else { 296 req.PageSize = int32(pageSize) 297 } 298 err := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error { 299 var err error 300 resp, err = c.datastoreAdminClient.ListIndexes(ctx, req, settings.GRPC...) 301 return err 302 }, opts...) 303 if err != nil { 304 return nil, "", err 305 } 306 307 it.Response = resp 308 return resp.Indexes, resp.NextPageToken, nil 309 } 310 fetch := func(pageSize int, pageToken string) (string, error) { 311 items, nextPageToken, err := it.InternalFetch(pageSize, pageToken) 312 if err != nil { 313 return "", err 314 } 315 it.items = append(it.items, items...) 316 return nextPageToken, nil 317 } 318 it.pageInfo, it.nextFunc = iterator.NewPageInfo(fetch, it.bufLen, it.takeBuf) 319 it.pageInfo.MaxSize = int(req.PageSize) 320 it.pageInfo.Token = req.PageToken 321 return it 322} 323 324// ExportEntitiesOperation manages a long-running operation from ExportEntities. 325type ExportEntitiesOperation struct { 326 lro *longrunning.Operation 327} 328 329// ExportEntitiesOperation returns a new ExportEntitiesOperation from a given name. 330// The name must be that of a previously created ExportEntitiesOperation, possibly from a different process. 331func (c *DatastoreAdminClient) ExportEntitiesOperation(name string) *ExportEntitiesOperation { 332 return &ExportEntitiesOperation{ 333 lro: longrunning.InternalNewOperation(c.LROClient, &longrunningpb.Operation{Name: name}), 334 } 335} 336 337// Wait blocks until the long-running operation is completed, returning the response and any errors encountered. 338// 339// See documentation of Poll for error-handling information. 340func (op *ExportEntitiesOperation) Wait(ctx context.Context, opts ...gax.CallOption) (*adminpb.ExportEntitiesResponse, error) { 341 var resp adminpb.ExportEntitiesResponse 342 if err := op.lro.WaitWithInterval(ctx, &resp, time.Minute, opts...); err != nil { 343 return nil, err 344 } 345 return &resp, nil 346} 347 348// Poll fetches the latest state of the long-running operation. 349// 350// Poll also fetches the latest metadata, which can be retrieved by Metadata. 351// 352// If Poll fails, the error is returned and op is unmodified. If Poll succeeds and 353// the operation has completed with failure, the error is returned and op.Done will return true. 354// If Poll succeeds and the operation has completed successfully, 355// op.Done will return true, and the response of the operation is returned. 356// If Poll succeeds and the operation has not completed, the returned response and error are both nil. 357func (op *ExportEntitiesOperation) Poll(ctx context.Context, opts ...gax.CallOption) (*adminpb.ExportEntitiesResponse, error) { 358 var resp adminpb.ExportEntitiesResponse 359 if err := op.lro.Poll(ctx, &resp, opts...); err != nil { 360 return nil, err 361 } 362 if !op.Done() { 363 return nil, nil 364 } 365 return &resp, nil 366} 367 368// Metadata returns metadata associated with the long-running operation. 369// Metadata itself does not contact the server, but Poll does. 370// To get the latest metadata, call this method after a successful call to Poll. 371// If the metadata is not available, the returned metadata and error are both nil. 372func (op *ExportEntitiesOperation) Metadata() (*adminpb.ExportEntitiesMetadata, error) { 373 var meta adminpb.ExportEntitiesMetadata 374 if err := op.lro.Metadata(&meta); err == longrunning.ErrNoMetadata { 375 return nil, nil 376 } else if err != nil { 377 return nil, err 378 } 379 return &meta, nil 380} 381 382// Done reports whether the long-running operation has completed. 383func (op *ExportEntitiesOperation) Done() bool { 384 return op.lro.Done() 385} 386 387// Name returns the name of the long-running operation. 388// The name is assigned by the server and is unique within the service from which the operation is created. 389func (op *ExportEntitiesOperation) Name() string { 390 return op.lro.Name() 391} 392 393// ImportEntitiesOperation manages a long-running operation from ImportEntities. 394type ImportEntitiesOperation struct { 395 lro *longrunning.Operation 396} 397 398// ImportEntitiesOperation returns a new ImportEntitiesOperation from a given name. 399// The name must be that of a previously created ImportEntitiesOperation, possibly from a different process. 400func (c *DatastoreAdminClient) ImportEntitiesOperation(name string) *ImportEntitiesOperation { 401 return &ImportEntitiesOperation{ 402 lro: longrunning.InternalNewOperation(c.LROClient, &longrunningpb.Operation{Name: name}), 403 } 404} 405 406// Wait blocks until the long-running operation is completed, returning the response and any errors encountered. 407// 408// See documentation of Poll for error-handling information. 409func (op *ImportEntitiesOperation) Wait(ctx context.Context, opts ...gax.CallOption) error { 410 return op.lro.WaitWithInterval(ctx, nil, time.Minute, opts...) 411} 412 413// Poll fetches the latest state of the long-running operation. 414// 415// Poll also fetches the latest metadata, which can be retrieved by Metadata. 416// 417// If Poll fails, the error is returned and op is unmodified. If Poll succeeds and 418// the operation has completed with failure, the error is returned and op.Done will return true. 419// If Poll succeeds and the operation has completed successfully, 420// op.Done will return true, and the response of the operation is returned. 421// If Poll succeeds and the operation has not completed, the returned response and error are both nil. 422func (op *ImportEntitiesOperation) Poll(ctx context.Context, opts ...gax.CallOption) error { 423 return op.lro.Poll(ctx, nil, opts...) 424} 425 426// Metadata returns metadata associated with the long-running operation. 427// Metadata itself does not contact the server, but Poll does. 428// To get the latest metadata, call this method after a successful call to Poll. 429// If the metadata is not available, the returned metadata and error are both nil. 430func (op *ImportEntitiesOperation) Metadata() (*adminpb.ImportEntitiesMetadata, error) { 431 var meta adminpb.ImportEntitiesMetadata 432 if err := op.lro.Metadata(&meta); err == longrunning.ErrNoMetadata { 433 return nil, nil 434 } else if err != nil { 435 return nil, err 436 } 437 return &meta, nil 438} 439 440// Done reports whether the long-running operation has completed. 441func (op *ImportEntitiesOperation) Done() bool { 442 return op.lro.Done() 443} 444 445// Name returns the name of the long-running operation. 446// The name is assigned by the server and is unique within the service from which the operation is created. 447func (op *ImportEntitiesOperation) Name() string { 448 return op.lro.Name() 449} 450 451// IndexIterator manages a stream of *adminpb.Index. 452type IndexIterator struct { 453 items []*adminpb.Index 454 pageInfo *iterator.PageInfo 455 nextFunc func() error 456 457 // Response is the raw response for the current page. 458 // It must be cast to the RPC response type. 459 // Calling Next() or InternalFetch() updates this value. 460 Response interface{} 461 462 // InternalFetch is for use by the Google Cloud Libraries only. 463 // It is not part of the stable interface of this package. 464 // 465 // InternalFetch returns results from a single call to the underlying RPC. 466 // The number of results is no greater than pageSize. 467 // If there are no more results, nextPageToken is empty and err is nil. 468 InternalFetch func(pageSize int, pageToken string) (results []*adminpb.Index, nextPageToken string, err error) 469} 470 471// PageInfo supports pagination. See the google.golang.org/api/iterator package for details. 472func (it *IndexIterator) PageInfo() *iterator.PageInfo { 473 return it.pageInfo 474} 475 476// Next returns the next result. Its second return value is iterator.Done if there are no more 477// results. Once Next returns Done, all subsequent calls will return Done. 478func (it *IndexIterator) Next() (*adminpb.Index, error) { 479 var item *adminpb.Index 480 if err := it.nextFunc(); err != nil { 481 return item, err 482 } 483 item = it.items[0] 484 it.items = it.items[1:] 485 return item, nil 486} 487 488func (it *IndexIterator) bufLen() int { 489 return len(it.items) 490} 491 492func (it *IndexIterator) takeBuf() interface{} { 493 b := it.items 494 it.items = nil 495 return b 496} 497