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 en savoir plus sur les opérations de longue durée, de l'API Cloud Healthcare, consultez la page Gérer les opérations de longue durée.

Propriétés de 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 le quota

Les opérations de longue durée ne partagent pas les quotas avec l'API Cloud Healthcare, de suppression (CRUD) qui utilisent les types suivants de quota:

• fhir_read_ops
• fhir_write_ops
• fhir_search_ops
• fhir_store_ops
• dicom_web_ops
• dicom_ops

Le quota de longue durée est calculé à l'aide de la méthode fhir_store_lro_ops. et dicom_store_lro_ops métriques.

L'API Cloud Healthcare limite le nombre d'opérations de longue durée pouvant être exécutées simultanément. dans un projet Google Cloud. Pour en savoir plus, consultez Limites du nombre d'opérations de longue durée.

Débit de données

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

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

• Limites de quota
• Conflit de ressources
• Autre trafic envoyé par votre projet Google Cloud à l'API Cloud Healthcare tandis qu'une opération de longue durée s'exécute

Pour un débit de données maximal lors de l'exécution d'opérations de longue durée, envisagez les éléments suivants:

• Les petits lots d'importation et d'exportation ont généralement un faible débit pour les raisons suivantes : les frais généraux.
• Les opérations de longue durée exécutent et consomment le quota séparément des autres opérations de l'API Cloud Healthcare.
• Chaque LRO a un débit maximal.
• Les opérations de longue durée simultanées sur une 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 être exécutées simultanément. dans un projet Google Cloud. Pour en savoir plus, consultez Limites du nombre d'opérations de longue durée.

Prévoyez le nombre d'opérations de longue durée requises par votre cas d'utilisation. Si vous devez partitionner des lots de données volumineux sur plusieurs opérations de longue durée, essayez de limiter le nombre de partitions.

Intégrité référentielle FHIR

fhirStores.import ne tient pas compte disableReferentialIntegrity . Cela vous permet d'importer des données avec des interdépendances arbitraires qui ne nécessitent de commander ou de regrouper, ce qui augmente le débit des données. Si les données d'entrée contient des références non valides ou, si l'importation de certaines ressources FHIR échoue, l'état du magasin pourrait enfreindre intégrité référentielle.

Pour que vous puissiez utiliser fhirStores.import, votre application cliente doit pour vous assurer que les références aux ressources FHIR sont valides en vérifiant les points suivants:

• Les données et la mise en forme des ressources FHIR sont correctes
• Les erreurs survenant 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 plus plus d'informations, consultez la section Importer des données FHIR et exécuter des lots.

Notifications Pub/Sub

Certaines méthodes de l'API Cloud Healthcare envoient des notifications Pub/Sub pour des événements, 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 des notifications Pub/Sub.

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

• dicomStores.import
• fhirStores.import

Si certaines parties de votre application requièrent une notification l'importation est terminée, utilisez une autre méthode de notification permettant de répertorier les données dans l'importation.

Limites de traitement des erreurs

Il est possible que l'API Cloud Healthcare ne consigne pas toutes les erreurs dans une opération de longue durée, en particulier si l'opération de longue durée traite d'importants volumes de données et génère de nombreuses erreurs. Implémentation un moyen de suivre séparément le traitement et les erreurs de l'opération de longue durée. Pour en savoir plus, consultez la section Gestion des erreurs de ressources.

Indexation des données et de la recherche

Les résultats de recherche peuvent être retardés en raison de l'indexation asynchrone de la recherche. Si une opération de longue durée crée ou met à jour une ressource FHIR, cela peut prendre plus de 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. La commande L'exécution et la fin des opérations de longue durée peuvent ne pas correspondre à l'ordre dans lequel elles ont été demandées.

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

Cette section décrit les limites de l'opération de longue durée lors du traitement de petits volumes de données.

Les opérations de longue durée renvoyées par les opérations d'importation et d'exportation contribuent à faire évoluer le débit des données. en traitant rapidement de grandes quantités de données et en évitant les pics de charge. À stocker de petites quantités de données, utilisez une autre technique décrite dans Bonnes pratiques de stockage des données.

Limites applicables au nombre d'opérations de longue durée

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

• Type d'opération de longue durée.
• Quantité de ressources Google Cloud allouées à l'opération de longue durée. Ceci est basé sur la taille des données d'entrée.

Si vous exécutez trop d'opérations de longue durée, les limites de débit de l'API Cloud Healthcare génèrent et peut réduire le débit de l'opération 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 opérations de longue durée sont des processus en arrière-plan. Par conséquent, si la charge de ces opérations interfère avec des processus de priorité supérieure, de type CRUD des opérations, l'API Cloud Healthcare peut réduire débit. Cela permet de s'assurer que les processus prioritaires sont disponibles.

