$bulk-member-matchoperazione per HealthLake - AWS HealthLake
UtilizzoParametri supportatiRichiesta POST per inviare in blocco un'offerta di lavoro abbinata a un membroRisposta al lavoro completata con outputRisorse di Output GroupIntegrazione con $ davinci-data-exportCaratteristiche prestazionaliAutorizzazioneGestione degli erroriOperazioni correlate

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

$bulk-member-matchoperazione per HealthLake

AWS HealthLake supporta l'$bulk-member-matchoperazione per l'elaborazione asincrona delle richieste di abbinamento di più membri. Questa operazione consente alle organizzazioni sanitarie di abbinare in modo efficiente gli identificatori univoci di centinaia di membri di diversi sistemi sanitari utilizzando informazioni demografiche e di copertura in un'unica richiesta di massa. Questa funzionalità è essenziale per lo scambio di payer-to-payer dati su larga scala, le transizioni tra i membri e i requisiti di conformità CMS e segue le specifiche FHIR.

Nota

L'$bulk-member-matchoperazione si basa su una specifica FHIR sottostante che è attualmente sperimentale e soggetta a modifiche. Man mano che le specifiche si evolvono, il comportamento e l'interfaccia di questa API verranno aggiornati di conseguenza. Si consiglia agli sviluppatori di monitorare le note di HealthLake rilascio di AWS e gli aggiornamenti delle specifiche FHIR pertinenti per rimanere informati su eventuali modifiche che potrebbero influire sulle loro integrazioni.

Questa operazione è particolarmente utile quando è necessario:

  • Elaborare l'abbinamento dei membri su larga scala durante i periodi di iscrizione aperti

  • Facilita le transizioni di massa dei membri tra i paganti

  • Supporta i requisiti di scambio di dati di conformità CMS su larga scala

  • Abbina in modo efficiente le coorti di membri attraverso le reti sanitarie

  • Riduci al minimo le chiamate API e migliora l'efficienza operativa per scenari di abbinamento ad alto volume

Utilizzo

L'$bulk-member-matchoperazione è un'operazione asincrona richiamata sulle risorse del gruppo utilizzando il metodo POST:

POST [base]/Group/$bulk-member-match

Dopo aver inviato una richiesta di corrispondenza in blocco, puoi verificare lo stato del lavoro utilizzando:

GET [base]/$bulk-member-match-status/{jobId}

Parametri supportati

HealthLake supporta i seguenti parametri FHIR: $bulk-member-match

Parametro Tipo Campo obbligatorio Description

MemberPatient

Paziente

Sì

Risorsa per il paziente contenente informazioni demografiche relative al membro da abbinare.

CoverageToMatch

Copertura

Sì

Risorsa di copertura che verrà utilizzata per il confronto con i record esistenti.

CoverageToLink

Copertura

No

Risorsa di copertura da collegare durante il processo di abbinamento.

Consent

Consenso

Sì

Viene inoltre memorizzata la risorsa di consenso a fini di autorizzazione. Questa operazione è diversa dalla singola $member-match operazione in cui non è richiesto il consenso.

Richiesta POST per inviare in blocco un'offerta di lavoro abbinata a un membro

L'esempio seguente mostra una richiesta POST per inviare un lavoro collettivo riservato ai membri. Ogni membro è racchiuso in un MemberBundle parametro contenente le risorse obbligatorie e Consent le risorse MemberPatientCoverageToMatch, oltre a un parametro opzionale. 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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Risposta al lavoro completata con output

Una volta completato il lavoro, la risposta include i metadati del lavoro e una risorsa FHIR Parameters contenente tre risorse di gruppo che classificano i risultati delle partite.

{
  "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": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Matched members group</div>"
          },
          "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": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Non-matched members group</div>"
          },
          "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": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Consent constrained members group</div>"
          },
          "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"
              }
            }
          ]
        }
      }
    ]
  }
}

Risorse di Output Group

Il lavoro completato restituisce una risorsa Parameters contenente tre risorse di gruppo:

MatchedMembers Group (Gruppo)

Contiene i riferimenti dei pazienti per tutti i membri abbinati correttamente e non è classificato come vincolo di consenso.

