feat: define Datastore -> Firestore in Datastore mode migration long running operation metadata

google/cloud/datastore_admin_v1/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright 2020 Google LLC
+# Copyright 2022 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -19,6 +19,7 @@
 
 from .types.datastore_admin import CommonMetadata
 from .types.datastore_admin import CreateIndexRequest
+from .types.datastore_admin import DatastoreFirestoreMigrationMetadata
 from .types.datastore_admin import DeleteIndexRequest
 from .types.datastore_admin import EntityFilter
 from .types.datastore_admin import ExportEntitiesMetadata
@@ -33,12 +34,17 @@
 from .types.datastore_admin import Progress
 from .types.datastore_admin import OperationType
 from .types.index import Index
+from .types.migration import MigrationProgressEvent
+from .types.migration import MigrationStateEvent
+from .types.migration import MigrationState
+from .types.migration import MigrationStep
 
 __all__ = (
     "DatastoreAdminAsyncClient",
     "CommonMetadata",
     "CreateIndexRequest",
     "DatastoreAdminClient",
+    "DatastoreFirestoreMigrationMetadata",
     "DeleteIndexRequest",
     "EntityFilter",
     "ExportEntitiesMetadata",
@@ -51,6 +57,10 @@
     "IndexOperationMetadata",
     "ListIndexesRequest",
     "ListIndexesResponse",
+    "MigrationProgressEvent",
+    "MigrationState",
+    "MigrationStateEvent",
+    "MigrationStep",
     "OperationType",
     "Progress",
 )

google/cloud/datastore_admin_v1/services/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright 2020 Google LLC
+# Copyright 2022 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

google/cloud/datastore_admin_v1/services/datastore_admin/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright 2020 Google LLC
+# Copyright 2022 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

google/cloud/datastore_admin_v1/services/datastore_admin/async_client.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright 2020 Google LLC
+# Copyright 2022 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,7 +16,7 @@
 from collections import OrderedDict
 import functools
 import re
-from typing import Dict, Sequence, Tuple, Type, Union
+from typing import Dict, Optional, Sequence, Tuple, Type, Union
 import pkg_resources
 
 from google.api_core.client_options import ClientOptions
@@ -31,12 +31,12 @@
 except AttributeError:  # pragma: NO COVER
     OptionalRetry = Union[retries.Retry, object]  # type: ignore
 
-from google.api_core import operation
-from google.api_core import operation_async
+from google.api_core import operation  # type: ignore
+from google.api_core import operation_async  # type: ignore
 from google.cloud.datastore_admin_v1.services.datastore_admin import pagers
 from google.cloud.datastore_admin_v1.types import datastore_admin
 from google.cloud.datastore_admin_v1.types import index
-from google.protobuf import empty_pb2
+from google.protobuf import empty_pb2  # type: ignore
 from .transports.base import DatastoreAdminTransport, DEFAULT_CLIENT_INFO
 from .transports.grpc_asyncio import DatastoreAdminGrpcAsyncIOTransport
 from .client import DatastoreAdminClient
@@ -166,6 +166,42 @@ def from_service_account_file(cls, filename: str, *args, **kwargs):
 
     from_service_account_json = from_service_account_file
 
+    @classmethod
+    def get_mtls_endpoint_and_cert_source(
+        cls, client_options: Optional[ClientOptions] = None
+    ):
+        """Return the API endpoint and client cert source for mutual TLS.
+
+        The client cert source is determined in the following order:
+        (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
+        client cert source is None.
+        (2) if `client_options.client_cert_source` is provided, use the provided one; if the
+        default client cert source exists, use the default one; otherwise the client cert
+        source is None.
+
+        The API endpoint is determined in the following order:
+        (1) if `client_options.api_endpoint` if provided, use the provided one.
+        (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
+        default mTLS endpoint; if the environment variabel is "never", use the default API
+        endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
+        use the default API endpoint.
+
+        More details can be found at https://google.aip.dev/auth/4114.
+
+        Args:
+            client_options (google.api_core.client_options.ClientOptions): Custom options for the
+                client. Only the `api_endpoint` and `client_cert_source` properties may be used
+                in this method.
+
+        Returns:
+            Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
+                client cert source to use.
+
+        Raises:
+            google.auth.exceptions.MutualTLSChannelError: If any errors happen.
+        """
+        return DatastoreAdminClient.get_mtls_endpoint_and_cert_source(client_options)  # type: ignore
+
     @property
     def transport(self) -> DatastoreAdminTransport:
         """Returns the transport used by the client instance.
@@ -249,6 +285,31 @@ async def export_entities(
         before completion it may leave partial data behind in
         Google Cloud Storage.
 
+
+        .. code-block:: python
+
+            from google.cloud import datastore_admin_v1
+
+            def sample_export_entities():
+                # Create a client
+                client = datastore_admin_v1.DatastoreAdminClient()
+
+                # Initialize request argument(s)
+                request = datastore_admin_v1.ExportEntitiesRequest(
+                    project_id="project_id_value",
+                    output_url_prefix="output_url_prefix_value",
+                )
+
+                # Make the request
+                operation = client.export_entities(request=request)
+
+                print("Waiting for operation to complete...")
+
+                response = operation.result()
+
+                # Handle the response
+                print(response)
+
         Args:
             request (Union[google.cloud.datastore_admin_v1.types.ExportEntitiesRequest, dict]):
                 The request object. The request for
@@ -316,7 +377,7 @@ async def export_entities(
 
         """
         # Create or coerce a protobuf request object.
