$bulk-member-match HealthLake에 대한 작업 - AWS HealthLake
사용법지원되는 파라미터대량 멤버 일치 작업 제출을 위한 POST 요청출력이 포함된 완료된 작업 응답출력 그룹 리소스$davinci-data-export와 통합성능 특성권한 부여오류 처리관련 작업

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

$bulk-member-match HealthLake에 대한 작업

AWS HealthLake 는 여러 멤버 일치 요청을 비동기적으로 처리하기 위한 $bulk-member-match 작업을 지원합니다. 이 작업을 통해 의료 기관은 단일 대량 요청으로 인구 통계 및 적용 범위 정보를 사용하여 여러 의료 시스템에서 수백 명의 멤버의 고유 식별자를 효율적으로 일치시킬 수 있습니다. 이 기능은 대규모 payer-to-payer 데이터 교환, 멤버 전환 및 CMS 규정 준수 요구 사항에 필수적이며 FHIR 사양을 따릅니다.

참고

$bulk-member-match 작업은 현재 실험적이고 변경될 수 있는 기본 FHIR 사양을 기반으로 합니다. 사양이 발전함에 따라이 API의 동작과 인터페이스가 그에 따라 업데이트됩니다. 개발자는 AWS HealthLake 릴리스 정보와 관련 FHIR 사양 업데이트를 모니터링하여 통합에 영향을 미칠 수 있는 변경 사항을 최신 상태로 유지하는 것이 좋습니다.

이 작업은 다음이 필요한 경우에 특히 유용합니다.

  • 공개 등록 기간 동안 대규모로 멤버 매칭 처리

  • 지급인 간 대량 멤버 전환 촉진

  • 대규모 CMS 규정 준수 데이터 교환 요구 사항 지원

  • 의료 네트워크 전반의 구성원 코호트를 효율적으로 일치시킵니다.

  • 대량 매칭 시나리오에서 API 호출을 최소화하고 운영 효율성 개선

사용법

$bulk-member-match 작업은 POST 메서드를 사용하여 그룹 리소스에서 호출되는 비동기 작업입니다.

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

대량 일치 요청을 제출한 후 다음을 사용하여 작업 상태를 폴링할 수 있습니다.

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

지원되는 파라미터

HealthLake는 다음 FHIR $bulk-member-match 파라미터를 지원합니다.

파라미터 Type 필수 설명

MemberPatient

환자

예

일치시킬 구성원의 인구통계 정보가 포함된 환자 리소스입니다.

CoverageToMatch

적용 범위

예

기존 레코드와 일치시키는 데 사용할 적용 범위 리소스입니다.

CoverageToLink

적용 범위

아니요

매칭 프로세스 중에 연결할 적용 범위 리소스입니다.

Consent

동의

예

권한 부여를 위한 동의 리소스도 저장됩니다. 이는 동의가 필요하지 않은 개별 $member-match 작업과 다릅니다.

대량 멤버 일치 작업 제출을 위한 POST 요청

다음 예제는 대량 멤버 일치 작업을 제출하기 위한 POST 요청을 보여줍니다. 각 멤버는 필수 MemberPatient, CoverageToMatch및 Consent 리소스를 포함하는 MemberBundle 파라미터와 선택적 로 래핑됩니다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"
              }
            ]
          }
        }
      ]
    }
  ]
}

출력이 포함된 완료된 작업 응답

작업이 완료되면 응답에는 작업 메타데이터와 일치 결과를 분류하는 세 개의 그룹 리소스가 포함된 FHIR 파라미터 리소스가 포함됩니다.

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

출력 그룹 리소스

완료된 작업은 세 개의 그룹 리소스가 포함된 파라미터 리소스를 반환합니다.

MatchedMembers 그룹

성공적으로 일치하는 모든 구성원에 대한 환자 참조를 포함하며 동의 제약으로 분류되지 않습니다.

