Administrar operaciones de larga duración

En esta página, se describe cómo administrar el ciclo de vida de una API de Cloud Healthcare de larga duración (LRO).

Cuando un método de API puede tardar mucho tiempo en completarse, puede mostrar un Operation al cliente. El cliente puede usar la interfaz Operation para recuperar el el estado del método de la API de forma asíncrona sondeando la operación. Los LRO de la API de Cloud Healthcare se adhieren al patrón de diseño de LRO de Google Cloud.

La API de Cloud Healthcare crea LRO para varias métodos, como projects.locations.datasets.fhirStores.import. Cuando se llama a projects.locations.datasets.fhirStores.import, el elemento La API de Cloud Healthcare crea una LRO para hacer un seguimiento del estado de la importación. La LRO tiene un identificador único que puedes usar para ver el estado de la LRO.

Las LRO se administran a nivel del conjunto de datos. Si llamas a un que muestre una LRO, como projects.locations.datasets.fhirStores.import, Puedes ver el estado de la LRO enviando una solicitud con el ID de LRO al conjunto de datos principal del almacén de FHIR en el que se realiza la importación.

Además de la API de REST, las siguientes fuentes generan operaciones cuando llamas a los métodos enumerados en Métodos que muestran una LRO:

Puedes administrar los LRO de tu API de Cloud Healthcare mediante la consola de Google Cloud, Google Cloud CLI o la API de REST.

El registro de una LRO se conserva aproximadamente 30 días después de que esta finaliza, lo que significa que no puedes ver ni enumerar una LRO después de ese punto.

Métodos que muestran una LRO

Los siguientes métodos muestran una LRO.

Métodos de administración de consentimientos:

Métodos del conjunto de datos:

Métodos de DICOM:

Métodos de FHIR:

Métodos HL7v2:

Obtén detalles sobre una LRO

En los siguientes ejemplos, se muestra cómo obtener detalles sobre una LRO.

La versión de la API de Cloud Healthcare que se muestra en la respuesta cuando se obtienen detalles sobre una LRO es lo mismo que la API del método que inició la LRO.

Console

Después de llamar a un método mediante la CLI de gcloud o la API que muestra un LRO, puedes ver los detalles sobre el LRO en la consola de Google Cloud.

  1. En la consola de Google Cloud, ve a la página Conjuntos de datos.

    Ir a Conjuntos de datos

  2. Haz clic en el nombre del conjunto de datos que contiene la LRO que deseas ver.

  3. Haz clic en Operaciones.

  4. Para ver los registros de errores de la operación en Cloud Logging, haz clic en Acciones y, luego, en Ver detalles en Cloud Logging. Para obtener más información, consulta Visualiza los registros de errores en Cloud Logging.

  5. Para ver más detalles sobre la operación, haz clic en un ID de operación en ejecución. Se muestra la página Detalles de la operación de larga duración. La página muestra la siguiente información:

    • El progreso de la LRO
    • Los detalles de la LRO, como el ID de operación y el método que invocó la LRO
    • Un subconjunto de entradas de registro

gcloud

Supongamos que recibes la siguiente respuesta después de llamar a gcloud healthcare dicom-stores deidentify:

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

La respuesta muestra que la API de Cloud Healthcare creó una LRO con un ID de operación. También puedes recuperar el ID de la operación si enumeras las operaciones de larga duración de la base de datos. Se seguirá ejecutando el comando hasta que finalice, en el momento en el que se muestre el siguiente resultado:

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

Para obtener detalles sobre la LRO, ejecuta gcloud healthcare operations describe. .

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • PROJECT_IDEl ID de tu proyecto de Google Cloud.
  • DATASET_ID: El ID del conjunto de datos
  • LOCATION: La ubicación del conjunto de datos
  • OPERATION_ID: Es el ID que muestra la operación de larga duración.

Ejecuta el siguiente comando:

Linux, macOS o 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

Deberías recibir una respuesta similar a la que figura a continuación:

Respuesta

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

Supongamos que recibes la siguiente respuesta después de llamar a projects.locations.datasets.dicomStores.deidentify:

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

El valor name en la respuesta muestra que la API de Cloud Healthcare creó una LRO llamada projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID. También puedes recuperar el nombre de la LRO si enumeras las LRO.

