기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 를 사용하여 대규모 리소스 패치 적용 `$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
```
작업 상태를 폴링하려면 설명 엔드포인트를 사용합니다.
```
GET [base]/$bulk-patch/{jobId}
```
`$bulk-patch` 작업을 시작하려면 다음을 수행합니다.
1. 대상 리소스 및 패치 작업을 지정하는 대량 패치 요청을 제출합니다. 응답에는 작업 ID가 포함됩니다.
1. 상태가 `COMPLETED` 또는가 될 때까지 설명 엔드포인트를 사용하여 작업 상태를 폴링합니다`COMPLETED_WITH_ERRORS`.
1. 작업 요약을 검토하여 성공, 실패 또는 건너뛴 리소스 수를 확인합니다.
## 파라미터
`$bulk-patch` 작업은 다음 파라미터를 지원합니다.
| 파라미터 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| resourceType | 문자열 | 예 | 패치할 FHIR 리소스 유형입니다. 예: Patient 또는 Observation. |
| resourceIds | string[] | 아니요 | 패치할 리소스 IDs. 이 파라미터를 생략하면 작업이 지정된 유형의 모든 리소스를 패치합니다. |
| operations | 객체 | 예 | 적용할 패치 작업입니다. JSON 패치 배열 또는 FHIR 패치 Parameters 리소스를 허용합니다. |
| clientToken | 문자열 | No | 멱등성을 보장하는 데 사용되는 사용자 제공 토큰입니다. 동일한 클라이언트 토큰으로 작업을 다시 제출하면 새 작업을 생성하는 대신 기존 작업이 반환됩니다. |
| validationLevel | 문자열 | No | 각 리소스를 업데이트할 때 적용되는 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 는 작업 제출 시 패치 작업 구문을 검증하고 잘못된 페이로드를 동기식으로 거부합니다. 그러나 구문적으로 유효한 패치 작업은 기본 저장 리소스 구조와 일치하지 않는 경우에도 처리 시 실패할 수 있습니다. 대량 패치 작업을 실행하기 전에 동기식 PATCH 작업을 사용하여 대상 리소스의 특성을 이해하고 패치 작업을 테스트합니다. 이를 통해 대규모 장애를 방지할 수 있습니다.
+ **오류를 사용하고 디버깅 이유를 건너뛰었습니다.** 설명 응답의 `failedResources` 및 `skippedResources` 목록을 검토하여 특정 리소스가 패치되지 않은 이유를 이해합니다.
+ **재시도하기 전에 리소스 상태를 확인합니다.** 패치 작업은 본질적으로 멱등성이 없습니다. 동일한 패치를 두 번 적용하면 다른 결과가 생성될 수 있습니다. 예를 들어 이미 존재하는 태그를 추가하면 중복이 생성됩니다. 건너뛰거나 실패한 리소스가 표시되면 재시도 작업을 제출하기 전에 현재 리소스 상태를 확인합니다.
## 권한 부여
`$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) - 지원되는 작업의 전체 목록입니다.