feat: add document purge API (#11140)

* feat: add document purge API
docs: keep the API doc up-to-date with recent changes

PiperOrigin-RevId: 528071547

Source-Link: googleapis/googleapis@32e0dc1

Source-Link: googleapis/googleapis-gen@f5843c4
Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLWRpc2NvdmVyeWVuZ2luZS8uT3dsQm90LnlhbWwiLCJoIjoiZjU4NDNjNGJjNDBlZGEyMzZlNTRkMzYzZDc5NDIwMGY3N2RlN2Q4OSJ9

* 🦉 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: Anthonios Partheniou <partheniou@google.com>

packages/google-cloud-discoveryengine/google/cloud/discoveryengine/__init__.py

@@ -83,6 +83,11 @@
     ImportUserEventsRequest,
     ImportUserEventsResponse,
 )
+from google.cloud.discoveryengine_v1beta.types.purge_config import (
+    PurgeDocumentsMetadata,
+    PurgeDocumentsRequest,
+    PurgeDocumentsResponse,
+)
 from google.cloud.discoveryengine_v1beta.types.recommendation_service import (
     RecommendRequest,
     RecommendResponse,
@@ -152,6 +157,9 @@
     "ImportUserEventsMetadata",
     "ImportUserEventsRequest",
     "ImportUserEventsResponse",
+    "PurgeDocumentsMetadata",
+    "PurgeDocumentsRequest",
+    "PurgeDocumentsResponse",
     "RecommendRequest",
     "RecommendResponse",
     "Schema",

packages/google-cloud-discoveryengine/google/cloud/discoveryengine_v1beta/__init__.py

@@ -55,6 +55,11 @@
     ImportUserEventsRequest,
     ImportUserEventsResponse,
 )
+from .types.purge_config import (
+    PurgeDocumentsMetadata,
+    PurgeDocumentsRequest,
+    PurgeDocumentsResponse,
+)
 from .types.recommendation_service import RecommendRequest, RecommendResponse
 from .types.schema import Schema
 from .types.schema_service import (
@@ -122,6 +127,9 @@
     "MediaInfo",
     "PageInfo",
     "PanelInfo",
+    "PurgeDocumentsMetadata",
+    "PurgeDocumentsRequest",
+    "PurgeDocumentsResponse",
     "RecommendRequest",
     "RecommendResponse",
     "RecommendationServiceClient",

packages/google-cloud-discoveryengine/google/cloud/discoveryengine_v1beta/gapic_metadata.json

@@ -69,6 +69,11 @@
                 "list_documents"
               ]
             },
+            "PurgeDocuments": {
+              "methods": [
+                "purge_documents"
+              ]
+            },
             "UpdateDocument": {
               "methods": [
                 "update_document"
@@ -104,6 +109,11 @@
                 "list_documents"
               ]
             },
+            "PurgeDocuments": {
+              "methods": [
+                "purge_documents"
+              ]
+            },
             "UpdateDocument": {
               "methods": [
                 "update_document"
@@ -139,6 +149,11 @@
                 "list_documents"
               ]
             },