Group.quantity 필드에는 각 그룹의 총 멤버 수가 포함됩니다.

NonMatchedMembers 그룹

일치 항목이 없거나 여러 일치 항목이 식별된 멤버에 대한 참조가 포함되어 있습니다.

ConsentConstrainedMembers 그룹

동의 제약 조건이 데이터 공유를 방해하는 성공적으로 일치하는 모든 멤버에 대한 환자 참조가 포함되어 있습니다. 동의 리소스는 다음 두 조건이 모두 있는 경우 제한된 것으로 간주됩니다.

  • 정책 URI는 로 끝#sensitive납니다. 가장 명확하고 직접적인 신호입니다. 제출 지급인은 "이 구성원의 데이터는 민감합니다. 주의해서 처리합니다."라고 명시적으로 말합니다.

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

  • 최상위 프로비저닝 유형은 입니다. deny 멤버가 데이터 공유를 광범위하게 거부했습니다.

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

$davinci-data-export와 통합

에서 반환한 MatchedMembers 그룹 리소스를 $davinci-data-export 작업과 함께 직접 사용하여 대량 멤버 데이터를 검색할 $bulk-member-match 수 있습니다.

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

이 통합을 통해 먼저 일치하는 구성원을 대량으로 식별한 다음 결과 그룹 리소스를 사용하여 전체 상태 레코드를 내보내는 효율적인 워크플로를 사용할 수 있습니다.

성능 특성

이 $bulk-member-match 작업은 대량 처리를 위해 설계되었으며 비동기적으로 실행됩니다.

  • 동시성: 데이터 스토어당 최대 5개의 동시 작업.

  • 확장성: 요청당 최대 500명의 멤버를 처리합니다(5MB 페이로드 제한).

  • 병렬 작업: 동시 가져오기, 내보내기 또는 대량 삭제 작업과 호환됩니다.

권한 부여

API는 다음 필수 범위와 함께 FHIR 인증 프로토콜에서 SMART를 사용합니다.

  • system/Patient.read - 환자 리소스를 검색하고 일치시키는 데 필요합니다.

  • system/Coverage.read - 적용 범위 정보를 검증하는 데 필요합니다.

  • system/Group.write - 결과 그룹 리소스를 생성하는 데 필요합니다.

  • system/Organization.read - 조건부, 적용 범위가 조직을 참조하는 경우 필요합니다.

  • system/Practitioner.read - 조건부, 적용 범위가 실무자를 참조하는 경우 필수입니다.

  • system/PractitionerRole.read - 조건부, 적용 범위가 실무자 역할을 참조하는 경우 필수입니다.

  • system/Consent.write - 조건부, 동의 리소스가 제공된 경우 필수입니다.

또한이 작업은 프로그래밍 방식 액세스를 위한 AWS IAM 서명 버전 4(SigV4) 권한 부여를 지원합니다.

오류 처리

작업은 다음 오류 조건을 처리합니다.

  • 400 잘못된 요청: 잘못된 요청 형식, 필수 파라미터 누락 또는 페이로드가 크기 제한(멤버 500명 또는 5MB)을 초과합니다.

  • 422 처리 불가능한 엔터티: 작업 실행 중 처리 오류.

  • 개별 멤버 오류: 특정 멤버가 처리에 실패하면 작업은 나머지 멤버로 계속되며 적절한 사유 코드와 함께 NonMatchedMembers 그룹에 오류 세부 정보가 포함됩니다. 예를 들어, 환자가 birthDate 파라미터가 누락된 MemberBundle는 다음 오류를 반환합니다.

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

오류 세부 정보는 상태 폴링 엔드포인트를 통해 사용할 수 있으며 다음을 포함합니다.

  • numberOfMembersWithCustomerError: 검증 또는 입력 오류가 있는 멤버 수입니다.

  • numberOfMembersWithServerError: 서버 측 처리 오류가 있는 멤버 수입니다.