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) no Vertex AI Agent Builder.

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 Vertex AI Agent Builder 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 Vertex AI Agent Builder 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.

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:

      {
  "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.v1beta.ImportDocumentsMetadata"
  }
}

      O valor name na resposta fornece o nome da operação, que pode ser usado para consultar o status da operação. 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/v1beta/OPERATION_NAME"

    OPERATION_NAME: o nome da operação da etapa anterior.

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

    {
  "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.v1alpha.ImportDocumentsMetadata",
      }
    }
  ]
}

Python

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

Para autenticar no Vertex AI Agent Builder, 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

Listar operações de longa duração

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

REST

Para listar as operações de longa duração de um recurso do Google Cloud, siga esta etapa:

  • Chame o método operations.list :

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

    DATA_STORE_ID: o ID do repositório de dados do Vertex AI Agent Builder que foi criado com seu mecanismo. No URL do console do Google Cloud, o ID do repositório de dados aparece após engines/ e antes de /data.

Python

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

Para autenticar no Vertex AI Agent Builder, 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

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/v1beta/OPERATION_NAME"; \
    sleep 10; \
    done

    OPERATION_NAME: o nome da operação, encontrado em Conferir detalhes sobre uma operação de longa duração. Por exemplo: projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789

  2. Pare 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 Python do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, 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