本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 大規模修補資源 `$bulk-patch`
AWS HealthLake 支援以非同步方式將修補程式操作套用至大量 FHIR 資源`$bulk-patch`的操作。您可以依 ID 或資料存放區中指定類型的所有資源，將特定資源清單設為目標。透過此操作，您可以大規模修改資源，而無需個別更新每個資源。
當您需要執行下列動作時， `$bulk-patch`操作特別有用：
+ 將中繼資料標籤或標籤套用至整個資料存放區的資源
+ 在數千或數百萬個資源上更新特定欄位
+ 執行大量資料更正或擴充
+ 在資源類型之間套用合規相關變更
+ 大規模遷移或標準化資料元素
**注意**
`$bulk-patch` 操作會將相同的修補程式套用至每個目標資源。若要修改個別資源，請使用 PATCH 操作。如需詳細資訊，請參閱[使用 PATCH 操作修改資源](managing-fhir-resources-patch.md)。
大量修補程式會以原子方式將每個修補程式套用至每個資源。每個資源都會獨立成功或失敗。
在提交任務後刪除或修改的資源會略過而非修補，以避免覆寫並行變更。
## Usage
`$bulk-patch` 操作是非同步的。若要開始任務，請提交 POST 請求：
```
POST [base]/$bulk-patch
```
若要輪詢任務的狀態，請使用描述端點：
```
GET [base]/$bulk-patch/{jobId}
```
若要開始使用 `$bulk-patch`操作，請執行下列動作：
1. 提交大量修補程式請求，以指定目標資源和修補程式操作。回應包含任務 ID。
1. 使用描述端點輪詢任務狀態，直到狀態為 `COMPLETED`或 `COMPLETED_WITH_ERRORS`。
1. 檢閱任務摘要，以查看成功、失敗或略過的資源數量。
## Parameters
`$bulk-patch` 操作支援下列參數。
| 參數 | Type | 必要 | 描述 |
| --- | --- | --- | --- |
| resourceType | string | 是 | 要修補的 FHIR 資源類型，例如 Patient或 Observation。 |
| resourceIds | string【】 | 否 | 要修補的資源 IDs清單。當您省略此參數時， 操作會修補指定類型的所有資源。 |
| operations | object | 是 | 要套用的修補程式操作。接受 JSON 修補程式陣列或 FHIR 修補程式Parameters資源。 |
| clientToken | string | 否 | 使用者提供的字符，用於確保冪等性。使用相同的用戶端字符重新提交任務會傳回現有的任務，而不是建立新的任務。 |
| validationLevel | string | 否 | 更新每個資源時套用的 FHIR 驗證層級。接受的值為 strict（預設值）structure-only、 和 minimal。 |
## 以資源為目標
您可以透過兩種模式將資源設為目標。
**資源類型模式**
在資源類型模式中， 操作會修補資料存放區中特定類型的所有資源。
```
{
"resourceType": "Patient",
"operations": { ... }
}
```
**資源 IDs 模式**
在資源 IDs模式中， 操作會依 ID 修補特定資源清單。所有資源 IDs都必須是相同的類型，且符合 `resourceType` 參數。格式可以是完整參考 (`[resourceType]/[id]`) 或僅限 ID (`[id]`)。清單最多可包含 50，000 IDs。
```
{
"resourceType": "Patient",
"resourceIds": ["Patient/001", "Patient/002", "Patient/003"],
"operations": { ... }
}
```
## 支援的修補程式格式
`$bulk-patch` 此操作同時支援 JSON 修補程式 (RFC 6902) 和 FHIR 修補程式 (FHIRPath 型） 語法。它使用與同步 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
}
}
```
**注意**
`estimatedResourceCount` 完全適用於資源 IDs 模式，且等於提交清單的大小。對於資源類型模式，實際處理的資源數量可能會略有不同，因為可在任務執行時建立或刪除資源。
當任務達到結束狀態時，描述回應會包含成功、失敗和略過資源的計數摘要。如果任何資源失敗或被略過，回應會列出 `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
}
```
## 常見的略過原因
當資源在範圍內但無法修補資源時，此操作會略過資源，因為其狀態會在任務提交和處理之間變更。略過的資源不會被視為錯誤。以下是略過資源的常見原因。
+ 在**提交任務後修改資源** — 在大量修補程式任務在提交時擷取其版本後，資源已由另一個操作更新。在極少數情況下，成功修補的資源可能會報告為略過，並在任務提交後修改原因。這是預期的，而且可能以非常低的速率發生 （數百萬個資源中的 1 個）。
+ 在**提交任務後刪除資源** — 在提交任務後刪除資源 （資源類型模式）。並非所有已刪除的資源都保證會出現在略過的清單中。如果在任務開始處理之前刪除資源，則會完全從任務範圍中排除，而不會反映在任務結果中。
+ **資源已刪除** — 指定的資源 ID 處於已刪除狀態 （資源 IDs 模式）。
+ **找不到資源** — 指定的資源 ID 不存在 （僅限資源 IDs 模式）。
## 常見的客戶故障
當操作因為資源或修補程式操作的問題而無法套用修補程式時，資源會失敗。失敗的資源包含含有診斷詳細資訊的錯誤訊息。以下是常見的客戶故障。
+ **FHIR 驗證失敗** — 修補的資源未通過 FHIR 驗證。大量修補程式會在整個修補的資源上套用 FHIR 驗證，而不只是修改的欄位。當修補程式產生無效的欄位值，或資源已包含不符合 FHIR 規範的欄位時，就會發生此失敗。使用 `validationLevel` 參數來控制驗證嚴格性。
+ **修補程式應用程式失敗** — 修補程式操作與資源結構不相容，例如取代不存在的欄位，或新增至非陣列路徑。
## 最佳實務
當您使用 `$bulk-patch`操作時，我們建議您採用下列最佳實務。
+ **使用同步 PATCH first.** AWS HealthLake validates 測試任務提交時的修補程式操作語法，並同步拒絕無效的承載。不過，如果語法有效的修補程式操作不符合基礎預存資源結構，則仍然可能會在處理時間失敗。了解目標資源的特性，並在執行大量修補程式任務之前，使用同步 PATCH 操作測試您的修補程式操作。這可協助您避免大規模故障。
+ **使用錯誤並略過除錯原因。**檢閱描述回應中的 `failedResources`和 `skippedResources`清單，以了解為何未修補特定資源。
+ **在重試之前驗證資源狀態。**修補程式操作本質上不是等冪的。套用相同的修補程式兩次可能會產生不同的結果，例如，新增已存在的標籤會建立重複的標籤。在您看到略過或失敗的資源後，請先驗證目前的資源狀態，再提交重試任務。
## Authorization
`$bulk-patch` 操作支援下列授權方法：
+ AWS 用於程式設計存取的 Identity and Access Management (IAM) Signature 第 4 版 (SigV4)。
+ FHIR 上的 SMART 具有下列必要範圍：
+ **範圍層級** — 僅支援系統層級範圍。操作會拒絕病患層級和使用者層級範圍。
+ **資源類型** — 範圍必須符合任務目標的資源類型。
+ **操作** — 所需的範圍取決於任務模式和 SMART 版本：
+ **啟動任務 （資源類型模式）** — SMART v1 需要 `read`和 `write`範圍。SMART v2 資料存放區需要 `search`和 `update`範圍。
+ **啟動任務 （資源 IDs 模式）** — SMART v1 需要 `read`和 `write`範圍。SMART v2 資料存放區需要 `read`和 `update`範圍。
+ **描述任務** — 需要 `read`範圍。
## 效能特性
`$bulk-patch` 操作專為大量處理而設計，並以非同步方式執行。
+ **並行** — 每個資料存放區最多支援 1 個並行大量修補任務。操作會將其他任務排入佇列，並在目前任務完成時自動啟動這些任務。
+ **可擴展性** — 每個任務最多可支援 20 億個資源。操作會拒絕超過此限制的任務。此限制可防止較長的處理時間，在此期間許多資源可以變更狀態，並避免長時間保留資料存放區任務並行。使用資源 IDs 模式來分割工作負載。當任務超過支援的擴展時的範例回應：
```
"status": "COMPLETED_WITH_ERRORS",
"message": "The requested bulk patch operation exceeds the supported scale."
```
+ **平行操作** — 大量修補程式與相同資料存放區上的並行大量刪除、匯入或匯出操作不相容。
+ **取消** — 大量修補任務提交後就無法取消。
## 相關的 操作
+ [使用 PATCH 操作修改資源](managing-fhir-resources-patch.md) — 使用 JSON 修補程式或 FHIR 修補程式的單一資源修補程式。
+ [使用 刪除資源類型 `$bulk-delete`](reference-fhir-operations-bulk-delete.md) — 刪除特定類型的所有資源。
+ [`$operations` 適用於 HealthLake 的 FHIR R4](reference-fhir-operations.md) — 支援操作的完整清單。