翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# を使用して大規模なリソースにパッチを適用する `$bulk-patch`
AWS HealthLake は、多数の FHIR リソースに非同期的にパッチオペレーションを適用するための `$bulk-patch` オペレーションをサポートしています。ID またはデータストア内の特定のタイプのすべてのリソースで、特定のリソースのリストをターゲットにできます。このオペレーションでは、各リソースを個別に更新することなく、大規模なリソースを変更できます。
`$bulk-patch` オペレーションは、以下を実行する必要がある場合に特に便利です。
+ データストア全体のリソースにメタデータタグまたはラベルを適用する
+ 数千または数百万のリソースの特定のフィールドを更新する
+ バルクデータ修正またはエンリッチメントを実行する
+ コンプライアンス関連の変更をリソースタイプに適用する
+ 大規模なデータ要素の移行または標準化
**注記**
`$bulk-patch` オペレーションは、すべてのターゲットリソースに同じパッチを適用します。個々のリソースを変更するには、PATCH オペレーションを使用します。詳細については、「[PATCH オペレーションによるリソースの変更](managing-fhir-resources-patch.md)」を参照してください。
一括パッチは、各パッチを各リソースにアトミックに適用します。各リソースは個別に成功または失敗します。
ジョブの送信後に削除または変更されたリソースは、同時変更が上書きされないように、パッチではなくスキップされます。
## 使用方法
`$bulk-patch` オペレーションは非同期です。ジョブを開始するには、POST リクエストを送信します。
```
POST [base]/$bulk-patch
```
ジョブのステータスをポーリングするには、describe エンドポイントを使用します。
```
GET [base]/$bulk-patch/{jobId}
```
`$bulk-patch` オペレーションを開始するには、以下を実行します。
1. ターゲットリソースとパッチオペレーションを指定する一括パッチリクエストを送信します。レスポンスにはジョブ ID が含まれます。
1. ステータスが `COMPLETED`または になるまで、describe エンドポイントを使用してジョブステータスをポーリングします`COMPLETED_WITH_ERRORS`。
1. ジョブの概要を確認して、成功、失敗、スキップされたリソースの数を確認します。
## パラメータ
`$bulk-patch` オペレーションでは、次のパラメータがサポートされています。
| パラメータ | タイプ | 必須 | 説明 |
| --- | --- | --- | --- |
| resourceType | 文字列 | はい | パッチを適用する FHIR リソースタイプ。例: Patientまたは Observation。 |
| resourceIds | String[] | いいえ | パッチを適用するリソース IDsのリスト。このパラメータを省略すると、 オペレーションは指定されたタイプのすべてのリソースにパッチを適用します。 |
| operations | オブジェクト | はい | 適用するパッチオペレーション。JSON Patch 配列または FHIR Patch Parametersリソースのいずれかを受け入れます。 |
| clientToken | string | いいえ | べき等性を確保するために使用するユーザー提供のトークン。同じクライアントトークンを使用してジョブを再送信すると、新しいジョブを作成する代わりに既存のジョブが返されます。 |
| validationLevel | string | いいえ | 各リソースを更新するときに適用される FHIR 検証レベル。使用できる値は strict (デフォルト)structure-only、、および ですminimal。 |
## リソースのターゲット設定
リソースは 2 つのモードでターゲットにできます。
**リソースタイプモード**
リソースタイプモードでは、オペレーションはデータストア内の特定のタイプのすべてのリソースにパッチを適用します。
```
{
"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 Patch を使用して特定の`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 モードに完全であり、送信されたリストのサイズと等しくなります。リソースタイプモードでは、ジョブの実行中にリソースを作成または削除できるため、処理されるリソースの実際の数は若干異なる場合があります。
ジョブが終了状態になると、describe レスポンスには、成功、失敗、スキップされたリソースの数の概要が含まれます。リソースが失敗またはスキップされた場合、レスポンスには `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 operation syntax at job submission and rejects invalid payloads synchronously。ただし、構文的に有効なパッチオペレーションは、基盤となるストアドリソース構造と一致しない場合、処理時に失敗する可能性があります。一括パッチジョブを実行する前に、ターゲットリソースの特性を理解し、同期 PATCH オペレーションを使用してパッチオペレーションをテストします。これにより、大規模な障害を回避できます。
+ **エラーとスキップされた理由を使用してデバッグします。**describe レスポンスの `failedResources`および `skippedResources`リストを確認して、特定のリソースにパッチが適用されなかった理由を理解します。
+ **再試行する前にリソースの状態を確認します。**パッチオペレーションは本質的にべき等ではありません。同じパッチを 2 回適用すると、異なる結果が生成されます。たとえば、既に存在するタグを追加すると、重複が作成されます。スキップされたリソースまたは失敗したリソースが表示されたら、再試行ジョブを送信する前に現在のリソースの状態を確認します。
## Authorization
`$bulk-patch` オペレーションは、次の認可方法をサポートしています。
+ AWS プログラムによるアクセスのための Identity and Access Management (IAM) 署名バージョン 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) — 特定のタイプのすべてのリソースを削除します。
+ [HealthLake `$operations`の FHIR R4](reference-fhir-operations.md) — サポートされているオペレーションの完全なリスト。