Cette page a été traduite par l'API Cloud Translation.

Bonnes pratiques concernant les opérations de longue durée

Cette page décrit les bonnes pratiques à suivre pour exécuter et gérer des opérations de longue durée (LRO) dans l'API Cloud Healthcare. Pour obtenir une présentation des opérations de longue durée dans l'API Cloud Healthcare, consultez Gérer les opérations de longue durée.

Propriétés LRO

Les sections suivantes s'appliquent aux méthodes listées dans Méthodes qui renvoient une opération de longue durée.

Impact sur les quotas

Les LRO ne partagent pas de quota avec les méthodes de création, de lecture, de mise à jour et de suppression (CRUD) de l'API Cloud Healthcare qui consomment les types de quota suivants:

Le quota de LRO est calculé à l'aide des métriques fhir_store_lro_ops et dicom_store_lro_ops.

L'API Cloud Healthcare limite le nombre d'opérations de longue durée pouvant s'exécuter simultanément dans un projet Google Cloud. Pour en savoir plus, consultez la section Limites du nombre de LRO.

Débit de données

Les méthodes LRO permettent généralement d'obtenir un débit de données plus élevé que les méthodes CRUD équivalentes. Par exemple, l'importation d'instances DICOM avec dicomStores.import est généralement plus efficace que le stockage individuel des instances avec dicomStores.storeInstances.

L'exécution simultanée de plusieurs LRO peut ne pas augmenter le débit de données en raison des contraintes suivantes, en particulier lors du traitement de grands volumes de données:

Limites de quota
Conflit de ressources
Autre trafic que votre projet Google Cloud envoie à l'API Cloud Healthcare pendant l'exécution d'une LRO

Pour un débit de données maximal lors de l'exécution d'opérations de longue durée, tenez compte des points suivants:

Les petits lots d'importation et d'exportation ont généralement un débit faible en raison des dépenses indirectes.
Les opérations de longue durée s'exécutent et consomment des quotas séparément des autres opérations de l'API Cloud Healthcare.
Chaque LRO a un débit maximal.
Les LRO simultanés sur la même ressource peuvent entraîner des conflits de verrouillage.
L'API Cloud Healthcare limite le nombre d'opérations de longue durée pouvant s'exécuter simultanément dans un projet Google Cloud. Pour en savoir plus, consultez la section Limites du nombre de LRO.

Prévoyez le nombre de LRO dont votre cas d'utilisation a besoin. Si vous devez partitionner de grands lots de données sur plusieurs LRO, essayez de limiter le nombre de partitions.

Intégrité référentielle FHIR

La méthode fhirStores.import ne tient pas compte du paramètre disableReferentialIntegrity. Vous pouvez ainsi importer des données avec des interdépendances arbitraires qui ne nécessitent pas d'ordre ni de regroupement, ce qui augmente le débit des données. Si les données d'entrée contiennent des références non valides ou si l'importation de certaines ressources FHIR échoue, l'état du magasin FHIR peut enfreindre l'intégrité référentielle.

Pour utiliser fhirStores.import, votre application cliente doit s'assurer que les références de ressources FHIR sont valides en vérifiant les points suivants:

Les données et la mise en forme des ressources FHIR sont correctes
Toutes les erreurs qui se produisent lors de l'importation sont gérées.

Pour appliquer l'intégrité référentielle, utilisez fhir.create ou fhir.executeBundle au lieu de fhirStores.import. Pour en savoir plus, consultez Importer des données FHIR ou exécuter des groupes.

Notifications Pub/Sub

Certaines méthodes de l'API Cloud Healthcare envoient des notifications Pub/Sub pour les événements cliniques, tels que la création ou la suppression d'une ressource de santé. Pour obtenir la liste des méthodes qui envoient des notifications Pub/Sub, consultez la section Configurer les notifications Pub/Sub.

Les méthodes d'importation suivantes n'envoient pas de notifications Pub/Sub:

Si certaines parties de votre application nécessitent une notification à la fin d'une importation, utilisez une autre méthode de notification pouvant lister les données de l'importation.

Limites de traitement des erreurs

L'API Cloud Healthcare ne consigne pas nécessairement toutes les erreurs d'une opération de longue durée, en particulier si l'opération de longue durée traite de grands volumes de données et produit de nombreuses erreurs. Implémentez un moyen de suivre le traitement et les erreurs des LRO séparément. Pour en savoir plus, consultez la section Gestion des erreurs de ressources.

Indexation des données et de la recherche

Des retards dans les résultats de recherche peuvent se produire en raison de l'indexation asynchrone de la recherche. Si une LRO crée ou met à jour une ressource FHIR, il peut s'écouler un certain temps avant que les modifications ne soient disponibles dans les résultats de recherche.

