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

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

Lorsqu'une méthode API peut prendre beaucoup de temps, elle peut renvoyer une Operation au client. Le client peut utiliser l'interface Operation pour récupérer l'état de la méthode API de manière asynchrone en interrogeant l'opération. Les opérations de longue durée de l'API Cloud Healthcare respectent le modèle de conception de longue durée 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 la méthode projects.locations.datasets.fhirStores.import est appelée, 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 possède 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 une méthode qui renvoie une opération de longue durée, telle que projects.locations.datasets.fhirStores.import, vous pouvez afficher l'état de l'opération en envoyant une requête contenant l'ID de l'opération à l'ensemble de données parent du magasin FHIR dans lequel l'importation est effectuée.

En plus de l'API REST, les sources suivantes génèrent des opérations 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:

Google Cloud CLI
Page API Cloud Healthcare dans la console Google Cloud

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 renvoyant 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:

projects.locations.datasets.consentStores.queryAccessibleData

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 affichée dans la réponse lors de l'obtention d'informations sur une opération de longue durée est identique à la version de l'API de la méthode qui a initié l'opération.

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.

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

Accéder à la page "Ensembles de données"
Cliquez sur le nom de l'ensemble de données contenant l'opération de longue durée que vous souhaitez afficher.
Cliquez sur Opérations.
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.
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. Cette page affiche les informations suivantes:
- Progression de l'opération de longue durée
- 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
- 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. L'exécution de la commande se poursuit jusqu'à la fin, après quoi elle génère le résultat suivant:

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

Pour en savoir plus sur 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 obtenir le nom de l'opération de longue durée 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 la requête, 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

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter gcloud auth list pour vérifier le compte actuellement actif.

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éponse

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

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:

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

Accéder à la page "Ensembles de données"
Cliquez sur le nom de l'ensemble de données contenant l'opération de longue durée que vous souhaitez afficher.
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 dans un ensemble de données, utilisez la méthode projects.locations.datasets.operations.get.

Avant d'utiliser les données de la requête, 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

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

Réponse

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

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 opération de longue durée dans la console Google Cloud, procédez comme suit:

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

Accéder à la page "Ensembles de données"
Cliquez sur le nom de l'ensemble de données contenant l'opération de longue durée que vous souhaitez afficher.
Cliquez sur Opérations.
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 la requête, 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

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

Réponse

{}

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

Avant d'utiliser les données de la requête, 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

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

Réponse

{
  "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."
  }
}

Annuler plusieurs opérations de longue durée

Pour annuler plusieurs opérations de longue durée, procédez comme suit:

Appelez la méthode operations.list pour obtenir les noms des opérations d'un ensemble de données.
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 opérations de longue durée

Lorsqu'une opération de longue durée échoue, la réponse inclut un code d'erreur Google Cloud canonique. Le tableau suivant explique la cause de chaque code et fournit des recommandations sur la façon de les gérer. En cas d'erreurs, il est recommandé de relancer la requête à l'aide d'un intervalle exponentiel entre les tentatives. Pour plus d'informations sur la mise en œuvre d'un intervalle exponentiel entre les tentatives dans l'API Cloud Healthcare, consultez Relancer 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.	Réexécutez l'opération si vous le souhaitez.
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 une erreur d'API ne renvoie pas suffisamment d'informations, elle peut être convertie en cette erreur.	Réessayez 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 réessayez pas 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 a abouti. Par exemple, une réponse réussie d'un serveur aurait pu être retardée suffisamment longtemps pour que le délai expire.	Réessayez avec un intervalle exponentiel entre les tentatives.
5	`NOT_FOUND`	Une entité demandée, telle qu'une ressource FHIR, est introuvable.	Ne réessayez pas 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 réessayez pas 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 est valide ni que l'entité demandée existe ou qu'elle répond à d'autres conditions préalables.	Ne réessayez pas avant d'avoir résolu le problème.
8	`RESOURCE_EXHAUSTED`	Certaines ressources sont épuisées, comme un quota par projet. Pour connaître les actions recommandées, consultez la section Bonnes pratiques de gestion des quotas.	Réessayez avec un intervalle exponentiel entre les tentatives. Le quota peut devenir disponible 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 réessayez pas 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éessayez 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 réessayez pas 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.	Veuillez 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éessayez avec un intervalle exponentiel entre les tentatives.
14	`UNAVAILABLE`	L'API Cloud Healthcare est actuellement indisponible. 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éessayez 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 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 réessayez pas avant d'avoir résolu le problème.