View a markdown version of this page

Corriger les ressources à grande échelle avec $bulk-patch - AWS HealthLake
UsageParametersCiblage des ressourcesFormats de correctifs pris en chargeExemple de tâche de lancement de correctifs en masseSondage groupé sur l'état des tâches liéesRaisons fréquemment ignoréesDéfaillances courantes des clientsBonnes pratiquesAutorisationCaractéristiques de performanceOpérations liées

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Corriger les ressources à grande échelle avec $bulk-patch

AWS HealthLake prend en charge l'$bulk-patchopération d'application d'opérations de correctif à un grand nombre de ressources FHIR de manière asynchrone. Vous pouvez cibler une liste spécifique de ressources par ID, ou toutes les ressources d'un type donné dans une banque de données. Cette opération vous permet de modifier les ressources à grande échelle sans mettre à jour chaque ressource individuellement.

L'$bulk-patchopération est particulièrement utile lorsque vous devez effectuer les opérations suivantes :

  • Appliquer des balises ou des étiquettes de métadonnées aux ressources d'une banque de données complète

  • Mettre à jour des champs spécifiques sur des milliers ou des millions de ressources

  • Procéder à des corrections ou à des enrichissements de données en masse

  • Appliquez les modifications liées à la conformité à tous les types de ressources

  • Migrez ou standardisez des éléments de données à grande échelle

Note

  • L'$bulk-patchopération applique le même correctif à chaque ressource ciblée. Pour modifier une ressource individuelle, utilisez l'opération PATCH. Pour de plus amples informations, veuillez consulter Modification des ressources à l'aide de l'opération PATCH.

  • Bulk Patch applique chaque correctif de manière atomique à chaque ressource. Chaque ressource réussit ou échoue indépendamment.

  • Les ressources qui sont supprimées ou modifiées après la soumission des tâches sont ignorées au lieu d'être corrigées, afin d'éviter de remplacer les modifications simultanées.

Usage

L'$bulk-patchopération est asynchrone. Pour démarrer une tâche, envoyez une demande POST :

POST [base]/$bulk-patch

Pour interroger l'état d'une tâche, utilisez le point de terminaison describe :

GET [base]/$bulk-patch/{jobId}

Pour commencer l'$bulk-patchopération, procédez comme suit :

  1. Soumettez une demande de correctif groupée qui spécifie les ressources cibles et les opérations de correctif. La réponse inclut un identifiant de tâche.

  2. Interrogez le statut de la tâche à l'aide du point de terminaison describe jusqu'à ce que le statut soit COMPLETED ouCOMPLETED_WITH_ERRORS.

  3. Consultez le résumé de la tâche pour voir combien de ressources ont réussi, échoué ou ont été ignorées.

Parameters

L'$bulk-patchopération prend en charge les paramètres suivants.

Paramètre Type Obligatoire Description
resourceType chaîne Oui Type de ressource FHIR à corriger, par exemple Patient ouObservation.
resourceIds chaîne [] Non La liste des ID de ressources à patcher. Lorsque vous omettez ce paramètre, l'opération corrige toutes les ressources du type spécifié.
operations objet Oui Les opérations de correction à appliquer. Accepte un tableau de correctifs JSON ou une Parameters ressource de correctif FHIR.
clientToken chaîne Non User-provided jeton utilisé pour garantir l'idempotence. Le renvoi d'une tâche avec le même jeton client renvoie la tâche existante au lieu d'en créer une nouvelle.
validationLevel chaîne Non Le niveau de validation FHIR appliqué lors de la mise à jour de chaque ressource. Les valeurs acceptées sont strict (par défaut)structure-only, etminimal.

Ciblage des ressources

Vous pouvez cibler les ressources selon deux modes.

Mode type de ressource

En mode type de ressource, l'opération applique des correctifs à toutes les ressources d'un type spécifique dans la banque de données.

{
    "resourceType": "Patient",
    "operations": { ... }
}
Mode ID de ressource

En mode ID de ressource, l'opération corrige une liste spécifique de ressources par ID. Tous les ID de ressources doivent être du même type et correspondre au resourceType paramètre. Le format peut être une référence complète ([resourceType]/[id]) ou uniquement l'ID ([id]). La liste peut contenir jusqu'à 50 000 ID de ressources.

{
    "resourceType": "Patient",
    "resourceIds": ["Patient/001", "Patient/002", "Patient/003"],
    "operations": { ... }
}

Formats de correctifs pris en charge

L'$bulk-patchopération prend en charge les syntaxes JSON Patch (RFC 6902) et FHIR Patch (FHIRPath-based). Elle utilise le même ensemble d'opérations prises en charge et la même syntaxe que l'opération PATCH synchrone. Pour de plus amples informations, veuillez consulter Modification des ressources à l'aide de l'opération PATCH.

Exemple de tâche de lancement de correctifs en masse

