feat: add Database.SourceInfo and Database.source_info (information a…

…bout database provenance, specifically for restored databases) (#963) * docs: Clarify maximum retention of backups (max 14 weeks) docs: Remove note about backups running at a specific time docs: Standardize on the capitalization of "ID" PiperOrigin-RevId: 668987834 Source-Link: googleapis/googleapis@296afd1 Source-Link: googleapis/googleapis-gen@f4db040 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiZjRkYjA0MDA0YzY0ZDUyZjg3YTk5MjZlNzAxODU5NTc3MTNlOGI1YiJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * feat: add Database.SourceInfo and Database.source_info (information about database provenance, specifically for restored databases) feat: add Database.CmekConfig and Database.cmek_config (information about CMEK enablement) feat: allow specifying an encryption_config when restoring a database feat: add Database.delete_time (the time a database was deleted, if it ever was) feat: add Database.previous_id (if a database was deleted, what ID it was using beforehand) docs: fix assorted capitalization issues with the word "ID" docs: clarify restore details PiperOrigin-RevId: 671737474 Source-Link: googleapis/googleapis@070b0fd Source-Link: googleapis/googleapis-gen@9921c68 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiOTkyMWM2ODIzNzkzNDk4YjI5ZTI1M2Y0ZWY0MWQxMjMzNjEyNWU1NCJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Lingqing Gan <lingqing.gan@gmail.com>
googleapis · Sep 6, 2024 · 4e15714 · 4e15714
1 parent 1614b3f
commit 4e15714
Show file tree

Hide file tree

Showing 11 changed files with 348 additions and 48 deletions.
diff --git a/google/cloud/firestore_admin_v1/services/firestore_admin/async_client.py b/google/cloud/firestore_admin_v1/services/firestore_admin/async_client.py
@@ -128,6 +128,8 @@ class FirestoreAdminAsyncClient:
     parse_index_path = staticmethod(FirestoreAdminClient.parse_index_path)
     location_path = staticmethod(FirestoreAdminClient.location_path)
     parse_location_path = staticmethod(FirestoreAdminClient.parse_location_path)
+    operation_path = staticmethod(FirestoreAdminClient.operation_path)
+    parse_operation_path = staticmethod(FirestoreAdminClient.parse_operation_path)
     common_billing_account_path = staticmethod(
         FirestoreAdminClient.common_billing_account_path
     )
@@ -834,7 +836,7 @@ async def sample_get_field():
                 database.
                 Fields are grouped by their "Collection
                 Group", which represent all collections
-                in the database with the same id.
+                in the database with the same ID.
 
         """
         # Create or coerce a protobuf request object.
@@ -967,7 +969,7 @@ async def sample_update_field():
 
                    Fields are grouped by their "Collection Group", which
                    represent all collections in the database with the
-                   same id.
+                   same ID.
 
         """
         # Create or coerce a protobuf request object.
@@ -1632,7 +1634,7 @@ async def sample_create_database():
                 last a letter or a number. Must not be UUID-like
                 /[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}/.
 
-                "(default)" database id is also valid.
+                "(default)" database ID is also valid.
 
                 This corresponds to the ``database_id`` field
                 on the ``request`` instance; if ``request`` is provided, this
@@ -2548,7 +2550,7 @@ async def sample_restore_database():
         Args:
             request (Optional[Union[google.cloud.firestore_admin_v1.types.RestoreDatabaseRequest, dict]]):
                 The request object. The request message for
-                [FirestoreAdmin.RestoreDatabase][google.firestore.admin.v1.RestoreDatabase].
+                [FirestoreAdmin.RestoreDatabase][google.firestore.admin.v1.FirestoreAdmin.RestoreDatabase].
             retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,
                 should be retried.
             timeout (float): The timeout for this request.

diff --git a/google/cloud/firestore_admin_v1/services/firestore_admin/client.py b/google/cloud/firestore_admin_v1/services/firestore_admin/client.py
@@ -378,6 +378,28 @@ def parse_location_path(path: str) -> Dict[str, str]:
         m = re.match(r"^projects/(?P<project>.+?)/locations/(?P<location>.+?)$", path)
         return m.groupdict() if m else {}
 
+    @staticmethod
+    def operation_path(
+        project: str,
+        database: str,
+        operation: str,
+    ) -> str:
+        """Returns a fully-qualified operation string."""
+        return "projects/{project}/databases/{database}/operations/{operation}".format(
+            project=project,
+            database=database,
+            operation=operation,
+        )
+
+    @staticmethod
+    def parse_operation_path(path: str) -> Dict[str, str]:
+        """Parses a operation path into its component segments."""
+        m = re.match(
+            r"^projects/(?P<project>.+?)/databases/(?P<database>.+?)/operations/(?P<operation>.+?)$",
+            path,
+        )
+        return m.groupdict() if m else {}
+
     @staticmethod
     def common_billing_account_path(
         billing_account: str,
@@ -1354,7 +1376,7 @@ def sample_get_field():
                 database.
                 Fields are grouped by their "Collection
                 Group", which represent all collections
-                in the database with the same id.
+                in the database with the same ID.
 
         """
         # Create or coerce a protobuf request object.
@@ -1484,7 +1506,7 @@ def sample_update_field():
 
                    Fields are grouped by their "Collection Group", which
                    represent all collections in the database with the
-                   same id.
+                   same ID.
 
         """
         # Create or coerce a protobuf request object.
@@ -2134,7 +2156,7 @@ def sample_create_database():
                 last a letter or a number. Must not be UUID-like
                 /[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}/.
 
-                "(default)" database id is also valid.
+                "(default)" database ID is also valid.
 
                 This corresponds to the ``database_id`` field
                 on the ``request`` instance; if ``request`` is provided, this
@@ -3026,7 +3048,7 @@ def sample_restore_database():
         Args:
             request (Union[google.cloud.firestore_admin_v1.types.RestoreDatabaseRequest, dict]):
                 The request object. The request message for
-                [FirestoreAdmin.RestoreDatabase][google.firestore.admin.v1.RestoreDatabase].
+                [FirestoreAdmin.RestoreDatabase][google.firestore.admin.v1.FirestoreAdmin.RestoreDatabase].
             retry (google.api_core.retry.Retry): Designation of what errors, if any,
                 should be retried.
             timeout (float): The timeout for this request.

diff --git a/google/cloud/firestore_admin_v1/services/firestore_admin/transports/rest.py b/google/cloud/firestore_admin_v1/services/firestore_admin/transports/rest.py
@@ -2157,7 +2157,7 @@ def __call__(
                 database.
                 Fields are grouped by their "Collection
                 Group", which represent all collections
-                in the database with the same id.
+                in the database with the same ID.
 
             """
 
@@ -2861,7 +2861,7 @@ def __call__(
             Args:
                 request (~.firestore_admin.RestoreDatabaseRequest):
                     The request object. The request message for
-                [FirestoreAdmin.RestoreDatabase][google.firestore.admin.v1.RestoreDatabase].
+                [FirestoreAdmin.RestoreDatabase][google.firestore.admin.v1.FirestoreAdmin.RestoreDatabase].
                 retry (google.api_core.retry.Retry): Designation of what errors, if any,
                     should be retried.
                 timeout (float): The timeout for this request.

diff --git a/google/cloud/firestore_admin_v1/types/database.py b/google/cloud/firestore_admin_v1/types/database.py
@@ -50,6 +50,10 @@ class Database(proto.Message):
             database was most recently updated. Note this
             only includes updates to the database resource
             and not data contained by the database.
+        delete_time (google.protobuf.timestamp_pb2.Timestamp):
+            Output only. The timestamp at which this
+            database was deleted. Only set if the database
+            has been deleted.
         location_id (str):
             The location of the database. Available
             locations are listed at
@@ -93,8 +97,8 @@ class Database(proto.Message):
             this database.
         key_prefix (str):
             Output only. The key_prefix for this database. This
-            key_prefix is used, in combination with the project id ("~")
-            to construct the application id that is returned from the
+            key_prefix is used, in combination with the project ID ("~")
+            to construct the application ID that is returned from the
             Cloud Datastore APIs in Google App Engine first generation
             runtimes.
 
@@ -103,6 +107,16 @@ class Database(proto.Message):
             v~foo).
         delete_protection_state (google.cloud.firestore_admin_v1.types.Database.DeleteProtectionState):
             State of delete protection for the database.
+        cmek_config (google.cloud.firestore_admin_v1.types.Database.CmekConfig):
+            Optional. Presence indicates CMEK is enabled
+            for this database.
+        previous_id (str):
+            Output only. The database resource's prior
+            database ID. This field is only populated for
+            deleted databases.
+        source_info (google.cloud.firestore_admin_v1.types.Database.SourceInfo):
+            Output only. Information about the provenance
+            of this database.
         etag (str):
             This checksum is computed by the server based
             on the value of other fields, and may be sent on
@@ -120,8 +134,7 @@ class DatabaseType(proto.Enum):
 
         Values:
             DATABASE_TYPE_UNSPECIFIED (0):
-                The default value. This value is used if the
-                database type is omitted.
+                Not used.
             FIRESTORE_NATIVE (1):
                 Firestore Native Mode
             DATASTORE_MODE (2):
@@ -225,6 +238,173 @@ class DeleteProtectionState(proto.Enum):
         DELETE_PROTECTION_DISABLED = 1
         DELETE_PROTECTION_ENABLED = 2
 
+    class CmekConfig(proto.Message):
+        r"""The CMEK (Customer Managed Encryption Key) configuration for
+        a Firestore database. If not present, the database is secured by
+        the default Google encryption key.
+
+        Attributes:
+            kms_key_name (str):
+                Required. Only keys in the same location as this database
+                are allowed to be used for encryption.
+
+                For Firestore's nam5 multi-region, this corresponds to Cloud
+                KMS multi-region us. For Firestore's eur3 multi-region, this
+                corresponds to Cloud KMS multi-region europe. See
+                https://cloud.google.com/kms/docs/locations.
+
+                The expected format is
+                ``projects/{project_id}/locations/{kms_location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}``.
+            active_key_version (MutableSequence[str]):
+                Output only. Currently in-use `KMS key
+                versions <https://cloud.google.com/kms/docs/resource-hierarchy#key_versions>`__.
+                During `key
+                rotation <https://cloud.google.com/kms/docs/key-rotation>`__,
+                there can be multiple in-use key versions.
+
+                The expected format is
+                ``projects/{project_id}/locations/{kms_location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/cryptoKeyVersions/{key_version}``.
+        """
+
+        kms_key_name: str = proto.Field(
+            proto.STRING,
+            number=1,
+        )
+        active_key_version: MutableSequence[str] = proto.RepeatedField(
+            proto.STRING,
+            number=2,
+        )
+
+    class SourceInfo(proto.Message):
+        r"""Information about the provenance of this database.
+
+        .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
+        Attributes:
+            backup (google.cloud.firestore_admin_v1.types.Database.SourceInfo.BackupSource):
+                If set, this database was restored from the
+                specified backup (or a snapshot thereof).
+
+                This field is a member of `oneof`_ ``source``.
+            operation (str):
+                The associated long-running operation. This field may not be
+                set after the operation has completed. Format:
+                ``projects/{project}/databases/{database}/operations/{operation}``.
+        """
+
+        class BackupSource(proto.Message):
+            r"""Information about a backup that was used to restore a
+            database.
+
+            Attributes:
+                backup (str):
+                    The resource name of the backup that was used to restore
+                    this database. Format:
+                    ``projects/{project}/locations/{location}/backups/{backup}``.
+            """
+
+            backup: str = proto.Field(
+                proto.STRING,
+                number=1,
+            )
+
+        backup: "Database.SourceInfo.BackupSource" = proto.Field(
+            proto.MESSAGE,
+            number=1,
+            oneof="source",
+            message="Database.SourceInfo.BackupSource",
+        )
+        operation: str = proto.Field(
+            proto.STRING,
+            number=3,
+        )
+
+    class EncryptionConfig(proto.Message):
+        r"""Encryption configuration for a new database being created from
+        another source.
+
+        The source could be a [Backup][google.firestore.admin.v1.Backup] .
+
+        This message has `oneof`_ fields (mutually exclusive fields).
+        For each oneof, at most one member field can be set at the same time.
+        Setting any member of the oneof automatically clears all other
+        members.
+
+        .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
+        Attributes:
+            google_default_encryption (google.cloud.firestore_admin_v1.types.Database.EncryptionConfig.GoogleDefaultEncryptionOptions):
+                Use Google default encryption.
+
+                This field is a member of `oneof`_ ``encryption_type``.
+            use_source_encryption (google.cloud.firestore_admin_v1.types.Database.EncryptionConfig.SourceEncryptionOptions):
+                The database will use the same encryption
+                configuration as the source.
+
+                This field is a member of `oneof`_ ``encryption_type``.
+            customer_managed_encryption (google.cloud.firestore_admin_v1.types.Database.EncryptionConfig.CustomerManagedEncryptionOptions):
+                Use Customer Managed Encryption Keys (CMEK)
+                for encryption.
+
+                This field is a member of `oneof`_ ``encryption_type``.
+        """
+
+        class GoogleDefaultEncryptionOptions(proto.Message):
+            r"""The configuration options for using Google default
+            encryption.
+
+            """
+
+        class SourceEncryptionOptions(proto.Message):
+            r"""The configuration options for using the same encryption
+            method as the source.
+
+            """
+
+        class CustomerManagedEncryptionOptions(proto.Message):
+            r"""The configuration options for using CMEK (Customer Managed
+            Encryption Key) encryption.
+
+            Attributes:
+                kms_key_name (str):
+                    Required. Only keys in the same location as the database are
+                    allowed to be used for encryption.
+
+                    For Firestore's nam5 multi-region, this corresponds to Cloud
+                    KMS multi-region us. For Firestore's eur3 multi-region, this
+                    corresponds to Cloud KMS multi-region europe. See
+                    https://cloud.google.com/kms/docs/locations.
+
+                    The expected format is
+                    ``projects/{project_id}/locations/{kms_location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}``.
+            """
+
+            kms_key_name: str = proto.Field(
+                proto.STRING,
+                number=1,
+            )
+
+        google_default_encryption: "Database.EncryptionConfig.GoogleDefaultEncryptionOptions" = proto.Field(
+            proto.MESSAGE,
+            number=1,
+            oneof="encryption_type",
+            message="Database.EncryptionConfig.GoogleDefaultEncryptionOptions",
+        )
+        use_source_encryption: "Database.EncryptionConfig.SourceEncryptionOptions" = (
+            proto.Field(
+                proto.MESSAGE,
+                number=2,
+                oneof="encryption_type",
+                message="Database.EncryptionConfig.SourceEncryptionOptions",
+            )
+        )
+        customer_managed_encryption: "Database.EncryptionConfig.CustomerManagedEncryptionOptions" = proto.Field(
+            proto.MESSAGE,
+            number=3,
+            oneof="encryption_type",
+            message="Database.EncryptionConfig.CustomerManagedEncryptionOptions",
+        )
+
     name: str = proto.Field(
         proto.STRING,
         number=1,
@@ -243,6 +423,11 @@ class DeleteProtectionState(proto.Enum):
         number=6,
         message=timestamp_pb2.Timestamp,
     )
+    delete_time: timestamp_pb2.Timestamp = proto.Field(
+        proto.MESSAGE,
+        number=7,
+        message=timestamp_pb2.Timestamp,
+    )
     location_id: str = proto.Field(
         proto.STRING,
         number=9,
@@ -286,6 +471,20 @@ class DeleteProtectionState(proto.Enum):
         number=22,
         enum=DeleteProtectionState,
     )
+    cmek_config: CmekConfig = proto.Field(
+        proto.MESSAGE,
+        number=23,
+        message=CmekConfig,
+    )
+    previous_id: str = proto.Field(
+        proto.STRING,
+        number=25,
+    )
+    source_info: SourceInfo = proto.Field(
+        proto.MESSAGE,
+        number=26,
+        message=SourceInfo,
+    )
     etag: str = proto.Field(
         proto.STRING,
         number=99,

diff --git a/google/cloud/firestore_admin_v1/types/field.py b/google/cloud/firestore_admin_v1/types/field.py
@@ -34,7 +34,7 @@ class Field(proto.Message):
     r"""Represents a single field in the database.
 
     Fields are grouped by their "Collection Group", which represent
-    all collections in the database with the same id.
+    all collections in the database with the same ID.
 
     Attributes:
         name (str):