As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
operação $bulk-member-match para HealthLake
AWS HealthLake suporta a $bulk-member-match operação de processamento de solicitações de correspondência de vários membros de forma assíncrona. Essa operação permite que as organizações de saúde combinem com eficiência centenas de identificadores exclusivos de membros em diferentes sistemas de saúde usando informações demográficas e de cobertura em uma única solicitação em massa. Esse recurso é essencial para troca de dados de pagador para pagador em grande escala, transições de membros e requisitos de conformidade do CMS e segue a especificação FHIR.
nota
A $bulk-member-match operação é baseada em uma especificação FHIR subjacente que atualmente é experimental e está sujeita a alterações. Conforme a especificação evolui, o comportamento e a interface dessa API serão atualizados adequadamente. Recomenda-se que os desenvolvedores monitorem as notas de HealthLake lançamento da AWS e as atualizações relevantes da especificação FHIR para se manterem informados sobre quaisquer alterações que possam afetar suas integrações.
Essa operação é particularmente útil quando você precisa:
Processe a correspondência de membros em grande escala durante os períodos de inscrição aberta
Facilite as transições de membros em massa entre pagadores
Support os requisitos de troca de dados de conformidade do CMS em grande escala
Combine eficientemente coortes de membros em todas as redes de saúde
Minimize as chamadas de API e melhore a eficiência operacional para cenários de correspondência de alto volume
Usage
A $bulk-member-match operação é uma operação assíncrona invocada em recursos do Grupo usando o método POST:
POST [base]/Group/$bulk-member-match
Depois de enviar uma solicitação de correspondência em massa, você pode pesquisar o status do trabalho usando:
GET [base]/$bulk-member-match-status/{jobId}
Parâmetros compatíveis
HealthLake suporta os seguintes parâmetros FHIR: $bulk-member-match
| Parâmetro | Tipo | Obrigatório | Description |
|---|---|---|---|
|
Paciente |
Sim |
Recurso para pacientes contendo informações demográficas para o membro a ser combinado. |
|
Cobertura |
Sim |
Recurso de cobertura que será usado para comparar com os registros existentes. |
|
Cobertura |
Não |
Recurso de cobertura a ser vinculado durante o processo de correspondência. |
|
Consentimento |
Sim |
O recurso de consentimento para fins de autorização também é armazenado. Isso é diferente da |
Solicitação POST para enviar uma vaga de correspondência de membros em massa
O exemplo a seguir mostra uma solicitação POST para enviar um trabalho por correspondência de membros em massa. Cada membro é encapsulado em um MemberBundle parâmetro contendo os Consent recursos e os recursos necessários MemberPatientCoverageToMatch, além de um opcionalCoverageToLink.
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" } ] } } ] } ] }
Resposta de trabalho concluída com saída
Quando o trabalho é concluído, a resposta inclui metadados do trabalho e um recurso de parâmetros FHIR contendo três recursos de grupo que categorizam os resultados da correspondência.
{ "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" } } ] } } ] } }
Como HealthLake classifica os membros em grupos de saída
Cada membro enviado em uma $bulk-member-match solicitação é avaliado por meio de um pipeline sequencial. O resultado de cada etapa determina em qual grupo de saída o membro é colocado.
Validação estrutural — Está em MemberBundle conformidade com os perfis exigidos? Em caso de falha: Erro (não em nenhum grupo).
Correspondência de pacientes — É possível HealthLake encontrar pacientes que correspondam aos dados demográficos enviados? Em caso de falha: NonMatchedMembers.
Confirmação de cobertura — Posso HealthLake restringir a exatamente um paciente com validade CoverageToMatch? Em caso de falha: NonMatchedMembers.
Avaliação do consentimento — O consentimento enviado é honroso no momento? (status = ativo, o período cobre a data atual, o artista pode ser validado). Em caso de falha: ConsentConstrainedMembers.
Sucesso — Todas as verificações são aprovadas. Consentimento armazenado no armazenamento de dados. Membro inserido MatchedMembers.
Princípio fundamental: um membro só pode aparecer em um destino. A primeira etapa com falha determina o posicionamento. Os membros que falham nas etapas 2 ou 3 nunca são colocados ConsentConstrainedMembers - esse grupo é exclusivamente para membros que se candidataram com sucesso, mas cujo consentimento não pode ser honrado.
Detalhes da avaliação do consentimento (Etapa 4):
Verificação 1 — Status de consentimento: É
Consent.statusigual a “ativo”? Se não → ConsentConstrainedMembers.Verificação 2 — Período de provisão:
provision.periodCobre a data atual? Se a data atual for antesperiod.startou depois deperiod.end→ ConsentConstrainedMembers.Verificação 3 — Validação do executante: A
Consent.performerreferência pode ser validada? Se o recurso referenciado não for encontrado no armazenamento de dados ou não estiver associado ao paciente correspondente →. ConsentConstrainedMembers
Todas as verificações devem ser aprovadas para que o membro seja inserido MatchedMembers e para que o consentimento seja armazenado.
Comportamento de correspondência de cobertura
Durante a correspondência de membros, somente CoverageToMatch é validado no armazenamento de dados do pagador respondente. CoverageToLinkpertence ao new/requesting pagador e não é validado no armazenamento de dados do pagador antigo. A inclusão CoverageToLink na solicitação não afetará os resultados correspondentes.
Cada combinação de Paciente e Cobertura na solicitação é processada de forma independente. O mesmo paciente pode ser enviado várias vezes com planos de cobertura diferentes, e cada inscrição recebe seu próprio resultado com base em sua cobertura específica.
Tratamento de referências do executante de consentimento
O novo pagador pode enviar uma referência temporária ou local do paciente Consent.performer (por exemplo, a mesma referência usada emConsent.patient). HealthLake resolve essas referências automaticamente:
Se
Consent.performercontiver a mesma referência local deConsent.patient, HealthLake substitui-a pela referência real do paciente correspondente após a correspondência ser bem-sucedida.HealthLake suporta referências de artistas do tipo Paciente RelatedPerson, Profissional e Organização (referências diretas e referências de identificadores lógicos). PractitionerRole
Se a validação do executor falhar (recurso não encontrado ou não associado ao paciente correspondente), o membro será inserido em ConsentConstrainedMembers vez de retornar um erro.
Recursos do Grupo de Saída
O trabalho concluído retorna um recurso de Parâmetros contendo três recursos do Grupo:
- MatchedMembers Group (Grupo)
-
Contém referências de pacientes para todos os membros combinados com sucesso cujo consentimento está ativo e válido no momento da solicitação. O recurso Consent é criado e armazenado no armazenamento de dados para cada membro correspondente. Esse grupo é instanciado no armazenamento de dados e pode ser usado diretamente com o.
$davinci-data-export - NonMatchedMembers Group (Grupo)
-
Contém referências a membros nos quais nenhuma correspondência exclusiva foi encontrada. Um membro é colocado aqui quando nenhum paciente no armazenamento de dados corresponde aos dados demográficos fornecidos, não existe cobertura válida para nenhum candidato a paciente compatível ou vários pacientes correspondem aos dados demográficos e vários têm cobertura válida (ambígua).
- ConsentConstrainedMembers Group (Grupo)
-
Contém referências de pacientes para membros que foram combinados com sucesso (dados demográficos e cobertura confirmados), mas cujo consentimento não pode ser honrado no momento da solicitação. O recurso Consent não é armazenado para membros com restrições de consentimento. A identidade do membro correspondente (MemberIdentifier e MemberId) ainda está incluída para que o pagador solicitante saiba quem foi restringido.
O Group.quantity campo contém a contagem total de membros em cada um de seus respectivos grupos.
Referências dos membros do grupo:
Group.member.entity.reference— Para MatchedMembers e ConsentConstrainedMembers, contém a ID do paciente do membro correspondente no sistema do pagador respondente. Para NonMatchedMembers, faz referência à entrada Patient contida.Group.member.entity.extension (base-ext-match-parameters)— Contém o ID do paciente da solicitação de entrada original (o ID enviado pelo pagador solicitante, derivado dePatient.idCoverage.beneficiary.reference, ouConsent.patient.reference).
Consent-Patient ligação
Importante
O recurso de consentimento armazenado retém a referência do paciente exatamente conforme enviada pelo pagador solicitante. HealthLake não atualiza automaticamente o campo do paciente do consentimento para apontar para o paciente correspondente no armazenamento de dados receptor.
Para vincular um consentimento armazenado ao paciente correspondente, use o resultado do trabalho: cada membro do MatchedMembers grupo tem um member.entity.reference apontando para o paciente correspondente e um member.entity.extension (base-ext-match-parameters) apontando para o paciente de entrada contido. Cross-reference estes com o campo do paciente do Consent para criar o mapeamento em sua camada de aplicação.
O que é armazenado versus o que é transitório
A tabela a seguir documenta o que HealthLake persiste no armazenamento de dados durante o $bulk-member-match processamento e o que existe somente na resposta do trabalho:
| Recurso | Armazenado? | Pode ser consultado via REST? | Observações |
|---|---|---|---|
MemberPatient (entrada) |
Não |
Não |
Usado somente para correspondência; não persiste |
CoverageToMatch (entrada) |
Não |
Não |
Usado somente para confirmação de cobertura |
CoverageToLink (entrada) |
Não |
Não |
Não validado em relação ao armazenamento de dados; pertence ao novo pagador |
Consentimento (membros correspondentes) |
Sim |
Sim — GET [base] /Consent/ {id} |
Armazenado como recebido do pagador solicitante |
Consentimento (membros restritos) |
Não |
Não |
Não armazenado. A identidade do membro ainda está incluída na resposta. |
MatchedMembers Grupo (saída) |
Sim |
Sim — GET [base] /Group/ {id} |
Instanciado; utilizável com $davinci-data-export |
NonMatchedMembers Grupo |
Não |
Não |
Somente resposta de emprego |
ConsentConstrainedMembers Grupo |
Não |
Não |
Somente resposta de emprego |
Integração com $davinci-data-export
O recurso de MatchedMembers grupo retornado por $bulk-member-match pode ser usado diretamente com a $davinci-data-export operação para recuperar dados de membros em massa:
POST [base]/Group/{matched-group-id}/$davinci-data-export GET [base]/Group/{matched-group-id}
Essa integração permite fluxos de trabalho eficientes em que você primeiro identifica os membros correspondentes em massa e depois exporta seus registros de saúde completos usando o recurso de grupo resultante.
Usando $member-remove antes da exportação
Se você precisar excluir membros específicos da exportação após a correspondência (por exemplo, um membro revoga o consentimento entre a correspondência e a exportação), use $member-remove no MatchedMembers Grupo.
Importante
Remover um membro via $member-remove marca o membro como inativo no Grupo, mas $davinci-data-export só exclui membros inativos depois que o Grupo é atualizado para o status “final”. Se você chamar $davinci-data-export um grupo que ainda tem o status padrão, os membros removidos ainda poderão aparecer nos resultados de exportação.
Fluxo de trabalho:
POST [base]/Group/{id}/$member-remove— marcar membros inativosPUT [base]/Group/{id}— atualize o status do grupo para “final”POST [base]/Group/{id}/$davinci-data-export— a exportação agora exclui membros removidos
Características de desempenho
A $bulk-member-match operação foi projetada para processamento de alto volume e é executada de forma assíncrona:
Concorrência: máximo de 5 operações simultâneas por armazenamento de dados.
Escalabilidade: lida com até 500 membros por solicitação (limite de carga útil de 5 MB).
Operações paralelas: Compatível com operações simultâneas de importação, exportação ou exclusão em massa.
Autorização
A API usa SMART no protocolo de autorização FHIR com os seguintes escopos obrigatórios:
system/Patient.read— Necessário para pesquisar e combinar os recursos do paciente.system/Coverage.read— Necessário para validar as informações de cobertura.system/Group.write— Necessário para criar recursos do Grupo de resultados.system/Organization.read— Condicional, obrigatório se a cobertura fizer referência a organizações.system/Practitioner.read— Condicional, exigido se a cobertura fizer referência a profissionais.system/PractitionerRole.read— Condicional, exigido se a cobertura fizer referência às funções dos profissionais.system/Consent.write— Condicional, exigido se os recursos de consentimento forem fornecidos.
A operação também oferece suporte à autorização AWS do IAM Signature Version 4 (SigV4) para acesso programático.
Regras de validação
As regras de validação a seguir são aplicadas a cada uma MemberBundle na Etapa 1. Os membros que falham na validação são relatados como erros e não aparecem em nenhum grupo de saída.
MemberPatient
| Campo | Como HealthLake o usa | Falha na validação se... |
|---|---|---|
| Pesquisa demográfica | Missing (Ausente) |
| Pesquisa demográfica | Falta (é necessário pelo menos um) |
| Pesquisa demográfica | Missing (Ausente) |
| Pesquisa demográfica; se ausente, extensão Birth Sex usada | Nem sexo nem nascimento. Sexo presente (hrex-pat-1) |
| Incluído na pesquisa quando presente; melhora a confiança | Nunca causa falha (opcional) |
CoverageToMatch / CoverageToLink
| Campo | Como HealthLake o usa | Falha na validação se... |
|---|---|---|
| Confirma que a cobertura é acionável | Missing (Ausente) |
| Vincula a cobertura a um candidato a paciente | Missing (Ausente) |
| Desambiguação quando existem vários candidatos | Falta ou mais de um pagador |
| Confirma a relação assinante-beneficiário | Missing (Ausente) |
| Chave primária de desambiguação | Nenhum presente |
Consentimento
| Campo | Como HealthLake o usa | Falha na validação se... |
|---|---|---|
| Confirma que o escopo do consentimento é a privacidade do paciente | Código de privacidade do paciente ausente ou inexistente |
| Confirma a classificação da divulgação | Missing (Ausente) |
| Identifica o sujeito do consentimento | Missing (Ausente) |
| Identifica quem está concordando | Missing (Ausente) |
| Documenta a fonte de consentimento | Missing (Ausente) |
| Determina o escopo do compartilhamento de dados | Falta ou o URI não termina em #regular ou #sensitive |
| Deve ser “permissão” de acordo com o perfil de consentimento da HRex | “Permissão” ausente ou não (incluindo “negar”) |
| Avaliado na Etapa 4 para verificação com restrição de consentimento | Desaparecido ou não start/end |
| Avaliado na Etapa 4 (NÃO na Etapa 1) | Nunca causa falha na Etapa 1 — HealthLake aceita qualquer status válido e avalia na Etapa 4 |
nota
O perfil HRex Consent define o status com um valor fixo de “ativo”. HealthLake relaxa intencionalmente essa restrição para que um consentimento não ativo receba uma classificação significativa (ConsentConstrainedMembers) em vez de uma rejeição geral de validação.
Comportamento de correspondência
Pesquisa de pacientes (Etapa 2) — HealthLake pesquisas usando
name.family+name.given(exato, sem distinção entre maiúsculas e minúsculas),birthDate(exato),gender(exato; sexo do nascimento usado se o sexo não existir) eidentifier(quando presente, opcional).Desambiguação da cobertura (Etapa 3) — Quando vários candidatos a pacientes são encontrados,
CoverageToMatché usada para restringir a um. Uma cobertura é “válida” quando existe um recurso de cobertura ativo no armazenamento de dados que corresponda asubscriberIdouidentifier(tipo MB) AND.payorAvaliação do consentimento (Etapa 4) - Realizada somente após uma combinação única bem-sucedida. Consulte a seção de detalhes da avaliação de consentimento acima.
Tratamento de erros
A operação trata das seguintes condições de erro:
400 Solicitação inválida: formato de solicitação inválido, parâmetros obrigatórios ausentes ou a carga excede os limites de tamanho (500 membros ou 5 MB).
422 Entidade não processável: erros de processamento durante a execução do trabalho.
Erros individuais de membros: quando um membro específico não consegue processar, a operação continua com os membros restantes e inclui detalhes do erro no NonMatchedMembers Grupo com códigos de motivo apropriados. Por exemplo, um
MemberBundlepaciente sem obirthDateparâmetro retornará o seguinte erro:"errors": [ { "memberIndex": 1, "jsonBlob": { "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "invalid", "diagnostics": "MemberPatient.birthDate is required" } ], "statusCode": 400 } } ]
Os detalhes do erro estão disponíveis por meio do endpoint da pesquisa de status e incluem:
numberOfMembersWithCustomerError: Contagem de membros com erros de validação ou entrada.numberOfMembersWithServerError: contagem de membros com erros de processamento no servidor.
Operações do relacionadas
$member-matchoperação para HealthLake— Operação de correspondência de membros individuais.
Operação FHIR R4 para $davinci-data-export HealthLake— Exportação de dados em massa usando recursos do Grupo.
FHIR R4 para $operations HealthLake— Lista completa das operações suportadas.