View a markdown version of this page

$bulk-member-match HealthLake 的 操作 - AWS HealthLake
Usage快速入門支援的參數提交大量成員比對任務的 POST 請求使用輸出完成任務回應HealthLake 如何將成員分類為輸出群組涵蓋範圍比對行為同意執行者參考處理輸出群組資源同意病患連結儲存的內容與暫時性的內容與 $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}

每個請求最多支援 500 個成員，承載上限為 5 MB。

快速入門

若要開始使用大量成員配對，請遵循下列步驟：

  1. 使用 Group/$bulk-member-match操作向 MemberBundles 提交大量比對請求。回應包含任務 ID。

  2. 使用 $bulk-member-match-status操作輪詢任務狀態，直到狀態為 COMPLETED。

  3. 從完成的任務回應中擷取MatchedMembers群組 ID。

  4. 使用相符群組上的 Group/$davinci-data-export操作匯出臨床資料。

支援的參數

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

參數 Type 必要 說明

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

HealthLake 如何將成員分類為輸出群組

在$bulk-member-match請求中提交的每個成員都會透過循序管道進行評估。每個步驟的結果會決定成員所在的輸出群組。

  1. 結構驗證 — MemberBundle 是否符合必要的設定檔？ 失敗時：錯誤 （不是在任何群組中）。

  2. 患者比對 — HealthLake 可以找到符合所提交人口統計特性的患者嗎？ 失敗時：NonMatchedMembers。

  3. 涵蓋範圍確認 — HealthLake 是否可以縮小到只有一位具有有效 CoverageToMatch 的患者？ 失敗時：NonMatchedMembers。

  4. 同意評估 — 是否provision.period涵蓋目前日期？ 失敗時：ConsentConstrainedMembers。

  5. 成功 — 所有檢查都通過。儲存在資料存放區的同意。放置在 MatchedMembers 中的成員。

金鑰原則：成員只能出現在一個目的地中。第一個失敗步驟決定放置位置。未通過步驟 2 或 3 的成員絕不會置於 ConsentConstrainedMembers 中 — 該群組僅適用於成功配對但無法接受其同意的成員。

同意評估詳細資訊 （步驟 4)：

  • 佈建期間：是否provision.period涵蓋目前日期？ 如果目前日期在 period.end → ConsentConstrainedMembers 之前period.start或之後。

所有檢查都必須通過，才能將成員放置在 MatchedMembers 中，並儲存同意。

注意

操作不會針對 patient 欄位驗證performer參考。父母或監護人可以代表眷屬進行同意。

下表說明同意分類如何決定成員置放：

佈建類型政策 URI狀態Period結果

permit

#regular

active

涵蓋目前日期

MatchedMembers （已儲存同意）

permit

#sensitive

active

涵蓋目前日期

MatchedMembers （已儲存同意）

permit

#regular 或 #sensitive

active

已過期或未啟動

ConsentConstrainedMembers

deny

任何

任何

任何

400 錯誤的請求 （步驟 1)

permit

結尾不是 #regular或 #sensitive

任何

任何

400 錯誤的請求 （步驟 1)

任何

任何

不是 active

任何

400 錯誤的請求 （步驟 1)

涵蓋範圍比對行為

在成員比對期間，只會針對回應付款人的資料存放區進行CoverageToMatch驗證。 CoverageToLink屬於新的/請求的付款人，且不會針對舊付款人的資料存放區進行驗證。在請求CoverageToLink中包含 不會影響相符的結果。

請求中的每個病患 + 涵蓋範圍組合都會獨立處理。同一個病患可以使用不同的涵蓋範圍計劃多次提交，而且每個項目都會根據其特定涵蓋範圍收到自己的結果。

同意執行者參考處理