Para obtener el estado de la LRO, usa el método projects.locations.datasets.operations.get. Para sondear una LRO, llama de forma reiterada al método projects.locations.datasets.operations.get hasta que finalice la operación. Usa una retirada entre cada solicitud de sondeo, por ejemplo, 10 segundos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_IDEl ID de tu proyecto de Google Cloud.
  • DATASET_ID: El ID del conjunto de datos
  • LOCATION: La ubicación del conjunto de datos
  • OPERATION_ID: Es el ID que muestra la operación de larga duración.

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente 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

Ejecuta el siguiente 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 API

Abre el página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

Este es el resultado. Cuando la respuesta contiene "done": true, significa que la operación de larga duración finalizó.

Genera una lista de LRO

En los siguientes ejemplos, se muestra cómo enumerar las LRO en un conjunto de datos.

Console

Para ver una lista de todas las LRO de un conjunto de datos en la consola de Google Cloud, sigue estos pasos: completa los siguientes pasos:

  1. En la consola de Google Cloud, ve a la página Conjuntos de datos.

    Ir a Conjuntos de datos

  2. Haz clic en el nombre del conjunto de datos que contiene la LRO que deseas ver.

  3. Haz clic en Operaciones.

Se mostrará una lista de LRO en el conjunto de datos y su estado. Para ver los registros de errores en Cloud Logging, haz clic en el ícono de más información en la última columna y, luego, haz clic en Ver detalles en Cloud Logging. Para obtener más información, consulta Visualiza los registros de errores en Cloud Logging.

gcloud

Para enumerar las LRO de un conjunto de datos, ejecuta el comando gcloud healthcare operations list.

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • DATASET_ID: El ID del conjunto de datos
  • LOCATION: La ubicación del conjunto de datos

Ejecuta el siguiente comando:

Linux, macOS o 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

Deberías recibir una respuesta similar a la que figura a continuación:

Respuesta

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

REST

Para enumerar las LRO en un conjunto de datos, usa el projects.locations.datasets.operations.get .

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_IDEl ID de tu proyecto de Google Cloud.
  • DATASET_ID: El ID del conjunto de datos
  • LOCATION: La ubicación del conjunto de datos

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente 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

Ejecuta el siguiente 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 API

Abre el página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

Cancela una LRO

En los siguientes ejemplos, se muestra cómo cancelar una LRO en un conjunto de datos.

Console

Para cancelar una LRO en la consola de Google Cloud, completa los siguientes pasos:

  1. En la consola de Google Cloud, ve a la página Conjuntos de datos.

    Ir a Conjuntos de datos

  2. Haz clic en el nombre del conjunto de datos que contiene la LRO que deseas ver.

  3. Haz clic en Operaciones.

  4. En la misma fila de la LRO que deseas cancelar, abre la lista de Acciones y haz clic en Detener operación.

REST

Para cancelar una LRO, usa projects.locations.datasets.operations.cancel .

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_IDEl ID de tu proyecto de Google Cloud.
  • DATASET_ID: El ID del conjunto de datos
  • LOCATION: La ubicación del conjunto de datos
  • OPERATION_ID: Es el ID que muestra la operación de larga duración.

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente 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

Ejecuta el siguiente 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 API

Abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

Para ver el estado de la solicitud de cancelación, usa la projects.locations.datasets.operations.get .

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_IDEl ID de tu proyecto de Google Cloud.
  • DATASET_ID: El ID del conjunto de datos
  • LOCATION: La ubicación del conjunto de datos
  • OPERATION_ID: Es el ID que muestra la operación de larga duración.

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente 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

Ejecuta el siguiente 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 API

Abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

Cancela varias LRO

Para cancelar varias LRO, completa los siguientes pasos:

  1. Llama al método operations.list para obtener los nombres de las operaciones en un conjunto de datos.
  2. Llama al método operations.cancel en cada operación.

Google proporciona una secuencia de comandos de Python que puedes usar para cancelar todas las operaciones en un conjunto de datos determinado.

Soluciona problemas de LRO

