$bulk-member-matchoperación para HealthLake - AWS HealthLake
De usoParámetros admitidosSolicitud POST para enviar un trabajo de emparejamiento masivo de miembrosRespuesta al trabajo completada con salidaRecursos del grupo de salidaIntegración con $ davinci-data-exportCaracterísticas de rendimientoAutorizaciónGestión de erroresOperaciones de relacionadas

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

$bulk-member-matchoperación para HealthLake

AWS HealthLake admite la $bulk-member-match operación de procesar las solicitudes de emparejamiento de varios miembros de forma asíncrona. Esta operación permite a las organizaciones de atención médica comparar de manera eficiente los identificadores únicos de cientos de miembros de diferentes sistemas de salud utilizando información demográfica y de cobertura en una sola solicitud masiva. Esta capacidad es esencial para el intercambio de payer-to-payer datos a gran escala, las transiciones de miembros y los requisitos de conformidad con los CMS, y sigue la especificación de la FHIR.

nota

La $bulk-member-match operación se basa en una especificación subyacente del FHIR que actualmente se encuentra en fase experimental y está sujeta a cambios. A medida que la especificación evolucione, el comportamiento y la interfaz de esta API se actualizarán en consecuencia. Se recomienda a los desarrolladores que supervisen las notas de la HealthLake versión de AWS y las actualizaciones de las especificaciones del FHIR pertinentes para mantenerse informados de cualquier cambio que pueda afectar a sus integraciones.

Esta operación resulta especialmente útil cuando necesita:

  • Procese la comparación de miembros a gran escala durante los períodos de inscripción abierta

  • Facilite las transiciones masivas de miembros entre pagadores

  • Support con los requisitos de intercambio de datos de conformidad con los CMS a gran escala

  • Haga coincidir de manera eficiente las cohortes de miembros en todas las redes de atención médica

  • Minimice las llamadas a la API y mejore la eficiencia operativa en escenarios de coincidencia de gran volumen

De uso

La $bulk-member-match operación es una operación asíncrona que se invoca en los recursos del grupo mediante el método POST:

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

Tras enviar una solicitud de coincidencia masiva, puedes sondear el estado del trabajo mediante:

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

Parámetros admitidos

HealthLake admite los siguientes $bulk-member-match parámetros del FHIR:

Parámetro Tipo Obligatorio Description (Descripción)

MemberPatient

Paciente

Sí

Recurso para pacientes que contiene información demográfica sobre el miembro al que se va a vincular.

CoverageToMatch

Cobertura

Sí

Recurso de cobertura que se utilizará para compararlo con los registros existentes.

CoverageToLink

Cobertura

No

Recurso de cobertura que se vinculará durante el proceso de emparejamiento.

Consent

Consentimiento

Sí

También se almacena el recurso de consentimiento para fines de autorización. Esto es diferente de la $member-match operación individual en la que no se requiere el consentimiento.

Solicitud POST para enviar un trabajo de emparejamiento masivo de miembros

El siguiente ejemplo muestra una solicitud POST para enviar un trabajo de emparejamiento masivo de miembros. Cada miembro está incluido en un MemberBundle parámetro que contiene los Consent recursos necesarios MemberPatient y uno opcionalCoverageToLink. CoverageToMatch

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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Respuesta al trabajo completada con salida

Cuando se completa el trabajo, la respuesta incluye los metadatos del trabajo y un recurso de parámetros del FHIR que contiene tres recursos del grupo que clasifican los resultados de la coincidencia.

{
  "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"
              }
            }
          ]
        }
      }
    ]
  }
}

Recursos del grupo de salida

El trabajo completado devuelve un recurso de parámetros que contiene tres recursos de grupo:

MatchedMembers Group (Grupo)

Contiene las referencias de los pacientes de todos los miembros seleccionados correctamente y no se clasifica como restricción de consentimiento.

El Group.quantity campo contiene el recuento total de miembros de cada uno de sus grupos respectivos.

NonMatchedMembers Group (Grupo)

Contiene referencias a miembros en los que no se encontró ninguna coincidencia o se identificaron varias coincidencias.

ConsentConstrainedMembers Group (Grupo)

Contiene las referencias de los pacientes de todos los miembros emparejados correctamente cuando las restricciones de consentimiento impiden el intercambio de datos. Un recurso de consentimiento se considera limitado cuando se dan las dos condiciones siguientes:

  • El URI de la política termina en #sensitive: es la señal más clara y directa. El pagador que los envía dice explícitamente: «Los datos de este miembro son confidenciales; trátelos con cuidado».

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

  • El tipo de disposición de nivel superior es deny: el miembro se ha negado ampliamente a compartir datos.

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

Integración con $ davinci-data-export

El recurso del MatchedMembers grupo devuelto por se $bulk-member-match puede utilizar directamente con la $davinci-data-export operación para recuperar datos masivos de los miembros:

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

Esta integración permite flujos de trabajo eficientes en los que primero se identifican los miembros coincidentes de forma masiva y, a continuación, se exportan sus historiales médicos completos utilizando el recurso del grupo resultante.

Características de rendimiento

La $bulk-member-match operación está diseñada para el procesamiento de grandes volúmenes y se ejecuta de forma asíncrona:

  • Simultaneidad: máximo de 5 operaciones simultáneas por almacén de datos.

  • Escalabilidad: gestiona hasta 500 miembros por solicitud (límite de carga útil de 5 MB).

  • Operaciones paralelas: compatible con operaciones simultáneas de importación, exportación o eliminación masiva.

Autorización

La API utiliza el protocolo de autorización SMART on FHIR con los siguientes ámbitos obligatorios:

  • system/Patient.read— Necesaria para buscar y comparar los recursos de los pacientes.

  • system/Coverage.read— Necesario para validar la información de cobertura.

  • system/Group.write— Necesario para crear los recursos del grupo de resultados.

  • system/Organization.read— Condicional, obligatorio si la cobertura hace referencia a organizaciones.

  • system/Practitioner.read— Condicional, obligatorio si la cobertura hace referencia a profesionales.

  • system/PractitionerRole.read— Condicional, obligatorio si la cobertura hace referencia a las funciones de los profesionales.

  • system/Consent.write— Condicional, obligatorio si se proporcionan recursos de consentimiento.

La operación también admite la autorización de la versión 4 (SiGv4) de AWS IAM Signature para el acceso programático.

Gestión de errores

La operación gestiona las siguientes condiciones de error:

  • 400 Solicitud errónea: el formato de solicitud no es válido, faltan los parámetros necesarios o la carga útil supera los límites de tamaño (500 miembros o 5 MB).

  • 422 Entidad inprocesable: errores de procesamiento durante la ejecución del trabajo.

  • Errores de miembros individuales: cuando un miembro específico no se procesa, la operación continúa con los miembros restantes e incluye los detalles del error en el NonMatchedMembers grupo con los códigos de motivo correspondientes. Por ejemplo, si MemberBundle a un paciente le falta el birthDate parámetro, se mostrará el siguiente error:

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

Los detalles del error están disponibles en el punto final del sondeo de estado e incluyen:

  • numberOfMembersWithCustomerError: Recuento de miembros con errores de validación o entrada.

  • numberOfMembersWithServerError: Recuento de miembros con errores de procesamiento en el servidor.