Monitorar operações de longa duração

Esta página descreve como gerenciar o ciclo de vida de uma operação de longa duração (LRO, na sigla em inglês) em aplicativos de IA.

Um objeto de operação de longa duração é retornado quando uma chamada para um método pode levar muito tempo para ser concluída. Por exemplo, a API AI Applications cria uma operação de longa duração quando você chama documents.import pela API ou pelas bibliotecas de cliente. A operação rastreia o status do job de processamento.

É possível usar os métodos de operações de longa duração que a API AI Applications oferece para verificar o status das operações. Também é possível listar ou consultar operações.

O registro de uma operação é mantido por aproximadamente 30 dias após a conclusão da operação. Isso significa que não é possível visualizar ou listar uma operação após esse período.

Listar operações de longa duração

Confira a seguir como listar as operações de um recurso Google Cloud.

REST

Para listar as operações de longa duração de um recurso Google Cloud , siga estas etapas:

  • Chame o método operations.list :

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/operations"

    DATA_STORE_ID: o ID do repositório de dados da AI Applications que foi criado com o mecanismo. No URL do console Google Cloud , o ID do repositório de dados aparece depois de engines/ e antes de /data.

Python

Para mais informações, consulte a documentação de referência da API AI Applications Python.

Para autenticar nos aplicativos de IA, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from typing import Optional

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_PROCESSOR_LOCATION"  # Options: "global"
# search_engine_id = "YOUR_SEARCH_ENGINE_ID"

# Create filter in https://google.aip.dev/160 syntax
# operations_filter = "YOUR_FILTER"


def list_operations_sample(
    project_id: str,
    location: str,
    search_engine_id: str,
    operations_filter: Optional[str] = None,
) -> operations_pb2.ListOperationsResponse:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # The full resource name of the search engine branch.
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/dataStores/{search_engine_id}"

    # Make ListOperations request
    request = operations_pb2.ListOperationsRequest(
        name=name,
        filter=operations_filter,
    )

    # Make ListOperations request
    response = client.list_operations(request=request)

    # Print the Operation Information
    for operation in response.operations:
        print(operation)

    return response

Acessar detalhes sobre uma operação de longa duração

Confira a seguir como receber detalhes sobre uma operação.

REST

Para conferir o status e os detalhes de uma operação de longa duração, siga estas etapas:

  1. Encontre o nome da operação de duas maneiras:

    • Depois de fazer uma chamada para um método que retorna uma operação de longa duração, analise a resposta.

      Por exemplo, se você chamar documents.import, o início da resposta será parecido com este:

      {
  "operations": [
    {
      "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.ImportDocumentsMetadata",
      }
    }
  ]
}

      O valor name na resposta fornece o nome da operação, que pode ser usado para consultar o status dela. Não inclua aspas ao copiar o nome da operação.

    • Confira o nome da operação listando operações de longa duração.

  2. Chame o método operations.get no recurso que criou a operação:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1/OPERATION_NAME"

    OPERATION_NAME: informe o nome da operação para a qual você precisa de informações. Para encontrar o nome da operação, listar operações de longa duração.

    As primeiras linhas da resposta do comando GET são parecidas com esta:

    {
      "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.ImportDocumentsMetadata"
      }
    }

Python

Para mais informações, consulte a documentação de referência da API AI Applications Python.

Para autenticar nos aplicativos de IA, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def get_operation_sample(operation_name: str) -> operations_pb2.Operation:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make GetOperation request
    request = operations_pb2.GetOperationRequest(name=operation_name)
    operation = client.get_operation(request=request)

    # Print the Operation Information
    print(operation)

    return operation

Pesquisar uma operação de longa duração

Confira a seguir como consultar o status de uma operação.

REST

Para consultar a operação de longa duração até que ela seja concluída, siga estas etapas:

  1. Execute o comando abaixo, que chama o método operations.get repetidamente, usando um recuo de 10 segundos entre cada solicitação:

    while true; \
    do curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1/OPERATION_NAME"; \
    sleep 10; \
    done

    OPERATION_NAME: fornece o nome da operação que você quer sondar. Para encontrar o nome da operação, listar operações de longa duração. Por exemplo, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

  2. Interrompa o job de pesquisa (Control+Z) depois que o status mostrar "done": true.

Python

Para mais informações, consulte a documentação de referência da API AI Applications Python.

Para autenticar nos aplicativos de IA, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from time import sleep

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def poll_operation_sample(
    operation_name: str, limit: int = 10
) -> operations_pb2.Operation:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make GetOperation request
    request = operations_pb2.GetOperationRequest(name=operation_name)

    for _ in range(limit):
        operation = client.get_operation(request=request)
        # Print the Operation Information
        print(operation)

        # Stop polling when Operation is no longer running
        if operation.done:
            break

        # Wait 10 seconds before polling again
        sleep(10)

    return operation

Cancelar uma operação de longa duração

Confira a seguir como cancelar uma operação:

REST

Para cancelar uma operação de longa duração, siga estas etapas:

  • Chame o método operations.cancel :

    curl -X post \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://discoveryengine.googleapis.com/v1/OPERATION_NAME":cancel

    OPERATION_NAME: informe o nome da operação que você quer cancelar. Para encontrar o nome da operação, listar operações de longa duração. Por exemplo, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

    Depois que a chamada de API é feita, o servidor tenta cancelar a operação. Os resultados e as ações que você pode realizar são os seguintes:

    • Um erro com "code": 400 e "status": "FAILED_PRECONDITION" indica que a solicitação não foi cancelada.

    • Um cancelamento bem-sucedido resulta em um objeto JSON vazio. Para verificar o cancelamento:

      • Use o método operations.get.

      • Se a operação for cancelada, a resposta do método operations.get terá o erro "code": 1, que representa o código de status CANCELLED.

        Exemplo:

        {
  "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.ImportDocumentsMetadata",
    "createTime": "2025-04-28T21:29:21.199190Z",
    "updateTime": "2025-04-28T21:31:29.076865Z"
  },
  "done": true,
  "error": {
    "code": 1,
    "message": "Operation projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789 is cancelled."
  }
}

Python

Para mais informações, consulte a documentação de referência da API AI Applications Python.

Para autenticar nos aplicativos de IA, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def cancel_operation_sample(operation_name: str) -> None:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make CancelOperation request
    request = operations_pb2.CancelOperationRequest(name=operation_name)
    client.cancel_operation(request=request)

    return