Nesta página, descrevemos como gerenciar o ciclo de vida de uma API Cloud Healthcare uma operação de longa duração (LRO, na sigla em inglês).
Quando um método de API demora muito para ser concluído, ele pode retornar uma
Operation
ao cliente. O cliente pode usar a interface Operation
para recuperar a
status do método da API de forma assíncrona ao pesquisar 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, por exemplo, 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 API Cloud Healthcare no console do Google Cloud
Gerencie as LROs da API Cloud Healthcare usando o console do Google Cloud, a CLI do Google Cloud 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 gestão de consentimento:
Métodos de conjunto de dados:
Métodos DICOM:
projects.locations.datasets.dicomStores.deidentify
projects.locations.datasets.dicomStores.export
projects.locations.datasets.dicomStores.import
projects.locations.datasets.dicomStores.studies.delete
projects.locations.datasets.dicomStores.studies.series.delete
Métodos FHIR:
projects.locations.datasets.fhirStores.deidentify
projects.locations.datasets.fhirStores.export
projects.locations.datasets.fhirStores.import
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, é possível consultar os detalhes dela no console do Google Cloud.
No console do Google Cloud, acesse a página 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 seguintes informações:
- 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 as 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
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.
"done": true
, o
operação de longa duração foi concluída.
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, faça o seguinte: siga estas etapas:
No console do Google Cloud, acesse a página 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
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.
Você receberá uma resposta JSON semelhante a esta:
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.
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 Interromper operação.
REST
Para cancelar uma LRO, use o
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
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.
Você receberá uma resposta JSON semelhante a esta:
Para ver o status da solicitação de cancelamento, use o
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
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.
Você receberá uma resposta JSON semelhante a esta:
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 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 fornece uma explicação da causa de cada código e uma recomendação para como lidar com o código. Para muitos erros, a ação recomendada é tentar a solicitação novamente usando a espera exponencial. Para mais informações sobre como implementar 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 | Se quiser, execute a operação novamente. |
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 poderá ser convertido nesse 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. Confira as ações recomendadas em Práticas recomendadas para o gerenciamento de cotas. | 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 tem suporte/não está 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 está indisponí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 do suporte em caso de 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. |