Frais généraux liés à l'allocation et au nettoyage des ressources

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

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

L'arrêt et le nettoyage d'une opération de longue durée peuvent également prendre plusieurs minutes.

En raison de la surcharge, une opération de longue durée qui traite une petite quantité de données peut passer la plupart de son temps à allouer des pools de nœuds de calcul 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 longue durée

Avant de demander une augmentation de quota de longue durée, implémentez la Bonnes pratiques de gestion des quotas Si vous avez encore besoin de quota, contactez Google Cloud Customer Care. Pour envoyer une demande, consultez Bonnes pratiques pour demander des quotas supplémentaires

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

• Vous importez des instances DICOM dont la taille est de plusieurs pétaoctets (Po).
• Vous importez des dizaines de milliards de ressources FHIR.

État et états d'échec de l'opération de longue durée

Lorsque vous lancez une opération de longue durée, la réponse contient un identifiant unique. Vous pouvez consulter l'état d'une LRO en interrogeant son ID. Après l'opération de longue durée se termine, elle présente l'un des états suivants:

• Opération terminée sans erreur
• Opération terminée avec quelques erreurs
• Échec de l'achèvement, mais une sortie partielle a pu être générée avant l'échec

L'exemple JSON suivant décrit la réponse renvoyée lorsqu'une opération de longue durée se termine:

