Gérer les opérations de longue durée

Cette page explique comment gérer le cycle de vie d'une API Cloud Healthcare une opération de longue durée (LRO).

Lorsqu'une méthode d'API peut prendre beaucoup de temps, elle peut renvoyer un Operation au client. Le client peut utiliser l'interface Operation pour récupérer les l'état de la méthode API de manière asynchrone en interrogeant l'opération. des opérations de longue durée L'API Cloud Healthcare respecte le modèle de conception LRO de Google Cloud.

L'API Cloud Healthcare crée des opérations de longue durée pour plusieurs méthodes, telles que projects.locations.datasets.fhirStores.import. Lorsque projects.locations.datasets.fhirStores.import est appelé, le L'API Cloud Healthcare crée une opération de longue durée pour suivre l'état de l'importation. L'opération de longue durée dispose d'un identifiant unique que vous pouvez utiliser pour afficher son état.

Les opérations de longue durée sont gérées au niveau de l'ensemble de données. Si vous appelez un qui renvoie une opération de longue durée, comme projects.locations.datasets.fhirStores.import, vous pouvez consulter l'état de l'opération de longue durée en envoyant une requête contenant ID de l'opération de longue durée de l'ensemble de données parent du store FHIR où l'importation a lieu.

Outre l'API REST, les sources suivantes génèrent des requêtes de longue durée lorsque vous appelez les méthodes répertoriées dans la section Méthodes qui renvoient une opération de longue durée:

Vous pouvez gérer les opérations de longue durée de l'API Cloud Healthcare à l'aide de la console Google Cloud, de Google Cloud CLI ou de l'API REST.

L'enregistrement associé à une opération de longue durée est conservé pendant environ 30 jours après son exécution, ce qui signifie que vous ne pouvez pas afficher ni répertorier une opération de longue durée après cette date.

Méthodes qui renvoient une opération de longue durée

Les méthodes suivantes renvoient une opération de longue durée.

Méthodes de gestion du consentement :

Méthodes de l'ensemble de données:

Méthodes DICOM:

Méthodes FHIR:

Méthodes HL7v2:

Obtenir des informations sur une opération de longue durée

Les exemples suivants montrent comment afficher les détails d'une opération de longue durée.

La version de l'API Cloud Healthcare indiquée dans la réponse lorsque vous obtenez des détails sur une opération de longue durée est identique à la version de l'API de la méthode qui a lancé l'opération de longue durée.

Console

Après avoir utilisé gcloud CLI ou l'API pour appeler une méthode qui renvoie une opération de longue durée, vous pouvez afficher les détails de l'opération de longue durée dans la console Google Cloud.

  1. Dans la console Google Cloud, accédez à la page Ensembles de données.

    Accéder à la page "Ensembles de données"

  2. Cliquez sur le nom de l'ensemble de données contenant l'opération de longue durée que vous souhaitez afficher.

  3. Cliquez sur Opérations.

  4. Pour afficher les journaux d'erreurs de l'opération dans Cloud Logging, cliquez sur Actions, puis sur Afficher les détails dans Cloud Logging. Pour en savoir plus, consultez la section Afficher les journaux d'erreurs dans Cloud Logging.

  5. Pour afficher davantage de détails sur l'opération, cliquez sur l'ID d'une opération en cours d'exécution. La page Détails de l'opération de longue durée s'affiche. La page affiche les informations suivantes:

    • Progression de l'opération de longue durée
    • Les détails de l'opération de longue durée, tels que l'ID d'opération et la méthode qui a appelé l'opération de longue durée
    • un sous-ensemble d'entrées de journal ;

gcloud

Supposons que vous receviez la réponse suivante après avoir appelé gcloud healthcare dicom-stores deidentify :

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

La réponse indique que l'API Cloud Healthcare a créé une opération de longue durée avec un ID d'opération. Vous pouvez également obtenir l'ID d'opération en répertoriant les opérations de base de données de longue durée. La commande continue de s'exécuter jusqu'à ce qu'elle soit terminée, puis génère les éléments suivants :

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

Pour obtenir les détails de l'opération de longue durée, exécutez la commande gcloud healthcare operations describe.

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • DATASET_ID : ID de l'ensemble de données
  • LOCATION : emplacement de l'ensemble de données
  • OPERATION_ID : ID renvoyé par l'opération de longue durée

Exécutez la commande suivante :

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

Vous devriez obtenir un résultat semblable à celui-ci :

Réponse

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

Supposons que vous receviez la réponse suivante après avoir appelé projects.locations.datasets.dicomStores.deidentify :

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

La valeur name dans la réponse indique que l'API Cloud Healthcare a créé une opération de longue durée appelée projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID. Vous pouvez également récupérer le nom de l'opération en répertoriant les opérations de longue durée.

