通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

对 FHIR 数据执行批量更新

该$bulk-update操作允许您使用异步处理进行批量更新多个 FHIR 资源。 它支持：

  • 所有资源类型的系统级更新
  • 限定于特定资源类型的更新
  • 单个请求中的多资源操作

注释

请谨慎使用 $bulk-update 的操作。 已更新的资源在提交后无法回滚。 建议首先使用与批量更新作业相同的参数运行 FHIR 搜索，以验证要更新的数据。

该$bulk-update操作使用下面列出的受支持的补丁类型来执行更新。

  • replace：替换现有值。 它利用 FHIR Patch 的“替换”语义，确保更新保持幂等性
  • upsert：如果值不存在，则添加一个值；如果值已存在，则替换该值。

注释

不支持其他修补操作（例如：添加、移动、删除、插入）。

批量更新操作的必要先决条件

必需的角色

若要执行批量更新，必须为应用程序或用户分配以下角色之一：

  • FHIR 数据批量操作符：提供对 FHIR 服务中的批量操作的访问权限。
  • FHIR 数据参与者：对 FHIR 服务的管理访问权限。

所需标头

Header 价值
Accept application/fhir+json
偏好 异步响应

请求

可以在请求中使用 FHIR 搜索参数。 批量更新操作支持标准搜索筛选器，例如：address:contains=Meadow 或 Patient.birthdate=1987-02-20。 还可以使用_include、_revinclude和_not-referenced来扩展搜索条件。

请求示例

  1. 系统级批量更新：在系统级别执行操作，使能对 FHIR 服务器上所有的资源类型中的 FHIR 资源进行更新。

PATCH https://{FHIR-SERVICE-HOST}/$bulk-update

  1. 范围限为单个资源类型的更新：如果对单个资源类型执行此操作，可更新映射到 URL 中的资源类型的 FHIR 资源。

PATCH https://{FHIR-SERVICE-HOST}/[ResourceType]/$bulk-update

  1. 根据搜索参数查询待更新的资源。 在此示例中，我们将使用 _include 并 _revinclude 更新 2021-12-18 之前更新的所有患者资源，以及引用这些资源的所有资源：

PATCH {FHIR-SERVICE-HOST}/Patient/$bulk-update?_lastUpdated=lt2021-12-18&_revinclude=*

PATCH {FHIR-SERVICE-HOST}/DiagnosticReport/$bulk-update?_lastUpdated=lt2021-12-12&_include=DiagnosticReport:based-on:ServiceRequest&_include:iterate=ServiceRequest:encounter

在对 FHIR 搜索参数使用批量更新时，请考虑先在 FHIR 搜索中使用同一查询，以便可以验证计划更新的数据。

下面是一个示例请求正文。

{ 
  "resourceType": "Parameters", 
  "parameter": [ 
    { 
      "name": "operation", 
      "part": [ 
        { 
          "name": "type", 
          "valueCode": "upsert" 
        }, 

        { 
          "name": "path", 
          "valueString": "Resource.meta" 
        }, 

        { 
          "name": "name", 
          "valueString": "security" 
        }, 

        { 
          "name": "value", 
          "valueCoding": { 
            "system": "http://example.org/security-system", 
            "code": "SECURITY_TAG_CODE", 
            "display": "Updated Security Tag Display" 
          } 
        } 
      ] 
    } 
  ] 
}

要点

  • 每个补丁路径必须以 ResourceType 根（例如 Patient.meta.tag）开头，以明确区分元级别更新和元素更新。 可以使用资源根来修补通用属性。 可以在系统级别、单个资源类型或多个资源类型执行批量更新。 如果需要更新不同资源类型的不同字段，可以在单独的操作中指定字段与值的映射。
  • 如果搜索返回多个资源类型，则修补程序仅应用于其类型与修补路径中的前缀匹配 ResourceType 的资源;将忽略其他类型。
  • SearchParameter 并 StructureDefinition 被视为批量更新的作用域外。 如果按资源类型在 SearchParameter 或 StructureDefinition 上运行批量更新作业，也会导致“400 错误请求”错误。 如果系统或资源类型级别的批量更新查询返回类型SearchParameter或StructureDefinition的资源，在操作期间将忽略这些资源。 只会更新其他资源类型。

