Esta página foi traduzida pela API Cloud Translation.

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

Quando um método da API pode demorar muito tempo a ser concluído, pode devolver um Operation ao cliente. O cliente pode usar a interface Operation para obter o estado do método da API de forma assíncrona através da sondagem da operação. As LROs na API Cloud Healthcare seguem o Google Cloud padrão de design de LROs.

A Cloud Healthcare API 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 um LRO para acompanhar o estado da importação. O LRO tem um identificador exclusivo que pode usar para ver o estado do LRO.

As LROs são geridas ao nível do conjunto de dados. Se estiver a chamar um método que devolve um LRO, como projects.locations.datasets.fhirStores.import, pode ver o estado do LRO enviando um pedido que contenha o ID do LRO para o conjunto de dados principal da FHIR store onde a importação está a ocorrer.

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

A CLI do Google Cloud
A página da API Cloud Healthcare na Google Cloud consola

Pode gerir as LROs da Cloud Healthcare API através da Google Cloud consola, da Google Cloud CLI ou da API REST.

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

Métodos que devolvem um LRO

Os seguintes métodos devolvem um LRO.

Métodos de gestão de consentimento:

projects.locations.datasets.consentStores.queryAccessibleData

Métodos do conjunto de dados:

Métodos DICOM:

Métodos FHIR:

Métodos HL7v2:

Obter detalhes sobre uma LRO

Os exemplos seguintes mostram como obter detalhes sobre um LRO.

A versão da API Cloud Healthcare apresentada na resposta quando obtém detalhes sobre um LRO é a mesma que a versão da API do método que iniciou o LRO.

Consola

Depois de chamar um método através da CLI gcloud ou da API que devolve um LRO, pode ver detalhes sobre o LRO na Google Cloud consola.

Na Google Cloud consola, aceda à página Conjuntos de dados.

Aceda aos conjuntos de dados
Clique no nome do conjunto de dados que contém a LRO que quer ver.
Clique em Operações.
Para ver os registos de erros da operação no Cloud Logging, clique em Ações e, de seguida, em Ver detalhes no Cloud Logging. Para mais informações, consulte o artigo Ver registos de erros no Cloud Logging.
Para ver mais detalhes sobre a operação, clique num ID de operação em execução. É apresentada a página Detalhes da operação de longa duração. A página mostra as seguintes informações:
- O progresso do LRO
- Os detalhes da LRO, como o ID da operação e o método que invocou a LRO
- Um subconjunto de entradas do registo

gcloud

Suponha que recebe a seguinte resposta depois de ligar para gcloud healthcare dicom-stores deidentify:

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

A resposta mostra que a Cloud Healthcare API criou uma LRO com um ID de operação. Também pode obter o ID da operação listando as operações de base de dados de longa duração. O comando continua a ser executado até terminar, após o qual produz o seguinte resultado:

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

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

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

PROJECT_ID: o ID do seu Google Cloud projeto
DATASET_ID: o ID do conjunto de dados
LOCATION: a localização do conjunto de dados
OPERATION_ID: o ID devolvido pela 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

Deve receber uma resposta semelhante à seguinte:

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

Suponha que recebe a seguinte resposta depois de ligar para 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 Cloud Healthcare API criou uma LRO denominada projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID. Também pode obter o nome da LRO listando as LROs.

Para obter o estado da LRO, use o método projects.locations.datasets.operations.get. Para sondar uma LRO, chame repetidamente o método projects.locations.datasets.operations.get até a operação terminar. Use um intervalo de tempo entre cada pedido de sondagem, como 10 segundos.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

PROJECT_ID: o ID do seu Google Cloud projeto
DATASET_ID: o ID do conjunto de dados
LOCATION: a localização do conjunto de dados
OPERATION_ID: o ID devolvido pela operação de longa duração

Para enviar o seu pedido, escolha uma destas opções:

curl

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando 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

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando 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

Explorador de APIs

Abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Preencha todos os campos obrigatórios e clique em Executar.

O resultado é o seguinte. Quando a resposta contém "done": true, a operação de longa duração terminou.

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: ...,
        ...
      }
    ]
  }
}

LROs de fichas

Os exemplos seguintes mostram como listar as LROs num conjunto de dados.

Consola

Para ver uma lista de todas as LROs num conjunto de dados na Google Cloud consola, conclua os seguintes passos:

Na Google Cloud consola, aceda à página Conjuntos de dados.

Aceda aos conjuntos de dados
Clique no nome do conjunto de dados que contém a LRO que quer ver.
Clique em Operações.

É apresentada uma lista de LROs no conjunto de dados e o respetivo estado. Para ver os registos de erros no Cloud Logging, clique no ícone de mais informações na última coluna e, de seguida, clique em Ver detalhes no Cloud Logging. Para mais informações, consulte o artigo Ver registos de erros nos Registos na nuvem.

gcloud

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

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

DATASET_ID: o ID do conjunto de dados
LOCATION: a localização 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

Deve receber uma resposta semelhante à seguinte:

Resposta

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

REST

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

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

PROJECT_ID: o ID do seu Google Cloud projeto
DATASET_ID: o ID do conjunto de dados
LOCATION: a localização do conjunto de dados

Para enviar o seu pedido, 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

Explorador de APIs

Deve receber uma resposta JSON semelhante à seguinte:

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: ...,
            ...
          }
        ]
      }
    },
    ...
  ]
}

Cancelar um LRO

Os exemplos seguintes mostram como cancelar uma LRO num conjunto de dados.

Consola

Para cancelar uma LRO na Google Cloud consola, conclua os seguintes passos:

Na Google Cloud consola, aceda à página Conjuntos de dados.