Pour obtenir l'état de l'opération de longue durée, utilisez la méthode projects.locations.datasets.operations.get. Pour interroger une opération de longue durée, appelez la méthode projects.locations.datasets.operations.get de façon répétée jusqu'à la fin de l'opération. Observez un intervalle (10 secondes, par exemple) entre chaque tentative d'interrogation.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • DATASET_ID : ID de l'ensemble de données
  • LOCATION : emplacement de l'ensemble de données
  • OPERATION_ID : ID renvoyé par l'opération de longue durée

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

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

Exécutez la commande suivante :

$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

API Explorer

Ouvrez la page de référence de la méthode. Le panneau APIs Explorer s'ouvre dans la partie droite de la page. Vous pouvez interagir avec cet outil pour envoyer des requêtes. Renseignez tous les champs obligatoires, puis cliquez sur Execute (Exécuter).

Le résultat est le suivant. Lorsque la réponse contient "done": true, l'opération de longue durée est terminée.

Répertorier les opérations de longue durée

Les exemples suivants montrent comment répertorier les opérations de longue durée dans un ensemble de données.

Console

Pour afficher la liste de toutes les opérations de longue durée d'un ensemble de données dans la console Google Cloud, procédez comme suit:

  1. Dans la console Google Cloud, accédez à la page Ensembles de données.

    Accéder à la page "Ensembles de données"

  2. Cliquez sur le nom de l'ensemble de données contenant l'opération de longue durée que vous souhaitez afficher.

  3. Cliquez sur Opérations.

Les opérations de longue durée de l'ensemble de données et leur état s'affichent. Pour afficher les journaux d'erreurs dans Cloud Logging, cliquez sur l'icône "Plus d'informations" dans la dernière colonne, puis sur Afficher les détails dans Cloud Logging. Pour en savoir plus, consultez la section Afficher les journaux d'erreurs dans Cloud Logging.

gcloud

Pour répertorier les opérations de longue durée d'un ensemble de données, exécutez la commande gcloud healthcare operations list.

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • DATASET_ID : ID de l'ensemble de données
  • LOCATION : emplacement de l'ensemble de données

Exécutez la commande suivante :

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

Vous devriez obtenir un résultat semblable à celui-ci :

Réponse

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

REST

Pour répertorier les opérations de longue durée d'un ensemble de données, utilisez la projects.locations.datasets.operations.get .

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • DATASET_ID : ID de l'ensemble de données
  • LOCATION : emplacement de l'ensemble de données

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

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

Exécutez la commande suivante :

$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

API Explorer

Ouvrez la page de référence de la méthode. Le panneau APIs Explorer s'ouvre dans la partie droite de la page. Vous pouvez interagir avec cet outil pour envoyer des requêtes. Renseignez tous les champs obligatoires, puis cliquez sur Exécuter.

Vous devriez recevoir une réponse JSON de ce type :

Annuler une opération de longue durée

Les exemples suivants montrent comment annuler une opération de longue durée dans un ensemble de données.

Console

Pour annuler une LRO dans la console Google Cloud, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page Ensembles de données.

    Accéder à la page "Ensembles de données"

  2. Cliquez sur le nom de l'ensemble de données contenant l'opération de longue durée que vous souhaitez afficher.

  3. Cliquez sur Opérations.

  4. Sur la ligne correspondant à l'opération de longue durée que vous souhaitez annuler, ouvrez la liste Actions, puis cliquez sur Arrêter l'opération.

REST

Pour annuler une opération de longue durée, utilisez la méthode projects.locations.datasets.operations.cancel.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • DATASET_ID : ID de l'ensemble de données
  • LOCATION : emplacement de l'ensemble de données
  • OPERATION_ID : ID renvoyé par l'opération de longue durée

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

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

Exécutez la commande suivante :

$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

API Explorer

Ouvrez la page de référence de la méthode. Le panneau APIs Explorer s'ouvre dans la partie droite de la page. Vous pouvez interagir avec cet outil pour envoyer des requêtes. Renseignez tous les champs obligatoires, puis cliquez sur Exécuter.

Vous devriez recevoir une réponse JSON de ce type :

Pour afficher l'état de la requête d'annulation, utilisez la méthode projects.locations.datasets.operations.get.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • DATASET_ID : ID de l'ensemble de données
  • LOCATION : emplacement de l'ensemble de données
  • OPERATION_ID : ID renvoyé par l'opération de longue durée

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

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

Exécutez la commande suivante :

$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

API Explorer

Ouvrez la page de référence de la méthode. Le panneau APIs Explorer s'ouvre dans la partie droite de la page. Vous pouvez interagir avec cet outil pour envoyer des requêtes. Renseignez tous les champs obligatoires, puis cliquez sur Exécuter.

Vous devriez recevoir une réponse JSON de ce type :

Annuler plusieurs opérations de longue durée

Pour annuler plusieurs LRO, procédez comme suit :

  1. Appelez la méthode operations.list pour obtenir les noms des opérations d'un ensemble de données.
  2. Appelez la méthode operations.cancel pour chaque opération.

