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. # `opération $bulk-member-match` pour HealthLake AWS HealthLake prend en charge l'`$bulk-member-match`opération de traitement asynchrone des demandes de correspondance de plusieurs membres. Cette opération permet aux établissements de santé de faire correspondre efficacement les identifiants uniques de centaines de membres dans différents systèmes de santé en utilisant des informations démographiques et de couverture dans une seule demande groupée. [Cette capacité est essentielle pour l'échange de données de payeur à payeur à grande échelle, les transitions de membres et les exigences de conformité du CMS et est conforme à la spécification FHIR.](https://build.fhir.org/ig/HL7/davinci-epdx/OperationDefinition-BulkMemberMatch.html) **Note** L'`$bulk-member-match`opération est basée sur une spécification FHIR sous-jacente qui est actuellement expérimentale et sujette à modification. Au fur et à mesure de l'évolution des spécifications, le comportement et l'interface de cette API seront mis à jour en conséquence. Il est conseillé aux développeurs de surveiller les notes de HealthLake publication d'AWS et les mises à jour pertinentes des spécifications FHIR afin de rester informés de toute modification susceptible d'avoir un impact sur leurs intégrations. Cette opération est particulièrement utile lorsque vous devez : + Procédez au jumelage des membres à grande échelle pendant les périodes d'inscription ouvertes + Faciliter les transitions de membres en masse entre les payeurs + Support des exigences d'échange de données de conformité des CMS à grande échelle + Associez efficacement les cohortes de membres à travers les réseaux de santé + Minimisez les appels d'API et améliorez l'efficacité opérationnelle pour les scénarios de mise en correspondance de volumes élevés ## Usage L'`$bulk-member-match`opération est une opération asynchrone invoquée sur les ressources du groupe à l'aide de la méthode POST : ``` POST [base]/Group/$bulk-member-match ``` Après avoir soumis une demande de correspondance groupée, vous pouvez consulter le statut du poste en utilisant : ``` GET [base]/$bulk-member-match-status/{jobId} ``` ## Paramètres pris en charge HealthLake prend en charge les `$bulk-member-match` paramètres FHIR suivants : | Paramètre | Type | Obligatoire | Description | | --- | --- | --- | --- | | `MemberPatient` | Patient | Oui | Ressource destinée aux patients contenant des informations démographiques pour le membre à jumeler. | | `CoverageToMatch` | Couverture | Oui | Ressource de couverture qui sera utilisée pour la comparaison avec les enregistrements existants. | | `CoverageToLink` | Couverture | Non | Ressource de couverture à associer pendant le processus de mise en correspondance. | | `Consent` | Consentement | Oui | La ressource de consentement à des fins d'autorisation est également stockée. Cela est différent de l'`$member-match`opération individuelle pour laquelle le consentement *n'est pas* requis. | ## Demande POST pour soumettre en masse un job correspondant à un nombre de membres L'exemple suivant montre une demande POST visant à soumettre un job de mise en relation groupé de membres. Chaque membre est encapsulé dans un `MemberBundle` paramètre contenant les `Consent` ressources requises `MemberPatient``CoverageToMatch`, ainsi qu'un paramètre facultatif`CoverageToLink`. ``` POST [base]/Group/$bulk-member-match Content-Type: application/fhir+json { "resourceType": "Parameters", "parameter": [ { "name": "MemberBundle", "part": [ { "name": "MemberPatient", "resource": { "resourceType": "Patient", "identifier": [ { "system": "http://example.org/patient-id", "value": "patient-0" } ], "name": [ { "family": "Smith", "given": ["James"] } ], "gender": "male", "birthDate": "1950-01-01" } }, { "name": "CoverageToMatch", "resource": { "resourceType": "Coverage", "status": "active", "identifier": [ { "system": "http://example.org/coverage-id", "value": "cov-0" } ], "subscriberId": "sub-0", "beneficiary": { "reference": "Patient/patient123" }, "relationship": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship", "code": "self" } ] }, "payor": [ { "reference": "Organization/org123" } ] } }, { "name": "Consent", "resource": { "resourceType": "Consent", "status": "active", "scope": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/consentscope", "code": "patient-privacy" } ] }, "category": [ { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "IDSCL" } ] } ], "patient": { "reference": "Patient/patient123" }, "performer": [ { "reference": "Patient/patient123" } ], "sourceReference": { "reference": "http://example.org/DocumentReference/consent-source" }, "policy": [ { "uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#regular" } ], "provision": { "type": "permit", "period": { "start": "2024-01-01", "end": "2025-12-31" }, "actor": [ { "role": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type", "code": "performer" } ] }, "reference": { "identifier": { "system": "http://hl7.org/fhir/sid/us-npi", "value": "9876543210" }, "display": "Old Health Plan" } }, { "role": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType", "code": "IRCP" } ] }, "reference": { "identifier": { "system": "http://hl7.org/fhir/sid/us-npi", "value": "0123456789" }, "display": "New Health Plan" } } ], "action": [ { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/consentaction", "code": "disclose" } ] } ] } } }, { "name": "CoverageToLink", "resource": { "resourceType": "Coverage", "status": "active", "identifier": [ { "system": "http://example.org/coverage-link-id", "value": "cov-link-0" } ], "subscriberId": "new-sub-0", "beneficiary": { "reference": "Patient/patient123" }, "relationship": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship", "code": "self" } ] }, "payor": [ { "identifier": { "system": "http://hl7.org/fhir/sid/us-npi", "value": "0123456789" }, "display": "New Health Plan" } ] } } ] } ] } ``` ## Réponse à la tâche terminée avec sortie Lorsque la tâche est terminée, la réponse inclut les métadonnées de la tâche et une ressource de paramètres FHIR contenant trois ressources de groupe qui catégorisent les résultats du match. ``` { "datastoreId": "datastoreId", "jobId": "jobId", "status": "COMPLETED", "submittedTime": "2026-03-20T18:45:26.321Z", "numberOfMembers": 3, "numberOfMembersProcessedSuccessfully": 3, "numberOfMembersWithCustomerError": 0, "numberOfMembersWithServerError": 0, "output": { "resourceType": "Parameters", "meta": { "profile": [ "http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/pdex-parameters-multi-member-match-bundle-out" ] }, "parameter": [ { "name": "MatchedMembers", "resource": { "resourceType": "Group", "id": "group1", "text": { "status": "generated", "div": "
Matched members group
" }, "contained": [ { "resourceType": "Patient", "id": "1", "identifier": [ { "system": "http://example.org/patient-id", "value": "patient-0" } ], "name": [ { "family": "Smith", "given": ["James"] } ], "gender": "male", "birthDate": "1950-01-01" } ], "type": "person", "actual": true, "code": { "coding": [ { "system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS", "code": "match", "display": "Matched" } ] }, "quantity": 1, "member": [ { "entity": { "extension": [ { "url": "http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters", "valueReference": { "reference": "#1" } } ], "reference": "Patient/patient123" } } ] } }, { "name": "NonMatchedMembers", "resource": { "resourceType": "Group", "id": "Group2", "text": { "status": "generated", "div": "
Non-matched members group
" }, "contained": [ { "resourceType": "Patient", "id": "1", "identifier": [ { "system": "http://example.org/patient-id", "value": "patient-501" } ], "name": [ { "family": "Carter", "given": ["Emily"] } ], "gender": "female", "birthDate": "1985-06-15" } ], "type": "person", "actual": true, "code": { "coding": [ { "system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS", "code": "nomatch", "display": "Not Matched" } ] }, "quantity": 1, "member": [ { "entity": { "extension": [ { "url": "http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters", "valueReference": { "reference": "#1" } } ], "reference": "Patient/patient123" } } ] } }, { "name": "ConsentConstrainedMembers", "resource": { "resourceType": "Group", "id": "group3", "text": { "status": "generated", "div": "
Consent constrained members group
" }, "contained": [ { "resourceType": "Patient", "id": "1", "identifier": [ { "system": "http://example.org/patient-id", "value": "patient-502" } ], "name": [ { "family": "Nguyen", "given": ["David"] } ], "gender": "male", "birthDate": "1972-11-22" } ], "type": "person", "actual": true, "code": { "coding": [ { "system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS", "code": "consentconstraint", "display": "Consent Constraint" } ] }, "quantity": 1, "member": [ { "entity": { "extension": [ { "url": "http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters", "valueReference": { "reference": "#1" } } ], "reference": "Patient/123" } } ] } } ] } } ``` ## Comment HealthLake classifie les membres en groupes de sortie Chaque membre soumis dans une `$bulk-member-match` demande est évalué par le biais d'un pipeline séquentiel. Le résultat de chaque étape détermine le groupe de sortie dans lequel le membre est placé. 1. **Validation structurale** — MemberBundle Sont-ils conformes aux profils requis ? En cas d'échec : erreur (dans aucun groupe). 1. **Correspondance des patients** — Est-il possible de HealthLake trouver des patients correspondant aux données démographiques soumises ? En cas de panne : NonMatchedMembers. 1. **Confirmation de couverture** — Est-il possible de se HealthLake limiter à un seul patient valide CoverageToMatch ? En cas de panne : NonMatchedMembers. 1. **Évaluation du consentement** — Le consentement soumis est-il honorable en ce moment ? (statut = actif, la période couvre la date actuelle, l'interprète peut être validé). En cas de panne : ConsentConstrainedMembers. 1. **Succès** — Tous les chèques sont réussis. Consentement stocké dans une banque de données. Membre inscrit MatchedMembers. **Principe de base :** un membre ne peut apparaître que dans une seule destination. La première étape défaillante détermine le placement. Les membres qui échouent aux étapes 2 ou 3 ne sont jamais inclus. Ce groupe est exclusivement réservé aux membres qui ont réussi le jumelage mais dont le consentement ne peut être honoré. ConsentConstrainedMembers **Détails de l'évaluation du consentement (étape 4) :** + **Contrôle 1 — État du consentement :** est-il `Consent.status` égal à « actif » ? Sinon → ConsentConstrainedMembers. + **Contrôle 2 — Période de mise à disposition :** `provision.period` couvre la date actuelle ? Si la date actuelle est antérieure `period.start` ou postérieure `period.end` → ConsentConstrainedMembers. + **Contrôle 3 — Validation du performeur :** la `Consent.performer` référence peut-elle être validée ? Si la ressource référencée ne se trouve pas dans la banque de données ou n'est pas associée au patient correspondant → ConsentConstrainedMembers. Toutes les vérifications doivent être passées pour que le membre soit inscrit MatchedMembers et pour que le consentement soit conservé. ## Comportement de correspondance de couverture Lors de la mise en correspondance des membres, seule la validation `CoverageToMatch` est effectuée par rapport à la banque de données du payeur répondant. `CoverageToLink`appartient au new/requesting payeur et *n'est pas* validé par rapport à la banque de données de l'ancien payeur. L'inclusion `CoverageToLink` dans la demande n'affectera pas les résultats correspondants. Chaque combinaison patient\+couverture figurant dans la demande est traitée indépendamment. Le même patient peut être soumis plusieurs fois avec différents plans de couverture, et chaque inscription reçoit son propre résultat en fonction de sa couverture spécifique. ## Gestion des références aux exécutants du consentement Le nouveau payeur peut envoyer une référence de patient temporaire ou locale `Consent.performer` (par exemple, la même référence utilisée dans`Consent.patient`). HealthLake résout automatiquement ces références : + S'il `Consent.performer` contient la même référence locale que`Consent.patient`, il la HealthLake remplace par la référence réelle du patient correspondant une fois l'appariement réussi. + HealthLake prend en charge les références d'intervenants de type Patient RelatedPerson PractitionerRole, Practitioner et Organization (références directes et références d'identification logiques). + Si la validation de l'intervenant échoue (ressource introuvable ou non associée au patient correspondant), le membre est intégré au ConsentConstrainedMembers lieu de renvoyer une erreur. ## Ressources du groupe de sortie La tâche terminée renvoie une ressource Parameters contenant trois ressources de groupe : **MatchedMembers Groupe** Contient les références des patients pour tous les membres correspondants dont le consentement est actif et valide au moment de la demande. La ressource Consent est créée et stockée dans la banque de données pour chaque membre correspondant. Ce groupe est instancié dans la banque de données et peut être utilisé directement avec. `$davinci-data-export` **NonMatchedMembers Groupe** Contient des références à des membres pour lesquels aucune correspondance unique n'a été trouvée. Un membre est placé ici lorsqu'aucun patient de la banque de données ne correspond aux données démographiques fournies, qu'il n'existe aucune couverture valide pour un patient candidat correspondant, ou lorsque plusieurs patients correspondent aux données démographiques et que plusieurs d'entre eux ont une couverture valide (ambigu). **ConsentConstrainedMembers Groupe** Contient des références de patients pour les membres qui ont été jumelés avec succès (données démographiques et couverture confirmées) mais dont le consentement ne peut être honoré au moment de la demande. La ressource de consentement *n'est pas* stockée pour les membres soumis à des contraintes de consentement. L'identité du membre correspondant (MemberIdentifier et MemberId) est toujours incluse afin que le payeur demandeur sache qui a été contraint. Le `Group.quantity` champ contient le nombre total de membres dans chacun de leurs groupes respectifs. **Références des membres du groupe :** + `Group.member.entity.reference`— Pour MatchedMembers et ConsentConstrainedMembers, contient l'identifiant patient du membre correspondant dans le système du payeur répondant. Pour NonMatchedMembers, fait référence à l'entrée Patient contenue. + `Group.member.entity.extension (base-ext-match-parameters)`— Contient l'identifiant du patient issu de la demande d'entrée initiale (l'identifiant soumis par le payeur demandeur`Patient.id`, dérivé de`Coverage.beneficiary.reference`, ou`Consent.patient.reference`). ## Consent-Patient lien **Important** La ressource de consentement stockée conserve la référence du patient exactement telle qu'elle a été soumise par le payeur demandeur. HealthLake ne met pas automatiquement à jour le champ patient du consentement pour qu'il pointe vers le patient correspondant dans la banque de données réceptrice. Pour lier un consentement enregistré au patient correspondant, utilisez le résultat de la tâche : chaque membre du MatchedMembers groupe `member.entity.reference` pointe vers le patient correspondant et un `member.entity.extension` (`base-ext-match-parameters`) pointant vers le patient saisi contenu. Cross-reference ceux-ci avec le champ patient du consentement pour créer le mappage dans votre couche d'application. ## Ce qui est stocké par rapport à ce qui est transitoire Le tableau suivant décrit ce qui est HealthLake conservé dans la banque de données pendant le `$bulk-member-match` traitement et ce qui n'existe que dans la réponse à la tâche : | Ressource | Stocké ? | Interrogable via REST ? | Remarques | | --- | --- | --- | --- | | MemberPatient (entrée) | Non | Non | Utilisé uniquement pour la mise en correspondance ; non persistant | | CoverageToMatch (entrée) | Non | Non | Utilisé uniquement pour confirmer la couverture | | CoverageToLink (entrée) | Non | Non | Non validé par rapport à la banque de données ; appartient au nouveau payeur | | **Consentement (membres correspondants)** | **Oui** | Oui — GET [base] /Consent/ {id} | Stocké tel qu'il a été reçu du payeur demandeur | | Consentement (membres limités) | Non | Non | Non stocké. L'identité du membre est toujours incluse dans la réponse. | | **MatchedMembers Groupe (sortie)** | **Oui** | Oui — GET [base] /Group/ {id} | Instancié ; utilisable avec $davinci-data-export | | NonMatchedMembers Groupe | Non | Non | Réponse au job uniquement | | ConsentConstrainedMembers Groupe | Non | Non | Réponse au job uniquement | ## Intégration avec $davinci-data-export La ressource de MatchedMembers groupe renvoyée par `$bulk-member-match` peut être directement utilisée avec l'`$davinci-data-export`opération de récupération des données des membres en masse : ``` POST [base]/Group/{matched-group-id}/$davinci-data-export GET [base]/Group/{matched-group-id} ``` Cette intégration permet des flux de travail efficaces dans lesquels vous identifiez d'abord les membres correspondants en masse, puis exportez leurs dossiers médicaux complets à l'aide de la ressource de groupe qui en résulte. ### Utiliser $member-remove avant l'exportation Si vous devez exclure des membres spécifiques de l'exportation après le rapprochement (par exemple, un membre révoque son consentement entre le rapprochement et l'exportation), utilisez-le `$member-remove` sur le MatchedMembers groupe. **Important** La suppression d'un membre `$member-remove` marque le membre comme inactif dans le groupe, mais exclut `$davinci-data-export` uniquement les membres inactifs une fois que le groupe est passé au statut « final ». Si vous faites appel `$davinci-data-export` à un groupe qui possède toujours le statut par défaut, les membres supprimés peuvent toujours apparaître dans les résultats d'exportation. Flux de travail : 1. `POST [base]/Group/{id}/$member-remove`— marque les membres comme inactifs 1. `PUT [base]/Group/{id}`— mettre à jour le statut du groupe à « final » 1. `POST [base]/Group/{id}/$davinci-data-export`— l'export exclut désormais les membres supprimés ## Caractéristiques de performance L'`$bulk-member-match`opération est conçue pour le traitement de gros volumes et s'exécute de manière asynchrone : + **Simultanéité** : maximum de 5 opérations simultanées par magasin de données. + **Évolutivité** : gère jusqu'à 500 membres par demande (limite de charge utile de 5 Mo). + **Opérations parallèles** : compatible avec les opérations simultanées d'importation, d'exportation ou de suppression en bloc. ## Autorisation L'API utilise le protocole d'autorisation SMART on FHIR avec les étendues requises suivantes : + `system/Patient.read`— Nécessaire pour rechercher et associer les ressources destinées aux patients. + `system/Coverage.read`— Nécessaire pour valider les informations de couverture. + `system/Group.write`— Nécessaire pour créer des ressources de groupe de résultats. + `system/Organization.read`— Conditionnel, obligatoire si la couverture fait référence à des organisations. + `system/Practitioner.read`— Conditionnel, obligatoire si la couverture fait référence à des praticiens. + `system/PractitionerRole.read`— Conditionnel, obligatoire si la couverture fait référence aux rôles des praticiens. + `system/Consent.write`— Conditionnel, obligatoire si des ressources de consentement sont fournies. L'opération prend également en charge AWS l'autorisation IAM Signature Version 4 (SigV4) pour l'accès programmatique. ## Règles de validation Les règles de validation suivantes sont appliquées à chacune MemberBundle à l'étape 1. Les membres dont la validation échoue sont signalés comme des erreurs et n'apparaissent dans aucun groupe de sortie. ### MemberPatient | Champ | Comment HealthLake l'utilise | Échec de validation si... | | --- | --- | --- | | `name.family` | Recherche démographique | Manquant | | `name.given` | Recherche démographique | Manquant (au moins un élément requis) | | `birthDate` | Recherche démographique | Manquant | | `gender` | Recherche démographique ; en cas d'absence, extension Birth Sex utilisée | Ni sexe ni sexe de naissance présents (hrex-pat-1) | | `identifier` | Inclus dans la recherche lorsqu'il est présent ; améliore la confiance | Ne cause jamais de panne (facultatif) | ### CoverageToMatch / CoverageToLink | Champ | Comment HealthLake l'utilise | Échec de validation si... | | --- | --- | --- | | `status` | Confirme que la couverture est exploitable | Manquant | | `beneficiary` | Associe la couverture à un patient candidat | Manquant | | `payor` | Homonymie lorsqu'il existe plusieurs candidats | Absent ou plus d'un payeur | | `relationship` | Confirme la relation abonné-bénéficiaire | Manquant | | `identifier (MB) or subscriberId` | Clé de désambiguïsation principale | Aucun des deux | ### Consentement | Champ | Comment HealthLake l'utilise | Échec de validation si... | | --- | --- | --- | | `scope` | Confirme que la portée du consentement est axée sur la confidentialité des patients | Code de confidentialité des patients manquant ou inexistant | | `category` | Confirme la classification des informations | Manquant | | `patient` | Identifie le sujet du consentement | Manquant | | `performer` | Identifie qui est d'accord | Manquant | | `sourceReference` | Documente la source du consentement | Manquant | | `policy.uri` | Détermine l'étendue du partage de données | URI manquant ou ne se terminant pas par \#regular ou \#sensitive | | `provision.type` | Doit être un « permis » selon le profil de consentement HRex | « Permis » manquant ou non (y compris « refus ») | | `provision.period` | Évalué à l'étape 4 pour une vérification sous réserve de consentement | Manquant ou non start/end | | `status` | Évalué à l'étape 4 (PAS à l'étape 1) | Ne cause jamais d'échec à l'étape 1 : HealthLake accepte tout statut valide et évalue à l'étape 4 | **Note** Le profil de consentement HRex définit le statut avec une valeur fixe de « actif ». HealthLake assouplit intentionnellement cette contrainte afin qu'un consentement non actif reçoive une classification significative (ConsentConstrainedMembers) plutôt qu'un rejet de validation général. ## Comportement correspondant + **Recherche d'un patient (étape 2)** : HealthLake recherche en utilisant `name.family` \+ `name.given` (exact, sans distinction `birthDate` majuscules/majuscules), `gender` (exact ; sexe de naissance utilisé en l'absence de sexe) et `identifier` (le cas échéant, facultatif). + **Désambiguïsation de la couverture (étape 3)** — Lorsque plusieurs patients candidats sont trouvés, elle `CoverageToMatch` est utilisée pour se limiter à un seul. Une couverture est « valide » lorsqu'une ressource de couverture active existe dans la banque de données correspondant à `subscriberId` ou `identifier` (type MB) ET`payor`. + **Évaluation du consentement (étape 4)** — Effectuée uniquement après une correspondance unique réussie. Consultez la section sur les détails de l'évaluation du consentement ci-dessus. ## Gestion des erreurs L'opération gère les conditions d'erreur suivantes : + **400 Mauvaise demande** : format de demande non valide, paramètres requis manquants ou charge utile supérieure aux limites de taille (500 membres ou 5 Mo). + **422 Entité intraitable** : erreurs de traitement lors de l'exécution de la tâche. + **Erreurs relatives à un membre individuel** : lorsqu'un membre en particulier échoue, l'opération se poursuit avec les membres restants et inclut les détails de l'erreur dans le NonMatchedMembers groupe avec les codes de motif appropriés. Par exemple, un `MemberBundle` Patient dont le `birthDate` paramètre est absent renverra le message d'erreur suivant : ``` "errors": [ { "memberIndex": 1, "jsonBlob": { "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "invalid", "diagnostics": "MemberPatient.birthDate is required" } ], "statusCode": 400 } } ] ``` Les détails de l'erreur sont disponibles via le point de terminaison du sondage d'état et incluent : + `numberOfMembersWithCustomerError`: Nombre de membres présentant des erreurs de validation ou de saisie. + `numberOfMembersWithServerError`: nombre de membres présentant des erreurs de traitement côté serveur. ## Opérations liées + [`$member-match`opération pour HealthLake](reference-fhir-operations-member-match.md)— Opération de mise en correspondance de membres individuels. + [Fonctionnement du FHIR R4 `$davinci-data-export` pour HealthLake](reference-fhir-operations-davinci-data-export.md)— Exportation de données en masse à l'aide des ressources du groupe. + [FHIR R4 pour `$operations` HealthLake](reference-fhir-operations.md)— Liste complète des opérations prises en charge.