L'exemple suivant soumet une tâche de correctif en bloc qui ajoute une balise de conformité à des Patient ressources spécifiques à l'aide de FHIR Patch.

Exemple de requête

POST [base]/$bulk-patch
Content-Type: application/json

{
    "resourceType": "Patient",
    "resourceIds": ["patient-1", "patient-2", "patient-3"],
    "validationLevel": "strict",
    "clientToken": "unique-idempotency-token-123",
    "operations": {
        "resourceType": "Parameters",
        "parameter": [
            {
                "name": "operation",
                "part": [
                    {"name": "type", "valueCode": "add"},
                    {"name": "path", "valueString": "Patient.meta"},
                    {"name": "name", "valueString": "tag"},
                    {"name": "value", "valueCoding": {
                        "system": "http://example.org/compliance",
                        "code": "2026-audit-complete"
                    }}
                ]
            }
        ]
    }
}
Exemple de réponse

{
    "datastoreId": "datastoreId",
    "jobId": "jobId",
    "jobStatus": "SUBMITTED"
}

Sondage groupé sur l'état des tâches liées

Une fois que vous avez soumis une tâche, effectuez un sondage sur son statut pour suivre sa progression et récupérer les résultats. La tâche passe par SUBMITTED etIN_PROGRESS, puis passe à un état terminal de COMPLETED ouCOMPLETED_WITH_ERRORS.

GET [base]/$bulk-patch/{jobId}

L'exemple suivant montre une réponse pour une tâche en cours.

{
    "datastoreId": "datastoreId",
    "jobId": "jobId",
    "status": "IN_PROGRESS",
    "submittedTime": "2026-09-14T06:53:31.429Z",
    "summary": {
        "estimatedResourceCount": 1000
    }
}
Note

La valeur estimatedResourceCount est exacte pour le mode ID de ressource et est égale à la taille de la liste soumise. Pour le mode type de ressource, le nombre réel de ressources traitées peut être légèrement différent car les ressources peuvent être créées ou supprimées pendant l'exécution de la tâche.

Lorsque la tâche atteint l'état terminal, la réponse describe inclut un récapitulatif du nombre de ressources réussies, échouées et ignorées. Si des ressources ont échoué ou ont été ignorées, la réponse répertorie les raisons entre failedResources etskippedResources. L'état de la tâche correspond à tout échec, COMPLETED_WITH_ERRORS qu'il s'agisse d'une erreur du client ou d'une erreur du serveur. La taille des réponses limite les skippedResources listes failedResources et, elles peuvent donc être tronquées. Vérifiez failedResourcesTruncated et skippedResourcesTruncated déterminez si la liste complète est incluse.

{
    "datastoreId": "datastoreId",
    "jobId": "jobId",
    "status": "COMPLETED_WITH_ERRORS",
    "submittedTime": "2026-09-14T06:53:31.429Z",
    "endTime": "2026-09-14T07:08:34.930Z",
    "summary": {
        "estimatedResourceCount": 1000,
        "totalResourcesProcessed": 1000,
        "succeeded": 985,
        "failedWithCustomerError": 5,
        "failedWithServerError": 0,
        "skipped": 10
    },
    "failedResources": [
        {
            "resourceId": "Patient/patient-101",
            "message": "FHIR resource in payload failed FHIR validation rules."
        }
    ],
    "skippedResources": [
        {
            "resourceId": "Patient/patient-201",
            "message": "Resource was modified after job submission"
        },
        {
            "resourceId": "Patient/patient-202",
            "message": "Resource was deleted."
        },
        {
            "resourceId": "Patient/patient-203",
            "message": "Resource not found."
        }
    ],
    "failedResourcesTruncated": false,
    "skippedResourcesTruncated": false
}

Raisons fréquemment ignorées

L'opération ignore une ressource lorsqu'elle est dans sa portée mais ne peut pas corriger la ressource car son état a changé entre la soumission et le traitement de la tâche. Les ressources ignorées ne sont pas considérées comme des erreurs. Les raisons courantes pour lesquelles une ressource est ignorée sont les suivantes.

  • La ressource a été modifiée après la soumission de la tâche  : la ressource a été mise à jour par une autre opération après que la tâche de correction en masse ait capturé sa version au moment de la soumission. Dans de rares cas, une ressource qui a été corrigée avec succès peut être signalée comme ignorée avec la raison modifiée après la soumission de la tâche. Cela est prévisible et pourrait se produire à un rythme très faible (1 ressource sur des millions).

  • La ressource a été supprimée après la soumission de la tâche — La ressource a été supprimée après la soumission de la tâche (mode type de ressource). Il n'est pas garanti que toutes les ressources supprimées apparaissent dans la liste ignorée. Si une ressource est supprimée avant que le traitement de la tâche ne commence, elle est totalement exclue de l'étendue de la tâche et n'est pas reflétée dans les résultats de la tâche.

  • La ressource a été supprimée — L'ID de ressource spécifié est dans un état supprimé (mode ID de ressource).

  • Ressource introuvable — L'ID de ressource spécifié n'existe pas (mode ID de ressource uniquement).