Cuando falla una LRO, su respuesta incluye un código de error canónico de Google Cloud. La siguiente tabla proporciona una explicación de la causa de cada código y una recomendación para cómo manejar el código. Si hay muchos errores, la acción recomendada es probar la de nuevo con una retirada exponencial. Para obtener información sobre cómo implementar retirada exponencial en la API de Cloud Healthcare, consulta Reintentar solicitudes fallidas.

Código Enum Descripción Acción recomendada
1 CANCELLED La operación se canceló (por lo general, la cancela el emisor). Vuelve a ejecutar la operación si lo deseas.
2 UNKNOWN Este error puede mostrarse cuando un valor Status recibido de otro espacio de direcciones pertenece a un espacio de error desconocido en este espacio de direcciones. Si el error de una API no muestra suficiente información, se puede convertir en este error. Vuelve a intentarlo con una retirada exponencial.
3 INVALID_ARGUMENT El cliente especificó un argumento no válido. Este error difiere de FAILED_PRECONDITION. INVALID_ARGUMENT indica los argumentos que son problemáticos sin importar el estado del sistema, como un nombre de archivo con formato incorrecto. No vuelvas a intentarlo sin solucionar el problema.
4 DEADLINE_EXCEEDED El plazo venció antes de que la operación se pudiera completar. En el caso de las operaciones que cambian el estado del sistema, es posible que se muestre este error incluso si la operación se completó correctamente. Por ejemplo, una respuesta correcta desde un servidor podría haberse retrasado lo suficiente como para que el plazo venciera. Vuelve a intentarlo con una retirada exponencial.
5 NOT_FOUND No se encontró alguna entidad solicitada, como un recurso de FHIR. No vuelvas a intentarlo sin solucionar el problema.
6 ALREADY_EXISTS La entidad que un cliente intentó crear, como una instancia de DICOM, ya existe. No vuelvas a intentarlo sin solucionar el problema.
7 PERMISSION_DENIED El llamador no tiene permiso para ejecutar la operación especificada. Este código de error no sugiere que la solicitud sea válida o que la entidad solicitada exista o satisfaga otras condiciones previas. No vuelvas a intentarlo sin solucionar el problema.
8 RESOURCE_EXHAUSTED Se agotaron algunos recursos, como una cuota por proyecto. Si quieres conocer las acciones recomendadas, consulta Prácticas recomendadas para la administración de cuotas. Vuelve a intentarlo con una retirada exponencial. Es posible que la cuota esté disponible con el tiempo.
9 FAILED_PRECONDITION La operación se rechazó debido a que el sistema no se encuentra en un estado necesario para la ejecución de la operación. Por ejemplo, el directorio que se borrará no está vacío, o se aplicará una operación rmdir a un elemento que no es un directorio. No vuelvas a intentarlo sin solucionar el problema.
10 ABORTED La operación se anuló, generalmente debido a un problema de simultaneidad, como una falla en la verificación del secuenciador o la anulación de la transacción. Vuelve a intentarlo con una retirada exponencial.
11 OUT_OF_RANGE La operación se intentó más allá del rango válido, como buscar o leer más allá del final del archivo. A diferencia de INVALID_ARGUMENT, este error indica un problema que se puede solucionar si cambia el estado del sistema. No vuelvas a intentarlo sin solucionar el problema.
12 UNIMPLEMENTED La operación no se implementó, no está habilitada o no se admite en la API de Cloud Healthcare. No volver a intentar.
13 INTERNAL Errores internos. Esto indica que se produjo un error inesperado en el procesamiento del sistema subyacente. Vuelve a intentarlo con una retirada exponencial.
14 UNAVAILABLE La API de Cloud Healthcare no está disponible en este momento. Lo más probable es que esta sea una condición transitoria y que se pueda corregir si vuelves a intentar una retirada. Ten en cuenta que no siempre es seguro reintentar operaciones no idempotentes. Vuelve a intentarlo con una retirada exponencial.
15 DATA_LOSS Daño o pérdida de datos no recuperable. Comunícate con tu administrador del sistema. Si se pierden o se dañan los datos, el administrador del sistema puede comunicarse con un representante del servicio de asistencia.
16 UNAUTHENTICATED La solicitud no tiene credenciales de autenticación válidas para la operación. No vuelvas a intentarlo sin solucionar el problema.