$bulk-member-match HealthLake 的 操作 - AWS HealthLake
Usage支援的參數提交大量成員比對任務的 POST 請求使用輸出完成任務回應輸出群組資源與 $davinci-data-export 整合效能特性Authorization錯誤處理相關的 操作

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

$bulk-member-match HealthLake 的 操作

AWS HealthLake 支援非同步處理多個成員比對請求$bulk-member-match的操作。此操作可讓醫療保健組織在單一大量請求中使用人口統計和涵蓋範圍資訊，在不同的醫療保健系統中有效率地比對數百個成員的唯一識別符。此功能對於大規模payer-to-payer資料交換、成員轉換和 CMS 合規要求至關重要，並遵循 FHIR 規格。

注意

$bulk-member-match 操作是以目前實驗性且可能會有所變更的基礎 FHIR 規格為基礎。隨著規格的演進，此 API 的行為和界面也會隨之更新。建議開發人員監控 AWS HealthLake 版本備註和相關的 FHIR 規格更新，以隨時掌握可能影響其整合的任何變更。

當您需要執行下列動作時，此操作特別有用：

  • 在開放註冊期間大規模處理成員比對

  • 促進付款人之間的大量成員轉換

  • 支援大規模 CMS 合規資料交換需求

  • 有效率地比對跨醫療保健網路的成員群組

  • 將 API 呼叫降至最低，並提高大量比對案例的操作效率

Usage

$bulk-member-match 操作是使用 POST 方法在群組資源上調用的非同步操作：

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

提交大量比對請求後，您可以使用下列方式輪詢任務狀態：

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

支援的參數

HealthLake 支援下列 FHIR $bulk-member-match 參數：

參數 Type 必要 Description

MemberPatient

病患

是

包含要比對之成員人口統計資訊的患者資源。

CoverageToMatch

涵蓋範圍

是

用於比對現有記錄的涵蓋資源。

CoverageToLink

涵蓋範圍

否

比對程序期間要連結的覆蓋資源。

Consent

同意

是

授權用途的同意資源也會儲存。這與不需要同意的個別$member-match操作不同。

提交大量成員比對任務的 POST 請求

下列範例顯示提交大量成員比對任務的 POST 請求。每個成員都會包裝在MemberBundle參數中MemberPatient，其中包含必要的 CoverageToMatch、 和 Consent 資源，以及選用的 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 群組資源$bulk-member-match可以直接與 $davinci-data-export操作搭配使用，以擷取大量成員資料：

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

此整合可讓您在初次大量識別相符成員的高效工作流程，然後使用產生的群組資源匯出其完整的運作狀態記錄。

效能特性

$bulk-member-match 操作專為大量處理而設計，並以非同步方式執行：

  • 並行：每個資料存放區最多 5 個並行操作。

  • 可擴展性：每個請求最多可處理 500 個成員 (5 MB 承載限制）。

  • 平行操作：與並行匯入、匯出或大量刪除操作相容。

Authorization

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 Signature 第 4 版 (SigV4) 授權。

錯誤處理

操作會處理下列錯誤條件：

  • 400 錯誤的請求：無效的請求格式、缺少必要的參數或承載超過大小限制 (500 個成員或 5 MB)。

  • 422 無法處理的實體：在任務執行期間處理錯誤。

  • 個別成員錯誤：當特定成員無法處理時，操作會繼續保留剩餘成員，並在 NonMatchedMembers 群組中包含錯誤詳細資訊，並具有適當的原因代碼。例如，MemberBundle缺少 birthDate 參數且具有患者 的 將傳回下列錯誤：

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

錯誤詳細資訊可透過狀態輪詢端點取得，包括：

  • numberOfMembersWithCustomerError：發生驗證或輸入錯誤的成員計數。

  • numberOfMembersWithServerError：發生伺服器端處理錯誤的成員計數。