Défaillances courantes des clients

Une ressource échoue lorsque l'opération ne peut pas appliquer le correctif en raison d'un problème lié à la ressource ou aux opérations du correctif. Les ressources défaillantes incluent un message d'erreur contenant des informations de diagnostic. Les défaillances les plus courantes des clients sont les suivantes.

  • Échec de validation FHIR  : la ressource corrigée échoue à la validation FHIR. Bulk Patch applique la validation FHIR à l'ensemble de la ressource patchée, et pas seulement aux champs modifiés. Cet échec peut se produire lorsque le correctif produit une valeur de champ non valide ou lorsque la ressource contient déjà des champs qui ne sont pas conformes à la norme FHIR. Utilisez le validationLevel paramètre pour contrôler la rigueur de la validation.

  • Défaillance de l'application du correctif  : les opérations relatives aux correctifs sont incompatibles avec la structure des ressources, par exemple en cas de remplacement d'un champ qui n'existe pas ou d'ajout à un chemin hors tableau.

Bonnes pratiques

Nous vous recommandons de suivre les bonnes pratiques suivantes lorsque vous utilisez cette $bulk-patch opération.

  • Testez d'abord avec le PATCH synchrone. AWS HealthLake valide la syntaxe des opérations de correction lors de la soumission des tâches et rejette les charges utiles non valides de manière synchrone. Cependant, les opérations de correction syntaxiquement valides peuvent toujours échouer au moment du traitement si elles ne correspondent pas à la structure de ressources stockées sous-jacente. Comprenez les caractéristiques de vos ressources cibles et testez vos opérations de patch à l'aide de l'opération PATCH synchrone avant d'exécuter une tâche de patch en masse. Cela vous permet d'éviter les pannes à grande échelle.

  • Utilisez l'erreur et ignorez les raisons pour déboguer. Consultez les skippedResources listes failedResources et figurant dans la réponse de description pour comprendre pourquoi des ressources spécifiques n'ont pas été corrigées.

  • Vérifiez l'état des ressources avant de réessayer. Les opérations de patch ne sont pas idempotentes par nature. L'application deux fois du même correctif peut produire des résultats différents. Par exemple, l'ajout d'une balise qui existe déjà crée un doublon. Une fois que des ressources ont été ignorées ou ont échoué, vérifiez l'état actuel des ressources avant de soumettre une nouvelle tentative de tâche.

Autorisation

L'$bulk-patchopération prend en charge les méthodes d'autorisation suivantes :

  • AWS Signature Version 4 (SIGv4) de gestion des identités et des accès (IAM) pour l'accès programmatique.

  • SMART sur FHIR avec les champs d'application requis suivants :

    • Niveau de portée  : seules les étendues au niveau du système sont prises en charge. L'opération rejette les scopes au niveau du patient et au niveau de l'utilisateur.

    • Type de ressource  : les étendues doivent correspondre au type de ressource ciblé par la tâche.

    • Opérations — Les étendues requises dépendent du mode de travail et de la version SMART :

      • Démarrer une tâche (mode type de ressource) — SMART v1 nécessite read et définit write les limites. Les banques de données SMART v2 nécessitent search et couvrent. update

      • Démarrer une tâche (mode ID de ressource) — SMART v1 nécessite read et définit write les limites. Les banques de données SMART v2 nécessitent read et couvrent. update

      • Décrivez un poste — Exige la read portée.

Caractéristiques de performance

L'$bulk-patchopération est conçue pour le traitement de gros volumes et s'exécute de manière asynchrone.

  • Simultanéité  : chaque banque de données prend en charge un maximum d'une tâche de correction en masse simultanée. L'opération met en file d'attente des tâches supplémentaires et les démarre automatiquement lorsque la tâche en cours est terminée.

  • Évolutivité  : chaque tâche prend en charge jusqu'à 2 milliards de ressources. L'opération rejette les tâches qui dépassent cette limite. Cette limite permet d'éviter des temps de traitement prolongés, au cours desquels de nombreuses ressources peuvent changer d'état, et évite de suspendre la simultanéité des tâches de la banque de données pendant une période prolongée. Utilisez le mode ID de ressource pour partitionner la charge de travail. Exemple de réponse lorsqu'une tâche dépasse l'échelle prise en charge :

    "status": "COMPLETED_WITH_ERRORS",
"message": "The requested bulk patch operation exceeds the supported scale."

  • Opérations parallèles  : le correctif en masse n'est pas compatible avec les opérations simultanées de suppression, d'importation ou d'exportation en bloc sur la même banque de données.

  • Annulation — Les tâches de mise à jour groupées ne peuvent pas être annulées une fois qu'elles ont été soumises.