Par exemple, une recherche de ressources Patient dans un store FHIR peut ne pas renvoyer tous les résultats immédiatement après une opération d'importation FHIR.

Ordre d'exécution

Les LRO sont planifiées en fonction de la disponibilité des ressources Google Cloud. L'ordre dans lequel les LRO sont exécutés et terminés peut ne pas correspondre à l'ordre dans lequel ils ont été demandés.

Éviter les petites requêtes d'importation et d'exportation

Cette section décrit les limites de la LRO lors du traitement de petits volumes de données.

Les LRO renvoyés par les opérations d'importation et d'exportation permettent d'augmenter le débit des données en traitant rapidement de grandes quantités de données et en évitant les pics de charge. Pour stocker de petites quantités de données, utilisez une autre technique décrite dans la section Bonnes pratiques pour le stockage des données.

Limites applicables au nombre de LRO

L'API Cloud Healthcare limite le nombre d'opérations de longue durée pouvant s'exécuter simultanément dans un projet Google Cloud. Cette limite est basée sur les éléments suivants:

Type de LRO.
Quantité de ressources Google Cloud allouées à l'ordre d'achat. Cela dépend de la taille des données d'entrée.

Si vous exécutez trop d'opérations de longue durée, l'API Cloud Healthcare limite le débit, produit des erreurs et peut réduire le débit des opérations de longue durée. L'API Cloud Healthcare conserve automatiquement les ressources Google Cloud afin que le nombre d'opérations de longue durée reste dans les limites de ressources.

Les LRO sont des processus en arrière-plan. Par conséquent, si la charge des LRO interfère avec des processus de priorité plus élevée, tels que les opérations CRUD, l'API Cloud Healthcare peut réduire le débit des LRO. Cela garantit que les processus de priorité plus élevée sont disponibles.

Coûts liés à l'allocation et au nettoyage des ressources

Lorsqu'une opération de longue durée commence, l'API Cloud Healthcare alloue des ressources. Cela peut prendre plusieurs minutes, car l'API Cloud Healthcare doit effectuer les opérations suivantes:

Démarrez un processus de contrôleur.
Allouer des nœuds de calcul à partir d'un pool de nœuds de calcul.
Déterminez la taille des données d'entrée.
Commencez à allouer du travail à grande échelle.

L'arrêt et le nettoyage d'une LRO peuvent également prendre plusieurs minutes.

En raison des frais généraux, une LRO qui traite une petite quantité de données peut passer la majeure partie de son temps à allouer des pools de workers et à nettoyer des ressources.

Si vous avez de nombreuses LRO, vous risquez de constater un débit de données inférieur, car vous êtes plus susceptible d'atteindre les limites de quota de votre projet Google Cloud.

Limites concernant les demandes de quota de LRO

Avant de demander plus de quota de requêtes en ligne hors connexion, suivez les bonnes pratiques de gestion des quotas. Si vous avez encore besoin de quota, contactez le service client Google Cloud. Pour effectuer une demande, consultez les bonnes pratiques pour demander un quota supplémentaire.

Vous devrez peut-être augmenter votre quota si vos données d'entrée sont volumineuses, par exemple:

Vous importez des instances DICOM de plusieurs pétaoctets (Po).
Vous importez des dizaines de milliards de ressources FHIR.

État de l'ordre de réparation et états d'échec

Lorsque vous démarrez une requête LRO, la réponse contient un ID unique. Vous pouvez consulter l'état d'une LRO en interrogeant son ID. Une fois la LRO terminée, elle présente l'un des états suivants:

Terminée sans erreur
Opération terminée avec quelques erreurs
L'opération n'a pas pu être terminée, mais elle a peut-être généré une sortie partielle avant l'échec

L'exemple JSON suivant décrit la réponse renvoyée à la fin d'une LRO:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "METADATA_TYPE",
    "apiMethodName": "API_METHOD_NAME",
    "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": 
    
  },
  // 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: ...,
        ...
      }
    ]
  }
}

Pour connaître l'état d'une opération de longue durée, en lister et en annuler, consultez la section Gérer les opérations de longue durée.

Gérer l'état des LRO et les états d'échec

Pour gérer l'état et les états d'échec des LRO, suivez ces bonnes pratiques:

