Esta página foi traduzida pela API Cloud Translation.

Como gerenciar 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) da API Cloud Healthcare.

Quando um método de API pode levar muito tempo para ser concluído, ele pode retornar um Operation ao cliente. O cliente pode usar a interface Operation para recuperar o status do método da API de forma assíncrona pesquisando a operação. As LROs na API Cloud Healthcare aderem ao 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 conferir 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, é possível conferir o status da LRO enviando uma solicitação contendo o ID da LRO para o conjunto de dados pai do armazenamento FHIR em que a importação está ocorrendo.

Além da API REST, as seguintes fontes 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 da API Cloud Healthcare no console do Google Cloud

Gerencie 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 um LRO

Os métodos a seguir retornam um LRO.

Métodos de gerenciamento de consentimento:

projects.locations.datasets.consentStores.queryAccessibleData

Métodos de conjunto de dados:

Métodos DICOM:

Métodos FHIR:

Métodos HL7v2:

Como acessar 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 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, você pode conferir 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 consultar.
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, quando gera o resultado:

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

Para conferir 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. Também é possível recuperar o nome da LRO listando LROs.

Para acessar 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 abaixo, 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

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 . É possível verificar a conta ativa atual executando gcloud auth list.

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 contém "done": true, a operação de longa duração foi 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 conferir uma lista de todas as LROs em um conjunto de dados 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 consultar.
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 abaixo, 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 consultar.
Clique em Operações.
Na mesma linha da LRO que você quer cancelar, abra a lista Ações e clique em Parar operação.

REST

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

Antes de usar os dados da solicitação abaixo, 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 conferir o status da solicitação de cancelamento, use o método projects.locations.datasets.operations.get.

Antes de usar os dados da solicitação abaixo, 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."
  }
}

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 em Python que pode ser usado para cancelar todas as operações de um determinado conjunto de dados.

Solução de problemas de LROs

Quando uma LRO falha, a resposta inclui um código de erro canônico do Google Cloud. A tabela a seguir explica a causa de cada código e recomenda como processar o código. 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 o erro de uma API não retornar informações suficientes, o erro pode ser convertido neste erro.	Tentar novamente com a 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 resolver 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 sucesso. Por exemplo, uma resposta bem-sucedida de um servidor pode ter atrasado tempo suficiente para que o prazo expirasse.	Tentar novamente com a espera exponencial.
5	`NOT_FOUND`	Alguma entidade solicitada, como um recurso FHIR, não foi encontrada.	Não tente novamente sem resolver o problema.
6	`ALREADY_EXISTS`	A entidade que um cliente tentou criar, como uma instância DICOM, já existe.	Não tente novamente sem resolver o problema.
7	`PERMISSION_DENIED`	O autor da chamada não tem permissão para executar a operação especificada. Esse código de erro não indica 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 resolver o problema.
8	`RESOURCE_EXHAUSTED`	Alguns recursos foram esgotados, como uma cota por projeto. Consulte as Práticas recomendadas para gerenciamento de cota e confira as ações recomendadas.	Tentar novamente com a espera exponencial. A cota pode ficar disponível com o 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 resolver 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.	Tentar novamente com a 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 resolver o problema.
12	`UNIMPLEMENTED`	A operação não foi implementada ou não é compatível/ativada na API Cloud Healthcare.	Não tente novamente.
13	`INTERNAL`	Erros internos. Isso indica que foi encontrado um erro inesperado no processamento do sistema de base.	Tentar novamente com a 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.	Tentar novamente com a 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 entrar em contato com um representante de suporte se ocorrer 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 resolver o problema.