Monitorize operações de longa duração

Esta página descreve como gerir o ciclo de vida de uma operação de longa duração (LRO) em aplicações de IA.

É devolvido um objeto de operação de longa duração quando uma chamada a um método pode demorar muito tempo a ser concluída. Por exemplo, a API AI Applications cria uma operação de longa duração quando chama documents.import através da API ou das bibliotecas cliente. A operação acompanha o estado da tarefa de processamento.

Pode usar os métodos de operações de execução longa fornecidos pela API AI Applications para verificar o estado das operações. Também pode listar ou sondar operações.

O registo de uma operação é mantido durante aproximadamente 30 dias após a conclusão da operação, o que significa que não pode ver nem listar uma operação após esse período.

Apresente operações de longa duração

O exemplo seguinte mostra como listar as operações de um recurso Google Cloud.

REST

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

  • 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 das Aplicações de IA que foi criado com o seu motor. No Google Cloud URL da consola, o ID da loja de dados aparece depois de engines/ e antes de /data.

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

Veja detalhes acerca de uma operação de longa duração

O exemplo seguinte mostra como obter detalhes sobre uma operação.

REST

Para obter o estado e ver detalhes acerca de uma operação de longa duração, siga estes passos:

  1. Encontre o nome da operação de uma das seguintes formas:

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

      Por exemplo, se chamar documents.import, o início da resposta tem um aspeto semelhante a 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 estado da operação. Não inclua as aspas quando copiar o nome da operação.

    • Obtenha o nome da operação listando as 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: indique o nome da operação para a qual precisa de informações. Pode encontrar o nome da operação ao listar operações de longa duração.

    As primeiras linhas da resposta do comando GET têm um aspeto semelhante a 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.v1.ImportDocumentsMetadata"
      }
    }

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

O exemplo seguinte mostra como verificar o estado de uma operação.

REST

Para sondar a operação de longa duração até terminar, siga estes passos:

  1. Execute o seguinte comando, que chama o método operations.get repetidamente, usando uma retirada de 10 segundos entre cada pedido:

    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: indique o nome da operação que quer consultar. Pode encontrar o nome da operação ao 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. Pare a tarefa de sondagem (Control+Z) depois de o estado apresentar "done": true.

Python

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

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

O exemplo seguinte mostra como cancelar uma operação:

REST

Para cancelar uma operação de longa duração, siga estes passos:

  • 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: indique o nome da operação que quer cancelar. Pode encontrar o nome da operação ao 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.

    Após a chamada da API, o servidor tenta cancelar a operação. Os resultados que vê e as ações que pode realizar são os seguintes:

    • Um erro com "code": 400 e "status": "FAILED_PRECONDITION" indica que não foi possível cancelar o pedido.

    • Um cancelamento bem-sucedido resulta num objeto JSON vazio. Para validar o cancelamento:

      • Use o método operations.get.

      • Se a operação for cancelada com êxito, a resposta do método operations.get tem o erro "code": 1, que representa o código de estado CANCELLED.

        Por 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 Python de aplicações de IA.

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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