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}

支援的參數

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. 同意評估 - 提交的同意現在是否可以接受？ （狀態 = 作用中，期間涵蓋目前日期，可以驗證執行者）。失敗時：ConsentConstrainedMembers。

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

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

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

  • 檢查 1 — 同意狀態：是否Consent.status等於「作用中」？ 如果不是 → ConsentConstrainedMembers。

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

  • 檢查 3 — 執行者驗證：是否可以驗證Consent.performer參考？ 如果在資料存放區中找不到參考的資源，或未與相符的患者相關聯 → ConsentConstrainedMembers。

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

涵蓋範圍比對行為

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

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

同意執行者參考處理

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

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

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

  • 如果執行者驗證失敗 （資源找不到或與相符的患者沒有關聯），成員會放置在 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

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

缺少

payor

存在多個候選項目時的歧義

缺少或多個付款人

relationship

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

缺少

identifier (MB) or subscriberId

主要歧義金鑰

兩者皆不存在

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

scope

確認同意範圍為患者隱私

缺少或沒有病患隱私代碼

category

確認揭露分類

缺少

patient

識別同意主體

缺少

performer

識別誰同意

缺少

sourceReference

記錄同意來源

缺少

policy.uri

決定資料共用範圍

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

provision.type

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

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

provision.period

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

遺失或沒有開始/結束

status

在步驟 4 （非步驟 1) 評估

永遠不會造成步驟 1 失敗 — HealthLake 接受任何有效狀態，並在步驟 4 進行評估

注意

HRex 同意設定檔會定義固定值為「作用中」的狀態。HealthLake 刻意放寬此限制，讓非作用中的同意收到有意義的分類 (ConsentConstrainedMembers)，而不是拒絕括號驗證。

相符行為

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

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

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

錯誤處理

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

  • 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：發生伺服器端處理錯誤的成員計數。