Interrogez les LRO pour connaître leur état et vérifier quand ils sont terminés. 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. Lorsque la réponse contient "done": true, l'opération de longue durée est terminée.
Une fois une opération de longue durée terminée, vérifiez si la réponse contient un champ error. Si c'est le cas, déterminez si vous devez répéter l'opération en fonction des éléments suivants:
- Code d'erreur. Pour connaître les codes d'erreur et les actions recommandées, consultez Résoudre les erreurs LRO.
- Nombre de tentatives déjà effectuées.
- Intervalle de temps entre le début de la requête LRO et le moment où l'erreur s'est produite. Par exemple, si une LRO qui prend normalement plusieurs heures prend plusieurs jours et n'a pas renvoyé d'état d'échec, vous pouvez demander à un humain d'intervenir. Pour en savoir plus sur les cas où une intervention humaine peut être requise, consultez la section Planifier les états d'erreur finaux.
Pour savoir comment répéter une opération de longue durée, consultez Mettre une opération de longue durée en file d'attente.
Si vous ne réessayez pas la LRO, consultez le champ metadata.counter.failure pour voir si des erreurs se sont produites sur des ressources spécifiques. Vous pouvez peut-être traiter les ressources individuellement. Pour en savoir plus, consultez la section Gérer les erreurs de ressources.

Gérer les erreurs de ressources

Une LRO peut se terminer avec des erreurs. Les erreurs de la réponse de l'opération de longue durée suivent le modèle d'erreur Google Cloud. La réponse de l'appel LRO inclut un lien vers Cloud Logging pour en savoir plus.

Détails de l'erreur LRO

Les erreurs LRO dans Cloud Logging présentent les propriétés suivantes:

Le journal des erreurs Cloud Logging ne contient pas l'ID de l'ordre de requête en ligne. Utilisez les champs operation.id et operation.producer pour trouver l'état et les erreurs de l'opération de longue durée. Par exemple, les LRO appelées à partir de la méthode projects.locations.datasets.fhirStores.import contiennent import_fhir dans le champ operation.producer.

Si plusieurs LRO ont le même operation.id et le même operation.producer, utilisez les codes temporels createTime et endTime pour identifier le LRO approprié.
Toutes les erreurs LRO ne sont pas disponibles dans Cloud Logging. Le champ metadata.counter.failure peut dépasser le nombre d'erreurs réelles consignées pour les raisons suivantes:
- Limites des quotas Cloud Logging
- Disponibilité du service Cloud Logging
- Limites des journaux LRO
Par exemple, si une LRO importe 10 millions de ressources FHIR, et que 50% d'entre elles comportent des erreurs de mise en forme, seules quelques centaines ou quelques milliers d'erreurs peuvent être consignées en raison de la limitation du débit et des quotas Cloud Logging.

Le nombre d'erreurs enregistrées varie également en fonction de la durée d'exécution de l'analyse des erreurs lors de la rencontre de taux d'erreur élevés. Si l'exécution de l'LRO est lente, il est possible que davantage d'erreurs s'affichent dans Cloud Logging, car les erreurs ont été réparties sur une longue période et n'ont pas été soumises à la limitation de débit.

Effets de la nouvelle tentative d'une opération de longue durée

Si une LRO rencontre une erreur et qu'une application cliente relance automatiquement l'opération à l'aide des mêmes données, la nouvelle tentative peut entraîner d'autres erreurs.

Imaginons un scénario où une LRO fhirStores.import se termine par des erreurs, car certaines des ressources FHIR qu'elle a essayé d'importer n'étaient pas valides. Si vous relancez automatiquement l'importation avec les mêmes données, de nombreuses erreurs 409 ALREADY_EXISTS peuvent être générées, car certaines ressources FHIR ont été importées dans l'opération d'origine. Si vous interrogez une opération de longue durée et que vous constatez qu'une opération de création a échoué, ne réessayez pas automatiquement. Un humain doit examiner les erreurs 409 ALREADY_EXISTS.

Si une nouvelle tentative aboutit, le champ metadata.counter.failure n'inclut pas les erreurs des opérations précédentes. Cela peut entraîner un nombre d'erreurs incorrect, car la réponse de la nouvelle tentative réussie n'inclut pas les erreurs des tentatives précédentes.

Réessayer une opération de longue durée

Si vous disposez d'un pipeline de traitement côté client qui détecte des erreurs LRO, n'utilisez pas Cloud Logging. Comme indiqué dans la section Détails des erreurs des opérations de longue durée, les journaux d'erreurs Cloud Logging des opérations de longue durée sont peu fiables et incomplets. Utilisez plutôt les techniques décrites dans les sections suivantes.

Réessayer d'importer des opérations

Pour détecter les données qui n'ont pas pu être importées, comparez les données importées dans l'API Cloud Healthcare à leurs données sources dans Cloud Storage. Vous pouvez importer des données à l'aide des méthodes suivantes:

Utilisez un identifiant unique, tel qu'un numéro de dossier médical (MRN) pour une ressource Patient FHIR, pour comparer les données.

Consultez la section Effets de la nouvelle tentative d'exécution d'une opération de longue durée pour connaître la procédure à suivre lorsque vous réessayez une opération d'importation.