{
  "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, listez les opérations de longue durée et annulez Pour les opérations de longue durée, consultez la page Gérer les opérations de longue durée.

Gérer l'état et l'état d'échec de l'opération de longue durée

Pour gérer l'état et l'état d'échec de l'opération de longue durée, 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 à plusieurs reprises la méthode projects.locations.datasets.operations.get 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 l'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 s'il faut relancer l'opération en fonction des éléments suivants:

  • Code d'erreur. Consultez la page Résoudre les problèmes liés aux opérations de longue durée. pour connaître les codes d'erreur et les actions recommandées.
  • Nombre de tentatives déjà effectuées.
  • Délai entre le début de l'opération de longue durée et le moment où l'erreur s'est produite. Par exemple, si une opération de longue durée, qui prend normalement plusieurs heures, prend plusieurs jours renvoyé un état d'échec, vous voudrez peut-être qu'un humain intervienne. Pour pour savoir quand une intervention humaine peut être nécessaire, consultez la page Anticipez 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 relancez pas l'opération de longue durée, consultez le champ metadata.counter.failure pour voir si des erreurs se sont produites sur des ressources spécifiques. Vous pourrez peut-être traiter les ressources individuellement. Pour en savoir plus, consultez Gérer les erreurs liées aux ressources.

Gérer les erreurs liées aux ressources

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

Détails de l'erreur LRO

Dans Cloud Logging, les erreurs de longue durée présentent les propriétés suivantes:

• Le journal d'erreurs Cloud Logging ne contient pas l'ID de longue durée. Utilisez le Champs operation.id et operation.producer permettant de connaître l'état de l'opération de longue durée et les erreurs. Par exemple, les opérations de longue durée appelées à partir de la méthode projects.locations.datasets.fhirStores.import contiennent import_fhir dans le champ operation.producer.

  Si plusieurs opérations de longue durée ont les mêmes valeurs operation.id et operation.producer, utiliser les codes temporels createTime et endTime pour identifier la bonne opération de longue durée.

• Toutes les erreurs de longue durée ne sont pas disponibles dans Cloud Logging. metadata.counter.failure peut dépasser le nombre d'erreurs réelles enregistrées pour les raisons suivantes:

  • Limites de quota de Cloud Logging
  • Disponibilité du service Cloud Logging
  • Limites des journaux LRO

  Par exemple, si une opération de longue durée importe 10 millions de ressources FHIR, dont 50 % comportent des erreurs de format, seules quelques centaines, voire 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 l'opération de longue durée s'exécute tout en rencontrant des taux d'erreur élevés. Si l'opération de longue durée s'exécute lentement, pourrait afficher plus d'erreurs dans Cloud Logging, car les erreurs se sont propagées sur une longue période et n'étaient pas soumis à une limitation du débit.

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

Si une opération de longue durée rencontre une erreur et qu'une application cliente effectue automatiquement une nouvelle tentative l'opération en utilisant les mêmes données, la nouvelle tentative peut entraîner davantage d'erreurs.

Prenons l'exemple d'un scénario dans lequel une opération de longue durée fhirStores.import se termine par des erreurs. car certaines des ressources FHIR qu'il a tenté d'importer n'étaient pas valides. Une nouvelle tentative automatique d'importation avec les mêmes données risque a généré de nombreuses erreurs 409 ALREADY_EXISTS, car certaines ressources FHIR ont été importées dans l'opération d'origine. Si vous interrogez une opération de longue durée créer une opération, ne pas réessayer automatiquement. Un humain doit examiner les erreurs 409 ALREADY_EXISTS.

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

Relancer une opération de longue durée

Si vous disposez d'un pipeline de traitement côté client qui détecte l'opération de longue durée des erreurs de configuration, n'utilisez pas Cloud Logging. Comme indiqué dans Informations sur les erreurs de longue durée, les journaux d'erreurs Cloud Logging pour les opérations de longue durée ne sont pas fiables et incomplets. Utilisez le 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 à ses données sources dans Cloud Storage. Vous pouvez importer des données à l'aide des méthodes suivantes :

• projects.locations.datasets.fhirStores.import
• projects.locations.datasets.dicomStores.import
• projects.locations.datasets.hl7V2Stores.import

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

Consultez la section Effets d'une nouvelle tentative d'exécution d'une opération de longue durée pour connaître les étapes à suivre une nouvelle tentative d'importation.

La réexécution d'une importation peut recréer des ressources que vous avez précédemment supprimées. Envisagez d'utiliser le scénario suivant:

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

Réessayer d'exporter les opérations

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 à l'aide des méthodes suivantes:

• projects.locations.datasets.fhirStores.export
• projects.locations.datasets.dicomStores.export
• projects.locations.datasets.hl7V2Stores.export

Mettre en file d'attente et gérer des opérations de longue durée

Si vous exécutez des opérations de longue durée qui traitent de grands volumes de données pour l'intégration ou de façon régulière implémentez les techniques de mise en file d'attente de LRO suivantes:

• Limitez les opérations de longue durée simultanées à un petit nombre, par exemple 5. Vous pouvez ajuster cette limite en fonction de la taille et des types les opérations de longue durée que vous exécutez.
• Surveiller l'exécution de l'opération de longue durée En cas d'erreurs, reprogrammez l'opération de longue durée ou corrigez les séparément dans votre pipeline de traitement.

• Corrigez automatiquement les erreurs sur la page Gérer les erreurs de ressources. dans la mesure du possible.

  • Comprendre le cas d'utilisation des importations FHIR pour déterminer s'il faut ignorer les erreurs 409 ALREADY_EXISTS ou effectuer une opération CRUD distincte pour résoudre les erreurs. Comme indiqué dans Informations sur les erreurs de longue durée, certaines erreurs 409 ALREADY_EXISTS peuvent ne pas être consignées dans Cloud Logging. Si votre application repose sur des journaux d'erreurs, utilisez l'une des techniques Relancez une opération de longue durée.

  • Pour résoudre quelques erreurs, mettez en file d'attente une LRO plus petite pour les données ayant généré 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. Consultez la section Relancer les opérations d'importation. des risques liés à la réexécution d'une importation sur des données supprimées.

• Détectez automatiquement si une intervention humaine est nécessaire pour résoudre les erreurs. Vous devez disposer d'outils et de playbooks opérationnels pour vous aider les administrateurs système. Les tâches permettant de résoudre les erreurs peuvent inclure les éléments suivants:

  • Reprogrammer une opération de longue durée.
  • Replanifier un sous-ensemble de données d'une opération de longue durée précédente
  • Examiner les erreurs et les corriger des éléments de données qui ont rencontré des erreurs. Cette tâche n'est possible que si vous pouvez déterminer que toutes les erreurs de l'opération de longue durée ont été consignées.

• Déterminer les planifications de LRO Vous pouvez planifier les opérations de longue durée pour éviter de les exécuter aux heures de pointe, lorsque de nombreuses opérations CRUD sont en cours. Pour 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 nouveau plusieurs fois sans succès, alors qu'elles ne sont configurées que pour un nombre limité de tentatives.
• Problèmes nécessitant une intervention humaine pour résoudre un sous-ensemble d'erreurs. Par exemple, si une opération de longue durée échoue et que le client ne peut 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 de récupération de données.
• Les files d'attente dépassent une longueur ou s'allongent trop rapidement.
• Non-respect du règlement (par exemple, un problème d'autorisation ou une mauvaise configuration.
• Vérifications de cohérence qui montrent les problèmes systémiques sur plusieurs opérations de longue durée. Il se peut que plusieurs Les opérations de longue durée d'anonymisation qui attendent les ensembles de données source et de destination d'avoir le même nombre de ressources FHIR. En cas d'écart qui augmente au fil du temps, cela peut indiquer que des données non traitées.
• Problèmes de quota de longue durée. 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.