Aceda aos conjuntos de dados
Clique no nome do conjunto de dados que contém a LRO que quer ver.
Clique em Operações.
Na mesma linha que a LRO que 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 qualquer um dos dados do pedido, faça as seguintes substituições:

PROJECT_ID: o ID do seu Google Cloud projeto
DATASET_ID: o ID do conjunto de dados
LOCATION: a localização do conjunto de dados
OPERATION_ID: o ID devolvido pela operação de longa duração

Para enviar o seu pedido, 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

Explorador de APIs

Deve receber uma resposta JSON semelhante à seguinte:

Resposta

{}

Para ver o estado do pedido de cancelamento, use o método projects.locations.datasets.operations.get.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

PROJECT_ID: o ID do seu Google Cloud projeto
DATASET_ID: o ID do conjunto de dados
LOCATION: a localização do conjunto de dados
OPERATION_ID: o ID devolvido pela operação de longa duração

Para enviar o seu pedido, 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

Explorador de APIs

Deve receber uma resposta JSON semelhante à seguinte:

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, conclua os seguintes passos:

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

A Google fornece um script Python que pode usar para cancelar todas as operações de um determinado conjunto de dados.

Resolução de problemas de LROs

Quando uma LRO falha, a respetiva resposta inclui um código de erro Google Cloud canónico. A tabela seguinte explica a causa de cada código e apresenta uma recomendação para como processar o código. Para muitos erros, a ação recomendada é tentar o pedido novamente usando a retirada exponencial. Para obter informações sobre como implementar o recuo exponencial na Cloud Healthcare API, consulte o artigo Tentar novamente pedidos com falhas.

Código	Enum	Descrição	Ação recomendada
1	`CANCELLED`	A operação foi cancelada, normalmente, pelo autor da chamada.	Se quiser, volte a executar a operação.
2	`UNKNOWN`	Este erro pode ser devolvido quando um valor `Status` recebido de outro espaço de endereço pertence a um espaço de erro que não é conhecido neste espaço de endereço. Se o erro de uma API não devolver informações suficientes, o erro pode ser convertido neste erro.	Tente novamente com retirada exponencial.
3	`INVALID_ARGUMENT`	O cliente especificou um argumento inválido. Este erro é diferente de `FAILED_PRECONDITION`. `INVALID_ARGUMENT` indica argumentos problemáticos independentemente do estado do sistema, como um nome de ficheiro com formato incorreto.	Não tente novamente sem corrigir o problema.
4	`DEADLINE_EXCEEDED`	O prazo expirou antes de a operação poder ser concluída. Para operações que alteram o estado do sistema, este erro pode ser devolvido mesmo que a operação tenha sido concluída com êxito. Por exemplo, uma resposta bem-sucedida de um servidor pode ter sofrido um atraso suficiente para que o prazo expire.	Tente novamente com retirada exponencial.
5	`NOT_FOUND`	Não foi possível encontrar alguma entidade solicitada, como um recurso FHIR.	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 autorização para executar a operação especificada. Este código de erro não implica que o pedido seja válido ou que a entidade pedida exista ou satisfaça outras pré-condições.	Não tente novamente sem corrigir o problema.
8	`RESOURCE_EXHAUSTED`	Algum recurso foi esgotado, como uma quota por projeto. Consulte as práticas recomendadas para a gestão de quotas para ver as ações recomendadas.	Tente novamente com retirada exponencial. A quota pode ficar disponível ao longo do tempo.
9	`FAILED_PRECONDITION`	A operação foi rejeitada porque o sistema não se encontra num estado necessário para a execução da operação. Por exemplo, o diretório a eliminar não está vazio ou uma operação `rmdir` é aplicada a um não diretório.	Não tente novamente sem corrigir o problema.
10	`ABORTED`	A operação foi interrompida, normalmente devido a um problema de simultaneidade, como uma falha na verificação do sequenciador ou uma interrupção da transação.	Tente novamente com retirada exponencial.
11	`OUT_OF_RANGE`	A operação foi tentada fora do intervalo válido, como procurar ou ler após o fim do ficheiro. Ao contrário de `INVALID_ARGUMENT`, este erro indica um problema que pode ser corrigido se o estado do sistema for alterado.	Não tente novamente sem corrigir o problema.
12	`UNIMPLEMENTED`	A operação não está implementada ou não é suportada/ativada na Cloud Healthcare API.	Não repetir.
13	`INTERNAL`	Erros internos. Isto indica que ocorreu um erro inesperado no processamento do sistema subjacente.	Tente novamente com retirada exponencial.
14	`UNAVAILABLE`	A Cloud Healthcare API está atualmente indisponível. Esta é provavelmente uma condição temporária que pode ser corrigida ao tentar novamente com uma recusa. Tenha em atenção que nem sempre é seguro repetir operações não idempotentes.	Tente novamente com retirada exponencial.
15	`DATA_LOSS`	Perda de dados irrecuperável ou corrupção de dados.	Contacte o administrador do sistema. O administrador do sistema pode querer contactar um representante do apoio técnico se tiver ocorrido perda ou corrupção de dados.
16	`UNAUTHENTICATED`	O pedido não tem credenciais de autenticação válidas para a operação.	Não tente novamente sem corrigir o problema.

Gerir operações de longa duração Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Métodos que devolvem um LRO

Obter detalhes sobre uma LRO

Consola

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Resposta

REST

curl

PowerShell

Explorador de APIs

Resposta

LROs de fichas

Consola

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Resposta

REST

curl

PowerShell

Explorador de APIs

Resposta

Cancelar um LRO

Consola

REST

curl

PowerShell

Explorador de APIs

Resposta

curl

PowerShell

Explorador de APIs

Resposta

Cancelar várias LROs

Resolução de problemas de LROs

Gerir operações de longa duração