新的付款人可能會在 中傳送臨時或本機患者參考 Consent.performer（例如，與 中使用的相同參考Consent.patient)。HealthLake 會自動解析這些參考：

  • 如果 Consent.performer包含與 相同的本機參考Consent.patient，則 HealthLake 會在相符成功後將其取代為實際相符的患者參考。

  • HealthLake 支援 Patient、RelatedPerson、Practitioner、PractitionerRole 和 Organization 類型的執行器參考 （包括直接參考和邏輯識別符參考）。

  • performer 參考不會針對 進行交叉驗證patient。代表眷屬進行同意的父母/監護人是有效的，而且不會將成員路由到 ConsentConstrainedMembers。

輸出群組資源

已完成的任務會傳回包含三個群組資源的參數資源：

MatchedMembers 群組

包含所有成功配對成員的 病患參考，其同意在請求時處於作用中且有效狀態。系統會為每個相符的成員建立同意資源並存放在資料存放區中。此群組會在資料存放區中執行個體化，可直接與 搭配使用$davinci-data-export。

NonMatchedMembers 群組

包含對找不到唯一相符項目之成員的參考。當資料存放區中沒有患者符合提供的人口統計特性、任何相符患者候選者沒有有效的涵蓋範圍，或多個患者符合人口統計特性且多個患者具有有效的涵蓋範圍 （模棱兩可） 時，就會放置成員。此群組不會在資料存放區中執行個體化。它只存在於完成的任務回應中。

ConsentConstrainedMembers 群組

包含成功配對 （人口統計特性和涵蓋範圍已確認） 但請求時無法履行同意之成員的患者參考。不會為受同意限制的成員存放 同意資源。相符的成員身分 (MemberIdentifier 和 MemberId) 仍包含在內，因此請求付款人知道誰受到限制。此群組不會在資料存放區中執行個體化。它只存在於完成的任務回應中。

Group.quantity 欄位包含其各自群組中的成員總數。

群組成員參考：

  • Group.member.entity.reference — 對於 MatchedMembers 和 ConsentConstrainedMembers， 包含回應付款人系統中相符成員的患者 ID。對於 NonMatchedMembers， 會參考包含的輸入病患。

  • Group.member.entity.extension (base-ext-match-parameters) — 包含來自原始輸入請求的患者 ID （請求付款人提交的 ID，衍生自 Patient.id、 Coverage.beneficiary.reference或 Consent.patient.reference)。

重要

儲存的同意資源會完全依照請求付款人所提交的內容來保留病患參考。HealthLake 不會自動更新同意的患者欄位，以指向接收資料存放區中相符的患者。

若要將儲存的同意連結至相符的 病患，請使用任務輸出：MatchedMembers 群組中的每個成員都member.entity.reference指向相符的 病患，而 member.entity.extension(base-ext-match-parameters) 指向包含的輸入 病患。將這些與 同意的 病患欄位交叉參考，以在應用程式層中建置映射。

儲存的內容與暫時性的內容

下表記錄 HealthLake 在$bulk-member-match處理期間保留到資料存放區的內容，以及僅存在於任務回應中的內容：

資源 已存放？ 可透過 REST 查詢？ 備註

MemberPatient （輸入）

否

否

僅用於比對；不保留

CoverageToMatch （輸入）

否

否

僅用於範圍確認

CoverageToLink （輸入）

否

否

未針對資料存放區進行驗證；屬於新的付款人

同意 （相符的成員）

是

是 — GET 【base】/Consent/{id}

從請求付款人收到時儲存

同意 （受限成員）

否

否

未儲存。回應中仍包含成員身分。

MatchedMembers 群組 （輸出）

是

是 — GET 【base】/Group/{id}

執行個體化；可與 $davinci-data-export 搭配使用

NonMatchedMembers 群組

否

否

僅限任務回應

ConsentConstrainedMembers 群組

否

否

僅限任務回應

與 $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}

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

匯出前使用 $member-remove

如果您需要在相符之後排除特定成員匯出 （例如，成員撤銷相符和匯出之間的同意），請在MatchedMembers群組$member-remove上使用 。