Si vous réexécutez une importation, vous risquez de recréer des ressources que vous avez précédemment supprimées. Imaginez le scénario suivant:

Vous essayez d'importer 1 000 000 de ressources FHIR. 50 000 ressources échouent en raison d'erreurs de mise en forme.
Vous passez plusieurs jours à corriger les erreurs de mise en forme. Pendant ce temps, un patient vous demande de supprimer ses dossiers.
Si vous relancez l'importation, vous risquez de recréer les données du patient que vous avez supprimées.

Réessayer les opérations d'exportation

Pour détecter les données qui n'ont pas pu être exportées vers BigQuery, écrivez un script permettant de comparer les ID uniques des données sources aux données exportées.

Vous pouvez exporter des données vers BigQuery de différentes manières:

Mettre en file d'attente et gérer les LRO

Si vous exécutez des requêtes LRO qui traitent de grands volumes de données pour l'intégration ou de manière régulière, implémentez les techniques de mise en file d'attente LRO suivantes:

Limitez le nombre de LRO simultanés à un petit nombre, comme 5. Vous pouvez ajuster cette limite en fonction de la taille et des types de requêtes de recherche locale que vous exécutez.
Surveillez l'achèvement de l'opération de récupération de l'objet LRO. En cas d'erreurs, reprogrammez la LRO ou corrigez-les séparément dans votre pipeline de traitement.
Résolvez automatiquement les erreurs dans la section Gérer les erreurs de ressources lorsque cela est possible.
- Comprendre le cas d'utilisation des importations FHIR pour déterminer si les erreurs 409 ALREADY_EXISTS doivent être ignorées ou si des opérations CRUD distinctes doivent être effectuées pour les résoudre. Comme indiqué dans la section Détails des erreurs LRO, certaines erreurs 409 ALREADY_EXISTS peuvent ne pas être enregistrées dans Cloud Logging. Si votre application s'appuie sur des journaux d'erreurs, utilisez l'une des techniques décrites dans la section Réessayer une LRO.
- Pour résoudre quelques erreurs, mettez en file d'attente une LRO plus petite pour les données qui ont rencontré les erreurs ou effectuez des opérations CRUD distinctes.
- Pour résoudre de nombreuses erreurs, la réexécution de l'opération de longue durée peut être l'option la plus simple pour assurer la cohérence. Pour connaître les risques de réexécuter une importation sur des données supprimées, consultez la section Réessayer les opérations d'importation.
Détectez automatiquement si une intervention humaine est nécessaire pour résoudre les erreurs. Vous devez disposer d'outils et de livres de jeu opérationnels pour les administrateurs système. Voici quelques exemples de tâches à effectuer pour résoudre les erreurs:
- Reprogrammer une opération de longue durée.
- Reprogrammer un sous-ensemble de données d'une demande de récupération de données précédente.
- Examinez les erreurs et corrigez les éléments de données individuels qui ont rencontré des erreurs. Cette tâche n'est possible que si vous pouvez déterminer que toutes les erreurs de l'enregistrement de l'erreur de l'ordre de réparation ont été consignées.
Déterminer les horaires des LOR Vous pouvez planifier des LRO pour éviter qu'ils ne s'exécutent aux heures de pointe, lorsque de nombreuses opérations CRUD sont en cours d'exécution. Pour en savoir plus, consultez la section Gérer le quota pour maximiser le débit de données.

Surveiller et recevoir des alertes

Créez et gérez des procédures de surveillance des LRO et de résolution des alertes. Les alertes sont principalement causées par les états de LRO et les problèmes de mise en file d'attente. Les procédures doivent couvrir les situations suivantes:

LRO qui tentent de nouvelles tentatives plus de fois que prévu.
Problèmes nécessitant une intervention humaine pour résoudre un sous-ensemble d'erreurs. Par exemple, si une LRO échoue et que le client ne parvient pas à résoudre les erreurs, une intervention humaine est probablement nécessaire. Pour savoir comment résoudre les problèmes nécessitant une intervention humaine, consultez Mettre en file d'attente et gérer les requêtes LRO.
Files d'attente qui dépassent une longueur ou qui augmentent trop rapidement
Non-respect des exigences du règlement, par exemple en cas de problème d'autorisation ou de mauvaise configuration.
Vérifications de cohérence qui révèlent des problèmes systémiques dans plusieurs LRO Vous pouvez avoir plusieurs LRO de désidentification qui s'attendent à ce que l'ensemble de données source et l'ensemble de données de destination aient le même nombre de ressources FHIR. Si un écart augmente avec le temps, cela peut indiquer des données non traitées.
Problèmes de quota LRO Pour en savoir plus, consultez les pages Gérer les quotas pour maximiser le débit de données et Bonnes pratiques pour la gestion des quotas.