响应

提交批量更新操作时，将返回以下格式的响应，其中Content-Location标头指向轮询终结点。

Content-Location: https://{hostname}/_operations/bulk-update/{job-id}

轮询终结点结果

根据批量更新作业的状态，对轮询终结点的请求将导致 4 个结果中的一个。 结果在 FHIR 响应的 OperationOutcome 中提供。

状态 Description
202 正在进行的作业
200 用户已完成或取消的作业
Other 基于错误类型的失败状态

对批量更新作的响应包括四个关键组件：

  1. ResourceUpdatedCount：显示已成功更新的资源数，按资源类型分组。
  2. ResourceIgnoredCount：按资源类型指示批量更新期间忽略的资源数。 如果没有相应类型的 Patch 请求，或者它们属于被排除的类型（例如 SearchParameter 或 StructureDefinition），则忽略这些资源。
  3. ResourcePatchFailedCount：按资源类型显示修补作失败的资源数。 例如，如果尝试替换不存在的值，则修补程序将失败并计算在此处。 如果某些资源失败，但其他资源失败，则作业被视为“软失败”。 “问题”部分中提供了一条通用消息，建议对单个资源使用 FHIR PATCH 操作以获取详细的错误信息。
  4. 问题：提供有关任何作业失败或失败更新原因的详细信息。

下面是一个示例响应体。

{ 

  "resourceType": "Parameters", 

  "parameter": [ 
    { 
      "name": "ResourceUpdatedCount", 
      "part": [ 
        { "name": "Practitioner", "valueInteger64": 10 }, 
        { "name": "Specimen", "valueInteger64": 7 }, 
        { "name": "Device", "valueInteger64": 3 } 
      ] 
    }, 

    { 
      "name": "ResourceIgnoredCount", 
      "part": [ 
        { "name": "StructureDefinition", "valueInteger64": 9 }, 
        { "name": "SearchParameter", "valueInteger64": 8 } 
      ] 
    } 
  ] 
}

响应错误处理

HTTP 状态 原因 Action
400 已在运行中的作业、不受支持的操作类型或已排除的资源类型。 一次只能运行一个批量更新作业。 如果在一个作业进行时尝试启动另一个作业，将导致“400 错误请求”错误。 解决冲突后重试。
403 未经 授权 分配所需的角色。
429 已中止 使用减少负载重试。
500 服务器错误 创建支持票证。
503 数据库问题 请稍后重试。

取消批量更新作业

将 DELETE 请求发送到作业的轮询终结点，如下所示。

DELETE https://{FHIR-SERVICE-HOST}/_operations/bulk-update/{job-id}

注释

取消作业后，若重试则会上次中断的位置继续执行删除流程。

审核日志

可以从 MicrosoftHealthcareApisAuditLogs 查询审核日志：

  • 依据 ResourceId 筛选。
  • 在记录中查找：作业已启动、作业已成功和补丁失败。

FAQ

为什么更新的资源计数与预期不匹配？

  • 更少：在运行此作业之前，资源可能已被另一个作业修改。
  • 更多：启动批量更新后，新的导入作业可能已插入资源。

如果批量更新作业似乎停滞不前，如何解决这个问题的步骤有哪些？ 若要检查批量更新作业是否停滞，请使用与批量更新作业相同的参数运行 FHIR 搜索，在查询中添加适当的操作条件，并包括_summary=count。 如果资源计数下降，则表明作业正在进行。 还可以取消批量更新作业，然后重试。

批量更新作业并发执行时，对 REST API 调用有什么影响？ 运行批量更新作时，可能会看到对服务的并发调用延迟增加。 为了避免延迟增加，建议取消批量更新作业，然后在流量较低的时间段内重新运行它。

是否可还原更改？ 应仔细使用批量更新功能。 例如，如果启用了版本控制，请提取历史版本，并使用 PUT 还原它们，或从备份还原（数据保留 7-30 天，具体取决于配置）。

什么是 ResourcePatchFailedCount？ 这是在 PATCH 操作期间失败的资源计数。 原因可能包括：

  • 替换不存在的元素
  • 尝试更新不可变字段

检查审核日志或单独提交 PATCH 请求以获取错误详细信息。

后续步骤

  • Last updated on