Il Group.quantity campo contiene il numero totale di membri in ciascuno dei rispettivi gruppi.

NonMatchedMembers Group (Gruppo)

Contiene riferimenti ai membri per i quali non è stata trovata alcuna corrispondenza o sono state identificate più corrispondenze.

ConsentConstrainedMembers Group (Gruppo)

Contiene i riferimenti dei pazienti per tutti i membri abbinati correttamente, laddove i vincoli di consenso impediscano la condivisione dei dati. Una risorsa di consenso è considerata limitata quando sono presenti entrambe le seguenti condizioni:

  • L'URI della policy termina con #sensitive: questo è il segnale più chiaro e diretto. Il pagante richiedente dice esplicitamente: «I dati di questo utente sono sensibili, trattali con cura».

    "policy": [{ "uri": "...hrex-consent.html#sensitive" }]

  • Il tipo di fornitura di primo livello è deny: il membro ha ampiamente rifiutato la condivisione dei dati.

    "provision": { "type": "deny" }

Integrazione con $ davinci-data-export

La risorsa di MatchedMembers gruppo restituita da $bulk-member-match può essere utilizzata direttamente con l'$davinci-data-exportoperazione per recuperare i dati di massa dei membri:

POST [base]/Group/{matched-group-id}/$davinci-data-export
GET [base]/Group/{matched-group-id}

Questa integrazione consente flussi di lavoro efficienti in cui si identificano innanzitutto i membri corrispondenti in blocco, quindi si esportano le relative cartelle cliniche complete utilizzando la risorsa di Gruppo risultante.

Caratteristiche prestazionali

L'$bulk-member-matchoperazione è progettata per l'elaborazione di grandi volumi e viene eseguita in modo asincrono:

  • Concorrenza: massimo 5 operazioni simultanee per archivio dati.

  • Scalabilità: gestisce fino a 500 membri per richiesta (limite di payload di 5 MB).

  • Operazioni parallele: compatibile con operazioni simultanee di importazione, esportazione o eliminazione in blocco.

Autorizzazione

L'API utilizza il protocollo di autorizzazione SMART on FHIR con i seguenti ambiti richiesti:

  • system/Patient.read— Necessario per cercare e abbinare le risorse dei pazienti.

  • system/Coverage.read— Necessario per convalidare le informazioni sulla copertura.

  • system/Group.write— Necessario per creare risorse del Gruppo di risultati.

  • system/Organization.read— Condizionale, obbligatorio se la copertura si riferisce alle organizzazioni.

  • system/Practitioner.read— Condizionale, obbligatorio se la copertura si riferisce ai professionisti.

  • system/PractitionerRole.read— Condizionale, obbligatorio se la copertura si riferisce ai ruoli dei professionisti.

  • system/Consent.write— Condizionale, obbligatorio se vengono fornite risorse per il consenso.

L'operazione supporta anche l'autorizzazione AWS IAM Signature Version 4 (SigV4) per l'accesso programmatico.

Gestione degli errori

L'operazione gestisce le seguenti condizioni di errore:

  • 400 Richiesta errata: formato di richiesta non valido, parametri obbligatori mancanti o il payload supera i limiti di dimensione (500 membri o 5 MB).

  • 422 Entità non processabile: errori di elaborazione durante l'esecuzione del lavoro.

  • Errori individuali dei membri: quando un membro specifico non viene elaborato, l'operazione continua con i membri rimanenti e include i dettagli dell'errore nel NonMatchedMembers Gruppo con i codici motivo appropriati. Ad esempio, se MemberBundle a un paziente manca il birthDate parametro, verrà restituito il seguente errore:

    "errors": [
  {
    "memberIndex": 1,
    "jsonBlob": {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "invalid",
          "diagnostics": "MemberPatient.birthDate is required"
        }
      ],
      "statusCode": 400
    }
  }
]

I dettagli sull'errore sono disponibili tramite l'endpoint di polling dello stato e includono:

  • numberOfMembersWithCustomerError: Numero di membri con errori di convalida o di input.

  • numberOfMembersWithServerError: Numero di membri con errori di elaborazione sul lato server.