Como gerenciar operações de longa duração

Nesta página, descrevemos como gerenciar o ciclo de vida de uma operação de longa duração (LRO, na sigla em inglês) da API Cloud Healthcare.

Quando um método de API pode levar muito tempo para ser concluído, ele pode retornar um Operation para o cliente. O cliente pode usar a interface Operation para recuperar o status do método de API de forma assíncrona pesquisando a operação. As LROs na API Cloud Healthcare seguem o padrão de design de LRO do Google Cloud.

A API Cloud Healthcare cria LROs para vários métodos, como projects.locations.datasets.fhirStores.import. Quando projects.locations.datasets.fhirStores.import é chamado, a API Cloud Healthcare cria uma LRO para rastrear o status da importação. A LRO tem um identificador exclusivo que pode ser usado para ver o status dela.

As LROs são gerenciadas no nível do conjunto de dados. Se você estiver chamando um método que retorna uma LRO, como projects.locations.datasets.fhirStores.import, poderá ver o status da LRO enviando uma solicitação contendo o ID da LRO para o conjunto de dados pai do repositório FHIR em que a importação está ocorrendo.

Além da API REST, as seguintes origens geram operações de longa duração quando você chama os métodos listados em Métodos que retornam uma LRO:

A Google Cloud CLI
A página API Cloud Healthcare no console do Google Cloud

É possível gerenciar as LROs da API Cloud Healthcare usando o console do Google Cloud, a Google Cloud CLI ou a API REST.

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

Métodos que retornam uma LRO

Os métodos a seguir retornam uma LRO.

Métodos de gerenciamento de consentimento:

projects.locations.datasets.consentStores.queryAccessibleData

Métodos do conjunto de dados:

Métodos DICOM:

Métodos FHIR:

Métodos de HL7v2:

Como ver detalhes sobre uma LRO

Os exemplos a seguir mostram como acessar os detalhes de uma LRO.

A versão da API Cloud Healthcare mostrada na resposta ao receber detalhes sobre uma LRO é a mesma que a versão da API do método que iniciou a LRO.

Console

Depois de chamar um método usando a CLI gcloud ou a API que retorna uma LRO, é possível ver os detalhes sobre a LRO no console do Google Cloud.

No console do Google Cloud, acesse a página Conjuntos de dados.

Acessar conjuntos de dados
Clique no nome do conjunto de dados que contém a LRO que você quer visualizar.
Clique em Operações.
Para ver os registros de erros da operação no Cloud Logging, clique em Ações e depois em Ver detalhes no Cloud Logging. Veja mais informações em Como visualizar registros de erros no Cloud Logging.
Para ver mais detalhes sobre a operação, clique em um ID de operação em execução. Será exibida a página Detalhes da operação de longa duração. A página mostra as seguintes informações:
- O progresso da LRO
- Os detalhes da LRO, como o ID da operação e o método que invocou a LRO
- Um subconjunto de entradas de registro

gcloud

Suponhamos que você receba a seguinte resposta após chamar gcloud healthcare dicom-stores deidentify:

Request issued for: [DATASET_ID]
Waiting for operation [OPERATION_ID] to complete...

A resposta mostra que a API Cloud Healthcare criou uma LRO com um código de operação. Também é possível recuperar o ID de operação listando operações de banco de dados de longa duração. O comando continua em execução até ser concluído. Depois disso, ele gera o seguinte:

Request issued for: [DATASET_ID]
Waiting for operation [OPERATION_ID] to complete...done
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID

Para ver detalhes sobre a LRO, execute o comando gcloud healthcare operations describe.

Antes de usar os dados do comando abaixo, faça estas substituições:

PROJECT_ID: o ID do seu projeto do Google Cloud;
DATASET_ID: o ID do conjunto de dados;
LOCATION: o local do conjunto de dados;
OPERATION_ID: o ID retornado da operação de longa duração.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud healthcare operations describe OPERATION_ID \
    --project=PROJECT_ID \
    --dataset=DATASET_ID \
    --location=LOCATION

