View a markdown version of this page

operação $bulk-member-match para HealthLake - AWS HealthLake

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

MemberPatient

Paciente

Sim

Recurso para pacientes contendo informações demográficas para o membro a ser combinado.

CoverageToMatch

Cobertura

Sim

Recurso de cobertura que será usado para comparar com os registros existentes.

CoverageToLink

Cobertura

Não

Recurso de cobertura a ser vinculado durante o processo de correspondência.

Consent

Consentimento

Sim

O recurso de consentimento para fins de autorização também é armazenado. Isso é diferente da $member-match operação individual em que o consentimento não é necessário.

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.

  1. Validação estrutural — Está em MemberBundle conformidade com os perfis exigidos? Em caso de falha: Erro (não em nenhum grupo).

  2. Correspondência de pacientes — É possível HealthLake encontrar pacientes que correspondam aos dados demográficos enviados? Em caso de falha: NonMatchedMembers.

  3. Confirmação de cobertura — Posso HealthLake restringir a exatamente um paciente com validade CoverageToMatch? Em caso de falha: NonMatchedMembers.

  4. 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.

  5. 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.status igual a “ativo”? Se não → ConsentConstrainedMembers.

  • Verificação 2 — Período de provisão: provision.period Cobre a data atual? Se a data atual for antes period.start ou depois de period.end → ConsentConstrainedMembers.

  • Verificação 3 — Validação do executante: A Consent.performer referê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.performer contiver 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 de Patient.idCoverage.beneficiary.reference, ouConsent.patient.reference).

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:

  1. POST [base]/Group/{id}/$member-remove— marcar membros inativos

  2. PUT [base]/Group/{id}— atualize o status do grupo para “final”

  3. 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

CampoComo HealthLake o usaFalha na validação se...

name.family

Pesquisa demográfica

Missing (Ausente)

name.given

Pesquisa demográfica

Falta (é necessário pelo menos um)

birthDate

Pesquisa demográfica

Missing (Ausente)

gender

Pesquisa demográfica; se ausente, extensão Birth Sex usada

Nem sexo nem nascimento. Sexo presente (hrex-pat-1)

identifier

Incluído na pesquisa quando presente; melhora a confiança

Nunca causa falha (opcional)

CoverageToMatch / CoverageToLink

CampoComo HealthLake o usaFalha na validação se...

status

Confirma que a cobertura é acionável

Missing (Ausente)

beneficiary

Vincula a cobertura a um candidato a paciente

Missing (Ausente)

payor

Desambiguação quando existem vários candidatos

Falta ou mais de um pagador

relationship

Confirma a relação assinante-beneficiário

Missing (Ausente)

identifier (MB) or subscriberId

Chave primária de desambiguação

Nenhum presente

CampoComo HealthLake o usaFalha na validação se...

scope

Confirma que o escopo do consentimento é a privacidade do paciente

Código de privacidade do paciente ausente ou inexistente

category

Confirma a classificação da divulgação

Missing (Ausente)

patient

Identifica o sujeito do consentimento

Missing (Ausente)

performer

Identifica quem está concordando

Missing (Ausente)

sourceReference

Documenta a fonte de consentimento

Missing (Ausente)

policy.uri

Determina o escopo do compartilhamento de dados

Falta ou o URI não termina em #regular ou #sensitive

provision.type

Deve ser “permissão” de acordo com o perfil de consentimento da HRex

“Permissão” ausente ou não (incluindo “negar”)

provision.period

Avaliado na Etapa 4 para verificação com restrição de consentimento

Desaparecido ou não start/end

status

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) e identifier (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 a subscriberId ou identifier (tipo MB) AND. payor

  • Avaliaçã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 MemberBundle paciente sem o birthDate parâ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.