View a markdown version of this page

$bulk-member-match操作为 HealthLake - AWS HealthLake
用法支持的参数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 调用并提高大批量匹配场景的运营效率

用法

该$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 请求。每个成员都封装在包含必需的MemberPatientCoverageToMatch、和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 Parameters 资源，其中包含三个对匹配结果进行分类的组资源。

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

包含所有成功匹配成员的患者推荐信息，且未被归类为同意限制。

该Group.quantity字段包含其各自组中的成员总数。

NonMatchedMembers Group

包含对未找到匹配项或发现多个匹配项的成员的引用。

ConsentConstrainedMembers Group

包含所有成功匹配成员的患者推荐信息，这些成员的同意限制会阻止数据共享。当同时满足以下两个条件时，同意资源被视为受限：

  • 策略 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 签名版本 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：出现服务器端处理错误的成员数。