Windows (PowerShell)

gcloud healthcare operations describe OPERATION_ID `
    --project=PROJECT_ID `
    --dataset=DATASET_ID `
    --location=LOCATION

Windows (cmd.exe)

gcloud healthcare operations describe OPERATION_ID ^
    --project=PROJECT_ID ^
    --dataset=DATASET_ID ^
    --location=LOCATION

Você receberá uma resposta semelhante a esta:

Resposta

done: true
// If there were any errors, an `error` field displays instead of a `response` field.
// See Troubleshooting long-running operations for a list of response codes.
error: ERROR
  code: ERROR_CODE
  message: DESCRIPTION
metadata:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata'
  apiMethodName: 'google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore'
  counter:
    success: 'SUCCESS_COUNT'
    // If there were any failures, they display in the `failure` field.
    failure: 'FAILURE_COUNT'
  createTime: 'YYYY-MM-DDTHH:MM:SS+ZZ:ZZ'
  endTime: 'YYYY-MM-DDTHH:MM:SS+ZZ:ZZ'
  logsUrl: https://console.cloud.google.com/CLOUD_LOGGING_URL
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID
// The `response` field only displays if there were no errors.
response:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary'

REST

Suponhamos que você receba a seguinte resposta após chamar projects.locations.datasets.dicomStores.deidentify:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

O valor name na resposta mostra que a API Cloud Healthcare criou uma LRO denominada projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID. Você também pode recuperar o nome da LRO listando as LROs.

Para ver o status da LRO, use o método projects.locations.datasets.operations.get. Para pesquisar uma LRO, chame repetidamente o método projects.locations.datasets.operations.get até que a operação seja concluída. Use um recuo entre cada solicitação de pesquisa. Por exemplo, pesquise a cada 10 segundos.

Antes de usar os dados da solicitação, faça as substituições a seguir:

PROJECT_ID: o ID do seu projeto do Google Cloud;
DATASET_ID: o ID do conjunto de dados;
LOCATION: o local do conjunto de dados;
OPERATION_ID: o ID retornado da operação de longa duração.

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

PowerShell

execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

APIs Explorer

Abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Preencha todos os campos obrigatórios e clique em Executar.

A saída é esta. Quando a resposta contiver "done": true, a operação de longa duração terá sido concluída.

Resposta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  // The `response` field only displays if there were no errors.
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary"
  },
  // If there were any errors, an `error` field displays instead of a `response` field.
  // See Troubleshooting long-running operations for a list of response codes.
  "error": {
    "code": ERROR_CODE,
    "message": "DESCRIPTION",
    "details": [
      {
        "@type": "...",
        FIELD1: ...,
        ...
      }
    ]
  }
}

Como listar LROs

Os exemplos a seguir mostram como listar as LROs em um conjunto de dados.

Console

Para ver uma lista de todas as LROs em um conjunto de dados no console do Google Cloud, conclua as seguintes etapas:

No console do Google Cloud, acesse a página Conjuntos de dados.

Acessar conjuntos de dados
Clique no nome do conjunto de dados que contém a LRO que você quer visualizar.
Clique em Operações.

Uma lista de LROs no conjunto de dados e seu status é exibida. Para ver os registros de erros no Cloud Logging, clique no ícone de mais informações na última coluna e em Ver detalhes no Cloud Logging. Para mais informações, consulte Como visualizar registros de erros no Cloud Logging.

gcloud

Para listar as LROs em um conjunto de dados, execute o comando gcloud healthcare operations list.

Antes de usar os dados do comando abaixo, faça estas substituições:

DATASET_ID: o ID do conjunto de dados;
LOCATION: o local do conjunto de dados;

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Windows (PowerShell)

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Windows (cmd.exe)

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Você receberá uma resposta semelhante a esta:

Resposta

ID             LOCATION     DONE
OPERATION_ID   LOCATION {TRUE|FALSE}
...

REST

Para listar as LROs em um conjunto de dados, use o método projects.locations.datasets.operations.get.

Antes de usar os dados da solicitação, faça as substituições a seguir:

PROJECT_ID: o ID do seu projeto do Google Cloud;
DATASET_ID: o ID do conjunto de dados;
LOCATION: o local do conjunto de dados;

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations"

PowerShell

execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations" | Select-Object -Expand Content

APIs Explorer

Você receberá uma resposta JSON semelhante a esta:

Resposta

{
  "operations": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
        "apiMethodName": "google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore",
        "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
        "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
        "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
        "counter": {
          "success": "SUCCESS_COUNT",
          // If there were any failures, they display in the `failure` field.
          "failure": "FAILURE_COUNT"
        }
      },
      "done": true,
      // The `response` field only displays if there were no errors.
      "response": {
        "@type": "type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary"
      },
      // If there were any errors, an `error` field displays instead of a `response` field.
      // See Troubleshooting long-running operations for a list of response codes.
      "error": {
        "code": ERROR_CODE,
        "message": "DESCRIPTION",
        "details": [
          {
            "@type": "...",
            FIELD1: ...,
            ...
          }
        ]
      }
    },
    ...
  ]
}

Como cancelar uma LRO

Os exemplos a seguir mostram como cancelar uma LRO em um conjunto de dados.

Console

Para cancelar uma LRO no console do Google Cloud, siga estas etapas:

No console do Google Cloud, acesse a página Conjuntos de dados.

Acessar conjuntos de dados
Clique no nome do conjunto de dados que contém a LRO que você quer visualizar.
Clique em Operações.
Na mesma linha da LRO que você quer cancelar, abra a lista Ações e clique em Interromper operação.

REST

Para cancelar uma LRO, use o método projects.locations.datasets.operations.cancel.

Antes de usar os dados da solicitação, faça as substituições a seguir:

PROJECT_ID: o ID do seu projeto do Google Cloud;
DATASET_ID: o ID do conjunto de dados;
LOCATION: o local do conjunto de dados;
OPERATION_ID: o ID retornado da operação de longa duração.

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d "" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID:cancel"

PowerShell

execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID:cancel" | Select-Object -Expand Content

APIs Explorer

Você receberá uma resposta JSON semelhante a esta:

Resposta

{}

Para ver o status da solicitação de cancelamento, use o método projects.locations.datasets.operations.get.

Antes de usar os dados da solicitação, faça as substituições a seguir:

PROJECT_ID: o ID do seu projeto do Google Cloud;
DATASET_ID: o ID do conjunto de dados;
LOCATION: o local do conjunto de dados;
OPERATION_ID: o ID retornado da operação de longa duração.

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

PowerShell

execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

APIs Explorer

Você receberá uma resposta JSON semelhante a esta:

Resposta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "API_METHOD_NAME",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "cancelRequested": true,
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  "error": {
    "code": 1,
    "message": "Operation cancelled by user. Any progress already completed by the operation will not be reverted."
  }
}

Como cancelar várias LROs

Para cancelar várias LROs, siga estas etapas:

Chame o método operations.list para receber os nomes das operações em um conjunto de dados.
Chame o método operations.cancel em cada operação.

O Google fornece um script Python que pode ser usado para cancelar todas as operações em um determinado conjunto de dados.

Como solucionar problemas de LROs

Quando uma LRO falha, a resposta dela inclui um código de erro canônico do Google Cloud. A tabela a seguir fornece uma explicação da causa de cada código e uma recomendação sobre como lidar com eles. Para muitos erros, a ação recomendada é tentar a solicitação novamente usando a espera exponencial. Para informações sobre como implementar a espera exponencial na API Cloud Healthcare, consulte Repetir solicitações com falha.

Código	Enum	Descrição	Ação recomendada
1	`CANCELLED`	A operação foi cancelada, geralmente pelo chamador	Execute a operação novamente, se quiser.
2	`UNKNOWN`	Este erro pode ser retornado quando um valor `Status` recebido de outro espaço de endereço pertence a um espaço de erro desconhecido nesse espaço de endereço. Se um erro de API não retornar informações suficientes, ele poderá ser convertido neste erro.	Tente de novo com espera exponencial.
3	`INVALID_ARGUMENT`	O cliente especificou um argumento inválido. Esse erro é diferente de `FAILED_PRECONDITION`. `INVALID_ARGUMENT` indica argumentos problemáticos, independentemente do estado do sistema, como um nome de arquivo incorreto.	Não tente novamente sem corrigir o problema.
4	`DEADLINE_EXCEEDED`	O prazo expirou antes do término da operação. Para operações que alteram o estado do sistema, esse erro pode ser retornado mesmo que a operação tenha sido concluída com êxito. Por exemplo, uma resposta bem-sucedida de um servidor pode ter atrasado tempo suficiente para que o prazo expirasse.	Tente de novo com espera exponencial.
5	`NOT_FOUND`	Algumas entidades solicitadas, como um recurso FHIR, não foram encontradas.	Não tente novamente sem corrigir o problema.
6	`ALREADY_EXISTS`	A entidade que um cliente tentou criar, como uma instância DICOM, já existe.	Não tente novamente sem corrigir o problema.
7	`PERMISSION_DENIED`	O autor da chamada não tem permissão para executar a operação especificada. Esse código do erro não implica que a solicitação seja válida nem que a entidade solicitada exista ou satisfaça outras condições prévias.	Não tente novamente sem corrigir o problema.
8	`RESOURCE_EXHAUSTED`	Alguns recursos foram esgotados, como uma cota por projeto. Consulte as ações recomendadas em Práticas recomendadas para o gerenciamento de cotas.	Tente de novo com espera exponencial. A cota pode ficar disponível ao longo do tempo.
9	`FAILED_PRECONDITION`	A operação foi rejeitada porque o estado do sistema não é o necessário para a execução dela. Por exemplo, o diretório a ser excluído não está vazio ou uma operação `rmdir` foi aplicada a um elemento que não é um diretório.	Não tente novamente sem corrigir o problema.
10	`ABORTED`	A operação foi cancelada, normalmente devido a um problema de simultaneidade, como falha na verificação do sequenciador ou cancelamento da transação.	Tente de novo com espera exponencial.
11	`OUT_OF_RANGE`	Houve uma tentativa da operação depois do intervalo válido, como a busca ou a leitura após o fim do arquivo. Diferentemente de `INVALID_ARGUMENT`, este erro indica um problema que poderá ser corrigido se o estado do sistema mudar.	Não tente novamente sem corrigir o problema.
12	`UNIMPLEMENTED`	A operação não foi implementada ou não tem suporte nem está ativada na API Cloud Healthcare.	Não tente de novo.
13	`INTERNAL`	Erros internos. Isso indica que foi encontrado um erro inesperado no processamento do sistema de base.	Tente de novo com espera exponencial.
14	`UNAVAILABLE`	A API Cloud Healthcare não está disponível no momento. Muito provavelmente, trata-se de uma condição temporária, que pode ser corrigida ao tentar novamente com uma retirada. Nem sempre é seguro repetir operações não idempotentes.	Tente de novo com espera exponencial.
15	`DATA_LOSS`	Perda ou corrupção irrecuperável de dados.	Entre em contato com seu administrador de sistemas. O administrador do sistema pode querer entrar em contato com um representante de suporte se ocorrer uma perda ou corrupção de dados.
16	`UNAUTHENTICATED`	A solicitação não tem credenciais válidas de autenticação para a operação.	Não tente novamente sem corrigir o problema.