-        # Sanity check: If we got a request object, we should *not* have
+        # Quick check: If we got a request object, we should *not* have
         # gotten any keyword arguments that map to the request.
         has_flattened_params = any(
             [project_id, labels, entity_filter, output_url_prefix]
@@ -383,6 +444,31 @@ async def import_entities(
         is possible that a subset of the data has already been
         imported to Cloud Datastore.
 
+
+        .. code-block:: python
+
+            from google.cloud import datastore_admin_v1
+
+            def sample_import_entities():
+                # Create a client
+                client = datastore_admin_v1.DatastoreAdminClient()
+
+                # Initialize request argument(s)
+                request = datastore_admin_v1.ImportEntitiesRequest(
+                    project_id="project_id_value",
+                    input_url="input_url_value",
+                )
+
+                # Make the request
+                operation = client.import_entities(request=request)
+
+                print("Waiting for operation to complete...")
+
+                response = operation.result()
+
+                # Handle the response
+                print(response)
+
         Args:
             request (Union[google.cloud.datastore_admin_v1.types.ImportEntitiesRequest, dict]):
                 The request object. The request for
@@ -456,7 +542,7 @@ async def import_entities(
 
         """
         # Create or coerce a protobuf request object.
-        # Sanity check: If we got a request object, we should *not* have
+        # Quick check: If we got a request object, we should *not* have
         # gotten any keyword arguments that map to the request.
         has_flattened_params = any([project_id, labels, input_url, entity_filter])
         if request is not None and has_flattened_params:
@@ -525,6 +611,29 @@ async def create_index(
 
         Indexes with a single property cannot be created.
 
+
+        .. code-block:: python
+
+            from google.cloud import datastore_admin_v1
+
+            def sample_create_index():
+                # Create a client
+                client = datastore_admin_v1.DatastoreAdminClient()
+
+                # Initialize request argument(s)
+                request = datastore_admin_v1.CreateIndexRequest(
+                )
+
+                # Make the request
+                operation = client.create_index(request=request)
+
+                print("Waiting for operation to complete...")
+
+                response = operation.result()
+
+                # Handle the response
+                print(response)
+
         Args:
             request (Union[google.cloud.datastore_admin_v1.types.CreateIndexRequest, dict]):
                 The request object. The request for
@@ -592,6 +701,29 @@ async def delete_index(
         [delete][google.datastore.admin.v1.DatastoreAdmin.DeleteIndex]
         again.
 
+
+        .. code-block:: python
+
+            from google.cloud import datastore_admin_v1
+
+            def sample_delete_index():
+                # Create a client
+                client = datastore_admin_v1.DatastoreAdminClient()
+
+                # Initialize request argument(s)
+                request = datastore_admin_v1.DeleteIndexRequest(
+                )
+
+                # Make the request
+                operation = client.delete_index(request=request)
+
+                print("Waiting for operation to complete...")
+
+                response = operation.result()
+
+                # Handle the response
+                print(response)
+
         Args:
             request (Union[google.cloud.datastore_admin_v1.types.DeleteIndexRequest, dict]):
                 The request object. The request for
@@ -646,6 +778,24 @@ async def get_index(
     ) -> index.Index:
         r"""Gets an index.
 
+        .. code-block:: python
+
+            from google.cloud import datastore_admin_v1
+
+            def sample_get_index():
+                # Create a client
+                client = datastore_admin_v1.DatastoreAdminClient()
+
+                # Initialize request argument(s)
+                request = datastore_admin_v1.GetIndexRequest(
+                )
+
+                # Make the request
+                response = client.get_index(request=request)
+
+                # Handle the response
+                print(response)
+
         Args:
             request (Union[google.cloud.datastore_admin_v1.types.GetIndexRequest, dict]):
                 The request object. The request for
@@ -700,6 +850,26 @@ async def list_indexes(
         the list of indexes and may occasionally return stale
         results.
 
+
+        .. code-block:: python
+
+            from google.cloud import datastore_admin_v1
+
+            def sample_list_indexes():
+                # Create a client
+                client = datastore_admin_v1.DatastoreAdminClient()
+
+                # Initialize request argument(s)
+                request = datastore_admin_v1.ListIndexesRequest(
+                )
+
+                # Make the request
+                page_result = client.list_indexes(request=request)
+
+                # Handle the response
+                for response in page_result:
+                    print(response)
+
         Args:
             request (Union[google.cloud.datastore_admin_v1.types.ListIndexesRequest, dict]):
                 The request object. The request for