重要

透過 移除成員會在群組中將成員$member-remove標記為非作用中，但$davinci-data-export只會在群組更新為「最終」狀態後排除非作用中成員。如果您在仍然具有預設狀態的 群組$davinci-data-export上呼叫 ，移除的成員仍可能會出現在匯出結果中。

工作流程：

  1. POST [base]/Group/{id}/$member-remove — 將成員標記為非作用中

  2. PUT [base]/Group/{id} — 將群組狀態更新為「最終」

  3. POST [base]/Group/{id}/$davinci-data-export — 匯出現在排除已移除的成員

效能特性

$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) 授權。

驗證規則

下列驗證規則會套用至步驟 1 的每個 MemberBundle。未通過驗證的成員會報告為錯誤，不會出現在任何輸出群組中。

MemberPatient

欄位HealthLake 如何使用它驗證失敗，如果...

name.family

人口統計搜尋

缺少

name.given

人口統計搜尋

缺少 （至少需要一個）

birthDate

人口統計搜尋

缺少

gender

人口統計搜尋；如果不存在，則使用 Birth Sex 延伸

性別和性別不存在 (hrex-pat-1)

identifier

存在時包含在搜尋中；提高可信度

永遠不會導致失敗 （選用）

CoverageToMatch / CoverageToLink

欄位HealthLake 如何使用它驗證失敗，如果...

status

確認涵蓋範圍是可行的

缺少

beneficiary

將涵蓋範圍連結至病患候選者

缺少

relationship

確認訂閱者與受益人的關係

缺少

identifier (MB) or subscriberId

主要歧義金鑰

兩者皆不存在

欄位HealthLake 如何使用它驗證失敗，如果...

scope

確認同意範圍為患者隱私

缺少或沒有病患隱私代碼

category

確認揭露分類

缺少

patient

識別同意主體

缺少

performer

識別誰同意

缺少

sourceReference

記錄同意來源

缺少

policy.uri

決定資料共用範圍

遺失或 URI 結尾不是 #regular 或 #sensitive

provision.type

每個 HRex 同意設定檔必須為「允許」

遺失或沒有「許可」（包括「拒絕」)

provision.period

在步驟 4 評估的同意限制檢查

遺失或沒有開始/結束

provision.actor

識別來源和收件人付款人

遺失或不包含每個 HRex 設定檔所需的來源 + 收件人演員

provision.action

確認揭露動作

遺失或沒有「公開」程式碼

status

每個 HRex IG 必須「作用中」

非「作用中」 — 傳回 400 個驗證錯誤

注意

根據 HRex IG， Consent.status 固定為「作用中」。HealthLake 會在步驟 1 （結構驗證） 強制執行此項，並在提供任何其他狀態時傳回 400 驗證錯誤。非作用中的同意不會處理或分類為 ConsentConstrainedMembers — 預先拒絕。

相符行為

  • 病患搜尋 （步驟 2) — HealthLake 使用 name.family + name.given（確切、不區分大小寫）、 birthDate （確切）、 gender （確切；如果性別不存在，則使用 birth Sex) 和 identifier（如果存在，則為選用） 進行搜尋。

  • 覆蓋範圍歧義 （步驟 3) — 找到多個病患候選項目時， CoverageToMatch 會用來縮小至一個。當在 subscriberId或 identifier(MB 類型） 上比對的資料存放區中存在作用中的覆蓋資源時，覆蓋是「有效」。

  • 同意評估 （步驟 4) — 僅在成功的唯一相符項目後執行。請參閱上述同意評估詳細資訊一節。

錯誤處理

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

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

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

  • 個別成員錯誤：當特定成員無法處理時，操作會繼續進行剩餘的成員，並包含錯誤詳細資訊與適當的原因代碼。例如，MemberBundle遺失 birthDate 參數且具有病患 的 將傳回下列錯誤：

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

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

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

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