Google fournit un script Python que vous pouvez utiliser pour annuler toutes les opérations d'un ensemble de données spécifique.

Résoudre les problèmes liés aux LRO

Lorsqu'une opération de longue durée échoue, sa réponse inclut un code d'erreur Google Cloud canonique. Le tableau suivant fournit une explication de la cause de chaque code et une recommandation pour comment gérer le code. Lorsqu'il y a de nombreuses erreurs, nous vous recommandons d'essayer en utilisant un intervalle exponentiel entre les tentatives. Pour savoir comment mettre en œuvre un délai avant nouvelle tentative exponentiel dans l'API Cloud Healthcare, consultez la section Réessayer les requêtes ayant échoué.

Code Enum Description Action recommandée
1 CANCELLED L'opération a été annulée, généralement par l'appelant. Si vous le souhaitez, réexécutez l'opération.
2 UNKNOWN Cette erreur peut s'afficher lorsqu'une valeur Status reçue d'un autre espace d'adressage appartient à un espace d'erreur inconnu dans cet espace d'adressage. Si l'erreur d'une API ne renvoie pas suffisamment d'informations, elle peut être convertie en cette erreur. Réessayer avec un intervalle exponentiel entre les tentatives
3 INVALID_ARGUMENT Le client a spécifié un argument non valide. Cette erreur diffère de FAILED_PRECONDITION. INVALID_ARGUMENT indique les arguments problématiques quel que soit l'état du système (par exemple, un nom de fichier mal formé). Ne relancez pas la requête avant d'avoir résolu le problème.
4 DEADLINE_EXCEEDED Le délai a expiré avant que l'opération puisse se terminer. Pour les opérations qui modifient l'état du système, cette erreur peut être renvoyée même si l'opération s'est terminée avec succès. Par exemple, une réponse réussie d'un serveur aurait pu être retardée suffisamment longtemps pour que le délai expire. Réessayer avec un intervalle exponentiel entre les tentatives
5 NOT_FOUND Une entité demandée (par exemple, une ressource FHIR) est introuvable. Ne relancez pas la requête avant d'avoir résolu le problème.
6 ALREADY_EXISTS L'entité qu'un client a tenté de créer, telle qu'une instance DICOM, existe déjà. Ne relancez pas la requête avant d'avoir résolu le problème.
7 PERMISSION_DENIED L'appelant n'est pas autorisé à exécuter l'opération spécifiée. Ce code d'erreur n'implique pas que la requête soit valide ni que l'entité demandée existe ou qu'elle répond à d'autres prérequis. Ne relancez pas la requête avant d'avoir résolu le problème.
8 RESOURCE_EXHAUSTED Une ressource a été épuisée, par exemple un quota par projet. Pour connaître les actions recommandées, consultez la section Bonnes pratiques de gestion des quotas. Réessayer avec un intervalle exponentiel entre les tentatives Des quotas peuvent être disponibles au fil du temps.
9 FAILED_PRECONDITION L'opération a été rejetée car le système n'est pas dans un état requis pour exécuter l'opération. Par exemple, le répertoire à supprimer n'est pas vide ou une opération rmdir est appliquée à un emplacement qui n'est pas un répertoire. Ne relancez pas la requête avant d'avoir résolu le problème.
10 ABORTED L'opération a été abandonnée, généralement en raison d'un problème de simultanéité, tel qu'un échec de vérification du séquenceur ou un abandon de transaction. Réessayer avec un intervalle exponentiel entre les tentatives
11 OUT_OF_RANGE L'opération a été tentée au-delà de la plage valide (par exemple, rechercher ou lire après la fin du fichier). Contrairement à INVALID_ARGUMENT, cette erreur indique un problème pouvant être résolu si l'état du système change. Ne relancez pas la requête avant d'avoir résolu le problème.
12 UNIMPLEMENTED L'opération n'est pas implémentée ou n'est pas prise en charge/activée dans l'API Cloud Healthcare. Ne pas réessayer.
13 INTERNAL Erreurs internes. Cela indique qu'une erreur inattendue s'est produite lors du traitement dans le système sous-jacent. Réessayer avec un intervalle exponentiel entre les tentatives
14 UNAVAILABLE L'API Cloud Healthcare n'est actuellement pas disponible. Il s'agit probablement d'une condition temporaire qui peut être corrigée en réessayant après avoir laissé passer un intervalle entre les tentatives. Notez qu'il n'est pas toujours sûr de relancer des opérations non idempotentes. Réessayer avec un intervalle exponentiel entre les tentatives
15 DATA_LOSS Perte ou corruption de données irrécupérable. Contactez votre administrateur système. En cas de perte ou de corruption de données, l'administrateur système peut vouloir contacter un représentant de l'assistance.
16 UNAUTHENTICATED La requête ne dispose pas d'identifiants d'authentification valides pour l'opération. Ne relancez pas la requête avant d'avoir résolu le problème.