本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 `$bulk-patch 大规模修补资源`
AWS HealthLake 支持将补丁`$bulk-patch`操作异步应用于大量 FHIR 资源的操作。您可以按 ID 定位特定的资源列表，也可以将数据存储中给定类型的所有资源作为目标。通过此操作，您可以大规模修改资源，而无需单独更新每种资源。
当你需要执行以下`$bulk-patch`操作时，该操作特别有用：
+ 将元数据标签或标签应用于整个数据存储库中的资源
+ 更新成千上万个资源的特定字段
+ 进行批量数据更正或充实
+ 跨资源类型应用与合规性相关的更改
+ 大规模迁移或标准化数据元素
**注意**
该`$bulk-patch`操作将相同的补丁应用于每个目标资源。要修改单个资源，请使用 PATCH 操作。有关更多信息，请参阅 [使用 PATCH 操作修改资源](managing-fhir-resources-patch.md)。
批量补丁将每个补丁自动应用于每个资源。每个资源要么成功，要么独立失败。
作业提交后删除或修改的资源将被跳过而不是修补，以避免覆盖并发的更改。
## 用量
该`$bulk-patch`操作是异步的。要开始作业，请提交 POST 请求：
```
POST [base]/$bulk-patch
```
要轮询任务的状态，请使用描述端点：
```
GET [base]/$bulk-patch/{jobId}
```
要开始`$bulk-patch`操作，请执行以下操作：
1. 提交批量补丁请求，指定目标资源和补丁操作。响应包含任务 ID。
1. 使用描述端点轮询任务状态，直到状态为`COMPLETED`或`COMPLETED_WITH_ERRORS`。
1. 查看作业摘要，了解有多少资源成功、失败或被跳过。
## 参数
该`$bulk-patch`操作支持以下参数。
| 参数 | Type | 必需 | 描述 |
| --- | --- | --- | --- |
| resourceType | 字符串 | 是 | 要修补的 FHIR 资源类型，例如Patient或Observation。 |
| resourceIds | String[] | 否 | 要修补的资源 ID 列表。省略此参数时，该操作会修补指定类型的所有资源。 |
| operations | 对象 | 是 | 要应用的补丁操作。接受 JSON 补丁数组或 FHIR 补丁Parameters资源。 |
| clientToken | 字符串 | 否 | User-provided 用于确保指数等性的代币。使用相同的客户端令牌重新提交任务将返回现有任务，而不是创建新任务。 |
| validationLevel | 字符串 | 否 | 更新每种资源时应用的 FHIR 验证级别。可接受的值是strict（默认）structure-only、和minimal。 |
## 定位资源
您可以采用两种模式来定位资源。
**资源类型模式**
在资源类型模式下，该操作会修补数据存储库中特定类型的所有资源。
```
{
"resourceType": "Patient",
"operations": { ... }
}
```
**资源 ID 模式**
在资源 ID 模式下，该操作按 ID 修补特定的资源列表。所有资源 ID 必须是相同类型且与`resourceType`参数相匹配。格式可以是完整参考文献 (`[resourceType]/[id]`)，也可以只是 ID (`[id]`)。该列表最多可包含 50,000 个资源 ID。
```
{
"resourceType": "Patient",
"resourceIds": ["Patient/001", "Patient/002", "Patient/003"],
"operations": { ... }
}
```
## 支持的补丁格式
该`$bulk-patch`操作支持 JSON 补丁 (RFC 6902) 和 FHIR 补丁 () 语法。FHIRPath-based它使用与同步 PATCH 操作相同的支持操作集和相同的语法。有关更多信息，请参阅 [使用 PATCH 操作修改资源](managing-fhir-resources-patch.md)。
## 启动批量补丁任务示例
以下示例提交了批量补丁作业，该任务使用 FHIR 补丁向特定`Patient`资源添加合规性标签。
**请求示例**
```
POST [base]/$bulk-patch
Content-Type: application/json
{
"resourceType": "Patient",
"resourceIds": ["patient-1", "patient-2", "patient-3"],
"validationLevel": "strict",
"clientToken": "unique-idempotency-token-123",
"operations": {
"resourceType": "Parameters",
"parameter": [
{
"name": "operation",
"part": [
{"name": "type", "valueCode": "add"},
{"name": "path", "valueString": "Patient.meta"},
{"name": "name", "valueString": "tag"},
{"name": "value", "valueCoding": {
"system": "http://example.org/compliance",
"code": "2026-audit-complete"
}}
]
}
]
}
}
```
**响应示例**
```
{
"datastoreId": "datastoreId",
"jobId": "jobId",
"jobStatus": "SUBMITTED"
}
```
## 批量补丁任务状态轮询
提交任务后，轮询任务状态以跟踪进度并检索结果。作业通过`SUBMITTED`和`IN_PROGRESS`，然后过渡到`COMPLETED`或的终端状态`COMPLETED_WITH_ERRORS`。
```
GET [base]/$bulk-patch/{jobId}
```
以下示例显示了对正在进行的任务的响应。
```
{
"datastoreId": "datastoreId",
"jobId": "jobId",
"status": "IN_PROGRESS",
"submittedTime": "2026-09-14T06:53:31.429Z",
"summary": {
"estimatedResourceCount": 1000
}
}
```
**注意**
对于资源 ID 模式，`estimatedResourceCount`是完全正确的，等于提交的列表的大小。对于资源类型模式，实际处理的资源数量可能略有不同，因为可以在作业运行时创建或删除资源。
当任务达到终端状态时，描述响应包括成功、失败和跳过的资源的计数摘要。如果有任何资源出现故障或被跳过，响应会在`failedResources`和`skippedResources`中列出原因。任务状态是指出现任何故障`COMPLETED_WITH_ERRORS`时，无论是客户错误还是服务器错误。响应大小限制了`failedResources`和`skippedResources`列表，因此它们可能会被截断。检查`failedResourcesTruncated`并`skippedResourcesTruncated`确定完整清单是否包括在内。
```
{
"datastoreId": "datastoreId",
"jobId": "jobId",
"status": "COMPLETED_WITH_ERRORS",
"submittedTime": "2026-09-14T06:53:31.429Z",
"endTime": "2026-09-14T07:08:34.930Z",
"summary": {
"estimatedResourceCount": 1000,
"totalResourcesProcessed": 1000,
"succeeded": 985,
"failedWithCustomerError": 5,
"failedWithServerError": 0,
"skipped": 10
},
"failedResources": [
{
"resourceId": "Patient/patient-101",
"message": "FHIR resource in payload failed FHIR validation rules."
}
],
"skippedResources": [
{
"resourceId": "Patient/patient-201",
"message": "Resource was modified after job submission"
},
{
"resourceId": "Patient/patient-202",
"message": "Resource was deleted."
},
{
"resourceId": "Patient/patient-203",
"message": "Resource not found."
}
],
"failedResourcesTruncated": false,
"skippedResourcesTruncated": false
}
```
## 常见的跳过原因
该操作会在资源处于作用域内时跳过该资源，但无法修补该资源，因为该资源的状态在任务提交和处理之间发生了变化。跳过的资源不被视为错误。以下是跳过资源的常见原因。
+ **提交任务后对资源进行了修改 **-批量补丁作业在提交时捕获其版本后，资源由另一项操作更新。在极少数情况下，成功修补的资源可能会被报告为跳过，提交作业后原因会被修改。这是预料之中的，而且可能以非常低的速度（百万分之一的资源）发生。
+ **任务提交后资源被删除 **-提交任务后资源被删除（资源类型模式）。并非所有已删除的资源都能保证出现在跳过的列表中。如果在作业开始处理之前删除了资源，则该资源将被完全排除在任务范围之外，也不会反映在作业结果中。
+ **资源已删除 **-指定的资源 ID 处于删除状态（资源 ID 模式）。
+ **未找到资源 **-指定的资源 ID 不存在（仅限资源 ID 模式）。
## 常见的客户故障
当由于资源或补丁操作出现问题而导致操作无法应用补丁时，资源会失败。失败的资源包括一条带有诊断详细信息的错误消息。以下是常见的客户故障。
+ **FHIR 验证失败 **-打补丁的资源未通过 FHIR 验证。批量补丁对整个打补丁的资源应用 FHIR 验证，而不仅仅是修改后的字段。当补丁生成的字段值无效，或者资源已经包含不符合 FHIR 的字段时，就会发生这种故障。使用`validationLevel`参数控制验证的严格性。
+ **补丁应用程序故障 **-补丁操作与资源结构不兼容，例如，替换不存在的字段或添加到非数组路径。
## 最佳实践
我们建议您在使用该`$bulk-patch`操作时采用以下最佳做法。
+ **首先使用同步 PATCH 进行测试。** AWS HealthLake 在提交任务时验证补丁操作语法并同步拒绝无效的有效负载。但是，如果语法上有效的补丁操作与底层存储资源结构不匹配，则在处理时仍会失败。在运行批量补丁作业之前，了解目标资源的特征并使用同步 PATCH 操作测试补丁操作。这可以帮助您避免大规模故障。
+ **使用错误和跳过的原因进行调试。**查看描述响应中的`failedResources`和`skippedResources`列表，了解未修补特定资源的原因。
+ **在重试之前验证资源状态。**补丁操作本质上不是等效的。两次应用同一个补丁会产生不同的结果，例如，添加已经存在的标签会产生副本。看到跳过或失败的资源后，请在提交重试任务之前验证当前资源状态。
## Authorization
该`$bulk-patch`操作支持以下授权方法：
+ AWS 用于编程访问的身份和访问管理 (IAM) 签名版本 4 (SigV4)。
+ FHIR 上的 SMART 具有以下所需范围：
+ **范围级别 **-仅支持系统级范围。该手术拒绝了患者级别和用户级别的范围。
+ **资源类型 **-范围必须与任务目标的资源类型相匹配。
+ **操作 ** — 所需的范围取决于作业模式和 SMART 版本：
+ **启动任务（资源类型模式）**— SMART v1 要求`read`和`write`范围。SMART v2 数据存储库的要求`search`和`update`范围。
+ **启动任务（资源 ID 模式）**— SMART v1 要求`read`和`write`范围。SMART v2 数据存储库的要求`read`和`update`范围。
+ **描述工作 **-需要`read`范围。
## 性能特征
该`$bulk-patch`操作专为高容量处理而设计，并异步运行。
+ **并发 **-每个数据存储最多支持 1 个并发批量补丁作业。该操作会将其他任务排入队列，并在当前任务完成时自动启动它们。
+ **可扩展性 ** — 每项任务支持多达 20 亿个资源。该操作会拒绝超过此限制的作业。此限制可防止延长处理时间，在此期间许多资源可以更改状态，并避免长时间保持数据存储任务并发性。使用资源 ID 模式对工作负载进行分区。任务超出支持的规模时的响应示例：
```
"status": "COMPLETED_WITH_ERRORS",
"message": "The requested bulk patch operation exceeds the supported scale."
```
+ **并行操作 **-批量补丁与同一数据存储库上的并行批量删除、导入或导出操作不兼容。
+ **取消 ** — 批量补丁任务提交后无法取消。
## 相关 操作
+ [使用 PATCH 操作修改资源](managing-fhir-resources-patch.md)— 使用 JSON Single-resource 补丁或 FHIR 补丁进行补丁。
+ [使用删除资源类型 `$bulk-delete`](reference-fhir-operations-bulk-delete.md)— 删除特定类型的所有资源。
+ [FHIR R4 $运营`用于` HealthLake](reference-fhir-operations.md)— 支持的操作的完整列表。