+            "PurgeDocuments": {
+              "methods": [
+                "purge_documents"
+              ]
+            },
             "UpdateDocument": {
               "methods": [
                 "update_document"

packages/google-cloud-discoveryengine/google/cloud/discoveryengine_v1beta/services/document_service/async_client.py

@@ -48,7 +48,11 @@
 from google.protobuf import struct_pb2  # type: ignore
 
 from google.cloud.discoveryengine_v1beta.services.document_service import pagers
-from google.cloud.discoveryengine_v1beta.types import document_service, import_config
+from google.cloud.discoveryengine_v1beta.types import (
+    document_service,
+    import_config,
+    purge_config,
+)
 from google.cloud.discoveryengine_v1beta.types import document
 from google.cloud.discoveryengine_v1beta.types import document as gcd_document
 
@@ -912,6 +916,123 @@ async def sample_import_documents():
         # Done; return the response.
         return response
 
+    async def purge_documents(
+        self,
+        request: Optional[Union[purge_config.PurgeDocumentsRequest, dict]] = None,
+        *,
+        retry: OptionalRetry = gapic_v1.method.DEFAULT,
+        timeout: Union[float, object] = gapic_v1.method.DEFAULT,
+        metadata: Sequence[Tuple[str, str]] = (),
+    ) -> operation_async.AsyncOperation:
+        r"""Permanently deletes all selected
+        [Document][google.cloud.discoveryengine.v1beta.Document]s in a
+        branch.
+
+        This process is asynchronous. Depending on the number of
+        [Document][google.cloud.discoveryengine.v1beta.Document]s to be
+        deleted, this operation can take hours to complete. Before the
+        delete operation completes, some
+        [Document][google.cloud.discoveryengine.v1beta.Document]s might
+        still be returned by
+        [DocumentService.GetDocument][google.cloud.discoveryengine.v1beta.DocumentService.GetDocument]
+        or
+        [DocumentService.ListDocuments][google.cloud.discoveryengine.v1beta.DocumentService.ListDocuments].
+
+        To get a list of the
+        [Document][google.cloud.discoveryengine.v1beta.Document]s to be
+        deleted, set
+        [PurgeDocumentsRequest.force][google.cloud.discoveryengine.v1beta.PurgeDocumentsRequest.force]
+        to false.
+
+        .. code-block:: python
+
+            # This snippet has been automatically generated and should be regarded as a
+            # code template only.
+            # It will require modifications to work:
+            # - It may require correct/in-range values for request initialization.
+            # - It may require specifying regional endpoints when creating the service
+            #   client as shown in:
+            #   https://googleapis.dev/python/google-api-core/latest/client_options.html
+            from google.cloud import discoveryengine_v1beta
+
+            async def sample_purge_documents():
+                # Create a client
+                client = discoveryengine_v1beta.DocumentServiceAsyncClient()
+
+                # Initialize request argument(s)
+                request = discoveryengine_v1beta.PurgeDocumentsRequest(
+                    parent="parent_value",
+                    filter="filter_value",
+                )
+
+                # Make the request
+                operation = client.purge_documents(request=request)
+
+                print("Waiting for operation to complete...")
+
+                response = (await operation).result()
+
+                # Handle the response
+                print(response)
+
+        Args:
+            request (Optional[Union[google.cloud.discoveryengine_v1beta.types.PurgeDocumentsRequest, dict]]):
+                The request object. Request message for
+                [DocumentService.PurgeDocuments][google.cloud.discoveryengine.v1beta.DocumentService.PurgeDocuments]
+                method.
+            retry (google.api_core.retry.Retry): Designation of what errors, if any,
+                should be retried.
+            timeout (float): The timeout for this request.
+            metadata (Sequence[Tuple[str, str]]): Strings which should be
+                sent along with the request as metadata.
+
+        Returns:
+            google.api_core.operation_async.AsyncOperation:
+                An object representing a long-running operation.
+
+                The result type for the operation will be :class:`google.cloud.discoveryengine_v1beta.types.PurgeDocumentsResponse` Response message for
+                   [DocumentService.PurgeDocuments][google.cloud.discoveryengine.v1beta.DocumentService.PurgeDocuments]
+                   method. If the long running operation is successfully
+                   done, then this message is returned by the
+                   google.longrunning.Operations.response field.
+
+        """
+        # Create or coerce a protobuf request object.
+        request = purge_config.PurgeDocumentsRequest(request)
+
+        # Wrap the RPC method; this adds retry and timeout information,
+        # and friendly error handling.
+        rpc = gapic_v1.method_async.wrap_method(
+            self._client._transport.purge_documents,
+            default_timeout=None,
+            client_info=DEFAULT_CLIENT_INFO,
+        )
+
+        # Certain fields should be provided within the metadata header;
+        # add these here.
+        metadata = tuple(metadata) + (
+            gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
+        )
+
+        # Send the request.
+        response = await rpc(
+            request,
+            retry=retry,
+            timeout=timeout,
+            metadata=metadata,
+        )
+
+        # Wrap the response in an operation future.
+        response = operation_async.from_gapic(
+            response,
+            self._client._transport.operations_client,
+            purge_config.PurgeDocumentsResponse,
+            metadata_type=purge_config.PurgeDocumentsMetadata,
+        )
+
+        # Done; return the response.
+        return response
+
     async def list_operations(
         self,
         request: Optional[operations_pb2.ListOperationsRequest] = None,

packages/google-cloud-discoveryengine/google/cloud/discoveryengine_v1beta/services/document_service/client.py

@@ -52,7 +52,11 @@
 from google.protobuf import struct_pb2  # type: ignore
 
 from google.cloud.discoveryengine_v1beta.services.document_service import pagers
-from google.cloud.discoveryengine_v1beta.types import document_service, import_config
+from google.cloud.discoveryengine_v1beta.types import (
+    document_service,
+    import_config,
+    purge_config,
+)
 from google.cloud.discoveryengine_v1beta.types import document
 from google.cloud.discoveryengine_v1beta.types import document as gcd_document
 
@@ -1160,6 +1164,124 @@ def sample_import_documents():
         # Done; return the response.
         return response
 
+    def purge_documents(
+        self,
+        request: Optional[Union[purge_config.PurgeDocumentsRequest, dict]] = None,
+        *,
+        retry: OptionalRetry = gapic_v1.method.DEFAULT,
+        timeout: Union[float, object] = gapic_v1.method.DEFAULT,
+        metadata: Sequence[Tuple[str, str]] = (),
+    ) -> operation.Operation:
+        r"""Permanently deletes all selected
+        [Document][google.cloud.discoveryengine.v1beta.Document]s in a
+        branch.
+
+        This process is asynchronous. Depending on the number of
+        [Document][google.cloud.discoveryengine.v1beta.Document]s to be
+        deleted, this operation can take hours to complete. Before the
+        delete operation completes, some
+        [Document][google.cloud.discoveryengine.v1beta.Document]s might
+        still be returned by
+        [DocumentService.GetDocument][google.cloud.discoveryengine.v1beta.DocumentService.GetDocument]
+        or
+        [DocumentService.ListDocuments][google.cloud.discoveryengine.v1beta.DocumentService.ListDocuments].
+
+        To get a list of the
+        [Document][google.cloud.discoveryengine.v1beta.Document]s to be
+        deleted, set
+        [PurgeDocumentsRequest.force][google.cloud.discoveryengine.v1beta.PurgeDocumentsRequest.force]
+        to false.
+
+        .. code-block:: python
+
+            # This snippet has been automatically generated and should be regarded as a
+            # code template only.
+            # It will require modifications to work:
+            # - It may require correct/in-range values for request initialization.
+            # - It may require specifying regional endpoints when creating the service
+            #   client as shown in:
+            #   https://googleapis.dev/python/google-api-core/latest/client_options.html
+            from google.cloud import discoveryengine_v1beta
+
+            def sample_purge_documents():
+                # Create a client
+                client = discoveryengine_v1beta.DocumentServiceClient()
+
+                # Initialize request argument(s)
+                request = discoveryengine_v1beta.PurgeDocumentsRequest(
+                    parent="parent_value",
+                    filter="filter_value",
+                )
+
+                # Make the request
+                operation = client.purge_documents(request=request)
+
+                print("Waiting for operation to complete...")
+
+                response = operation.result()
+
+                # Handle the response
+                print(response)
+
+        Args:
+            request (Union[google.cloud.discoveryengine_v1beta.types.PurgeDocumentsRequest, dict]):
+                The request object. Request message for
+                [DocumentService.PurgeDocuments][google.cloud.discoveryengine.v1beta.DocumentService.PurgeDocuments]
+                method.
+            retry (google.api_core.retry.Retry): Designation of what errors, if any,
+                should be retried.
+            timeout (float): The timeout for this request.
+            metadata (Sequence[Tuple[str, str]]): Strings which should be
+                sent along with the request as metadata.
+
+        Returns:
+            google.api_core.operation.Operation:
+                An object representing a long-running operation.
+
+                The result type for the operation will be :class:`google.cloud.discoveryengine_v1beta.types.PurgeDocumentsResponse` Response message for
+                   [DocumentService.PurgeDocuments][google.cloud.discoveryengine.v1beta.DocumentService.PurgeDocuments]
+                   method. If the long running operation is successfully
+                   done, then this message is returned by the
+                   google.longrunning.Operations.response field.
+
+        """
+        # Create or coerce a protobuf request object.
+        # Minor optimization to avoid making a copy if the user passes
+        # in a purge_config.PurgeDocumentsRequest.
+        # There's no risk of modifying the input as we've already verified
+        # there are no flattened fields.
+        if not isinstance(request, purge_config.PurgeDocumentsRequest):
+            request = purge_config.PurgeDocumentsRequest(request)
+
+        # Wrap the RPC method; this adds retry and timeout information,
+        # and friendly error handling.
+        rpc = self._transport._wrapped_methods[self._transport.purge_documents]
+
+        # Certain fields should be provided within the metadata header;
+        # add these here.
+        metadata = tuple(metadata) + (
+            gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
+        )
+
+        # Send the request.
+        response = rpc(
+            request,
+            retry=retry,
+            timeout=timeout,
+            metadata=metadata,
+        )
+
+        # Wrap the response in an operation future.
+        response = operation.from_gapic(
+            response,
+            self._transport.operations_client,
+            purge_config.PurgeDocumentsResponse,
+            metadata_type=purge_config.PurgeDocumentsMetadata,
+        )
+
+        # Done; return the response.
+        return response
+
     def __enter__(self) -> "DocumentServiceClient":
         return self
 

packages/google-cloud-discoveryengine/google/cloud/discoveryengine_v1beta/services/document_service/transports/base.py

@@ -27,7 +27,11 @@
 from google.protobuf import empty_pb2  # type: ignore
 
 from google.cloud.discoveryengine_v1beta import gapic_version as package_version
-from google.cloud.discoveryengine_v1beta.types import document_service, import_config
+from google.cloud.discoveryengine_v1beta.types import (
+    document_service,
+    import_config,
+    purge_config,
+)
 from google.cloud.discoveryengine_v1beta.types import document
 from google.cloud.discoveryengine_v1beta.types import document as gcd_document
 
@@ -165,6 +169,11 @@ def _prep_wrapped_messages(self, client_info):
                 default_timeout=300.0,
                 client_info=client_info,
             ),
+            self.purge_documents: gapic_v1.method.wrap_method(
+                self.purge_documents,
+                default_timeout=None,
+                client_info=client_info,
+            ),
         }
 
     def close(self):
@@ -238,6 +247,15 @@ def import_documents(
     ]:
         raise NotImplementedError()
 
+    @property
+    def purge_documents(
+        self,
+    ) -> Callable[
+        [purge_config.PurgeDocumentsRequest],
+        Union[operations_pb2.Operation, Awaitable[operations_pb2.Operation]],
+    ]:
+        raise NotImplementedError()
+
     @property
     def list_operations(
         self,