기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 에서 FHIR 리소스 관리 AWS HealthLake
FHIR R4 RESTful API 상호 작용을 사용하여 HealthLake 데이터 스토어에서 FHIR 리소스를 관리합니다. 다음 섹션에서는 FHIR 리소스 관리에 사용할 수 있는 모든 HealthLake 지원 FHIR R4 RESTful API 상호 작용을 설명합니다. HealthLake 데이터 스토어 기능과 지원하는 FHIR 사양의 부분에 대한 자세한 내용은 섹션을 참조하세요[에 대한 FHIR R4 기능 설명 AWS HealthLake](reference-fhir-capability-statement.md).
**참고**
이 장에 나열된 FHIR 상호 작용은 의료 데이터 교환을 위한 HL7 FHIR R4 표준을 준수하도록 구축되었습니다. HL7 FHIR 서비스의 표현이므로 AWS CLI 및 AWS SDKs 통해 제공되지 않습니다. 자세한 내용은 FHIR [R4 RESTful API](https://hl7.org/fhir/R4/http.html) 설명서의 RESTful API를 참조하세요. ** R4 RESTful **
다음 표에는에서 지원하는 FHIR R4 상호 작용이 나열되어 있습니다 AWS HealthLake. HealthLake에서 지원하는 FHIR *리소스 유형에* 대한 자세한 내용은 섹션을 참조하세요[조건 키](reference-fhir-resource-types.md).
**에서 지원하는 FHIR R4 상호 작용 AWS HealthLake**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/healthlake/latest/devguide/managing-fhir-resources.html)
**Topics**
+ [FHIR 리소스 생성](managing-fhir-resources-create.md)
+ [FHIR 리소스 읽기](managing-fhir-resources-read.md)
+ [FHIR 리소스 기록 읽기](managing-fhir-resources-read-history.md)
+ [FHIR 리소스 업데이트](managing-fhir-resources-update.md)
+ [PATCH 작업을 사용하여 리소스 수정](managing-fhir-resources-patch.md)
+ [FHIR 리소스 번들링](managing-fhir-resources-bundle.md)
+ [FHIR 리소스 삭제](managing-fhir-resources-delete.md)
+ [자격 증명 및 동시성](managing-fhir-resources-idempotency.md)
# FHIR 리소스 생성
FHIR `create` 상호 작용은 HealthLake 데이터 스토어에 새 FHIR 리소스를 생성합니다. 자세한 내용은 **FHIR R4 RESTful API 설명서**[https://hl7.org/fhir/R4/http.html#create](https://hl7.org/fhir/R4/http.html#create)의 섹션을 참조하세요.
**FHIR 리소스를 생성하려면**
1. HealthLake `region` 및 `datastoreId` 값을 수집합니다. 자세한 내용은 [데이터 스토어 속성 가져오기](managing-data-stores-describe.md) 단원을 참조하십시오.
1. `Resource` 생성할 FHIR 유형을 결정합니다. 자세한 내용은 [조건 키](reference-fhir-resource-types.md) 단원을 참조하십시오.
1. HealthLake `region` 및에 대해 수집된 값을 사용하여 요청에 대한 URL을 구성합니다`datastoreId`. 생성할 FHIR `Resource` 유형도 포함합니다. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다.
```
POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource
```
1. 요청에 대한 JSON 본문을 구성하여 새 리소스에 대한 FHIR 데이터를 지정합니다. 이 절차의 목적상 FHIR `Patient` 리소스를 사용하므로 파일을 로 저장합니다`create-patient.json`.
```
{
"resourceType": "Patient",
"identifier": [
{
"system": "urn:oid:1.2.36.146.595.217.0.1",
"value": "12345"
}
],
"name": [
{
"family": "Silva",
"given": [
"Ana",
"Carolina"
]
}
],
"gender": "female",
"birthDate": "1992-02-10"
}
```
1. 요청을 보냅니다. FHIR `create` 상호 작용은 FHIR 권한 부여 시 [AWS 서명 버전 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 또는 SMART와 함께 `POST` 요청을 사용합니다. 다음 예제에서는 curl 또는 HealthLake 콘솔을 사용하여 HealthLake에서 FHIR `Patient` 리소스를 생성합니다. 전체 예제를 보려면 **복사** 버튼을 스크롤합니다.
------
#### [ SigV4 ]
SigV4 권한 부여
```
curl --request POST \
'https://healthlake.region.amazonaws.com/datastore/datastore-id/r4/Patient' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json' \
--data @create-patient.json
```
------
#### [ SMART on FHIR ]
[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 데이터 형식에 대한 SMART on FHIR 권한 부여 예제입니다.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
호출자는 권한 부여 Lambda에서 권한을 할당할 수 있습니다. 자세한 내용은 [OAuth 2.0 범위](reference-smart-on-fhir-oauth-scopes.md) 단원을 참조하십시오.
------
#### [ AWS Console ]
**참고**
HealthLake 콘솔은 [AWS SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 권한 부여만 지원합니다.
1. HealthLake 콘솔의 [쿼리 실행](https://console.aws.amazon.com/healthlake/home#/crud) 페이지에 로그인합니다.
2. **쿼리 설정** 섹션에서 다음을 선택합니다.
+ **데이터 스토어 ID** - 쿼리 문자열을 생성할 데이터 스토어 ID를 선택합니다.
+ **쿼리 유형** -를 선택합니다`Create`.
+ **리소스 유형** - 생성할 FHIR [리소스 유형을](reference-fhir-resource-types.md) 선택합니다.
+ **요청 본문** - 새 리소스에 대한 FHIR 데이터를 지정하여 요청에 대한 JSON 본문을 구성합니다.
3. **쿼리 실행**을 선택합니다.
------
**리소스 생성을 위한 검증 수준 구성**
FHIR 리소스를 생성할 때 선택적으로 `x-amzn-healthlake-fhir-validation-level` HTTP 헤더를 지정하여 리소스에 대한 검증 수준을 구성할 수 있습니다.는 AWS HealthLake 현재 다음 검증 수준을 지원합니다.
+ `strict`: 리소스는 리소스의 프로필 요소 또는 프로필이 없는 경우 R4 사양에 따라 검증됩니다. 이는에 대한 기본 검증 수준입니다 AWS HealthLake.
+ `structure-only`: 리소스는 R4에 대해 검증되며 참조된 프로파일은 무시합니다.
+ `minimal`: 리소스는 특정 R4 규칙을 무시하면서 최소한으로 검증됩니다. 검색/분석에 필요한 구조 검사에 실패한 리소스는 감사 경고를 포함하도록 업데이트됩니다.
최소 검증 수준으로 생성된 리소스는 검색 인덱싱에 필요한 검증에 실패하더라도 데이터 스토어에 수집될 수 있습니다. 이 경우 해당 실패를 문서화하기 위한 Healthlake별 확장을 포함하도록 리소스가 업데이트됩니다.
```
{
"url": "http://healthlake.amazonaws.com/fhir/StructureDefinition/validation-issue",
"valueString": "{\"resourceType\":\"OperationOutcome\",\"issue\":[{\"severity\":\"error\",\"code\":\"processing\",\"details\":{\"text\":\"FHIR resource in payload failed FHIR validation rules.\"},\"diagnostics\":\"FHIR resource in payload failed FHIR validation rules.\"}]}"
}
```
또한 다음 HTTP 응답 헤더는 "true" 값과 함께 포함됩니다.
```
x-amzn-healthlake-validation-issues : true
```
**참고**
R4 사양에 따라 잘못된 형식으로 수집된 데이터는 이러한 오류가 있는 경우 예상대로 검색하지 못할 수 있습니다.
# FHIR 리소스 읽기
FHIR `read` 상호 작용은 HealthLake 데이터 스토어에서 리소스의 현재 상태를 읽습니다. 자세한 내용은 **FHIR R4 RESTful API 설명서**[https://hl7.org/fhir/R4/http.html#read](https://hl7.org/fhir/R4/http.html#read)의 섹션을 참조하세요.
**FHIR 리소스를 읽으려면**
1. HealthLake `region` 및 `datastoreId` 값을 수집합니다. 자세한 내용은 [데이터 스토어 속성 가져오기](managing-data-stores-describe.md) 단원을 참조하십시오.
1. 연결된 `id` 값을 `Resource` 읽고 수집할 FHIR 유형을 결정합니다. 자세한 내용은 [조건 키](reference-fhir-resource-types.md) 단원을 참조하십시오.
1. HealthLake `region` 및에 대해 수집된 값을 사용하여 요청에 대한 URL을 구성합니다`datastoreId`. FHIR `Resource` 유형 및 관련 도 포함합니다`id`. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id
```
1. 요청을 보냅니다. FHIR `read` 상호 작용은 FHIR 권한 부여 시 [AWS 서명 버전 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 또는 SMART와 함께 `GET` 요청을 사용합니다. 다음 `curl` 예제에서는 HealthLake에서 FHIR `Patient` 리소스의 현재 상태를 읽습니다. 전체 예제를 보려면 **복사** 버튼을 스크롤합니다.
------
#### [ SigV4 ]
SigV4 권한 부여
```
curl --request GET \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json'
```
------
#### [ SMART on FHIR ]
[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 데이터 형식에 대한 SMART on FHIR 권한 부여 예제입니다.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
호출자는 권한 부여 Lambda에 권한을 할당할 수 있습니다. 자세한 내용은 [OAuth 2.0 범위](reference-smart-on-fhir-oauth-scopes.md) 단원을 참조하십시오.
------
#### [ AWS Console ]
1. HealthLake 콘솔의 [쿼리 실행](https://console.aws.amazon.com/healthlake/home#/crud) 페이지에 로그인합니다.
2. **쿼리 설정** 섹션에서 다음을 선택합니다.
+ **데이터 스토어 ID** - 쿼리 문자열을 생성할 데이터 스토어 ID를 선택합니다.
+ **쿼리 유형** -를 선택합니다`Read`.
+ **리소스 유형** - 읽을 FHIR [리소스 유형을](reference-fhir-resource-types.md) 선택합니다.
+ **리소스 ID** - FHIR 리소스 ID를 입력합니다.
3. **쿼리 실행**을 선택합니다.
------
# FHIR 리소스 기록 읽기
FHIR `history` 상호 작용은 HealthLake 데이터 스토어에서 특정 FHIR 리소스의 기록을 검색합니다. 이 상호 작용을 사용하여 시간이 지남에 따라 FHIR 리소스의 내용이 어떻게 변경되었는지 확인할 수 있습니다. 또한 감사 로그와 협력하여 수정 전후의 리소스 상태를 확인하는 데 유용합니다. FHIR 상호 작용 `create`, `update`및를 `delete` 수행하면 리소스의 기록 버전이 저장됩니다. 자세한 내용은 **FHIR R4 RESTful API 설명서**[https://hl7.org/fhir/R4/http.html#history](https://hl7.org/fhir/R4/http.html#history)의 섹션을 참조하세요.
**참고**
특정 FHIR 리소스 유형에 `history` 대해 옵트아웃할 수 있습니다. 옵트아웃하려면를 사용하여 사례를 생성합니다[AWS Support Center Console](https://console.aws.amazon.com/support/home#/). 사례를 생성하려면에 로그인 AWS 계정 하고 **사례 생성을** 선택합니다.
**FHIR 리소스 기록을 읽으려면**
1. HealthLake `region` 및 `datastoreId` 값을 수집합니다. 자세한 내용은 [데이터 스토어 속성 가져오기](managing-data-stores-describe.md) 단원을 참조하십시오.
1. 연결된 `id` 값을 `Resource` 읽고 수집할 FHIR 유형을 결정합니다. 자세한 내용은 [조건 키](reference-fhir-resource-types.md) 단원을 참조하십시오.
1. HealthLake `region` 및에 대해 수집된 값을 사용하여 요청에 대한 URL을 구성합니다`datastoreId`. FHIR `Resource` 유형, 연결된 및 `id`선택적 검색 파라미터도 포함합니다. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id/_history{?[parameters]}
```
**FHIR `history` 상호 작용에 대해 HealthLake에서 지원하는 검색 파라미터**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/healthlake/latest/devguide/managing-fhir-resources-read-history.html)
1. 요청을 보냅니다. FHIR `history` 상호 작용은 FHIR 권한 부여에서 [AWS 서명 버전 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 또는 SMART와 함께 `GET` 요청을 사용합니다. 다음 `curl` 예제에서는 `_count` 검색 파라미터를 사용하여 HealthLake의 FHIR `Patient` 리소스에 대한 페이지당 100개의 과거 검색 결과를 반환합니다. 전체 예제를 보려면 **복사** 버튼을 스크롤합니다.
------
#### [ SigV4 ]
SigV4 권한 부여
```
curl --request GET \
'https://healthlake.region.amazonaws.com/datastore/datastore-id/r4/Patient/id/_history?_count=100' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json'
```
------
#### [ SMART on FHIR ]
[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 데이터 형식에 대한 SMART on FHIR 권한 부여 예제입니다.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
호출자는 권한 부여 Lambda에 권한을 할당할 수 있습니다. 자세한 내용은 [OAuth 2.0 범위](reference-smart-on-fhir-oauth-scopes.md) 단원을 참조하십시오.
------
`history` 상호 작용의 반환 콘텐츠는 `Bundle`유형이 로 설정된 FHIR 리소스에 포함되어 있습니다`history`. 지정된 버전 기록을 포함하고, 가장 오래된 버전을 마지막으로 정렬하며, 삭제된 리소스를 포함합니다. 자세한 내용은 **FHIR R4 설명서**[https://hl7.org/fhir/R4/bundle.html](https://hl7.org/fhir/R4/bundle.html)의 섹션을 참조하세요.
## 버전별 FHIR 리소스 기록 읽기
FHIR `vread` 상호 작용은 HealthLake 데이터 스토어에서 리소스의 버전별 읽기를 수행합니다. 이 상호 작용을 사용하면 과거 특정 시간에 있던 FHIR 리소스의 내용을 볼 수 있습니다.
**참고**
*없이* FHIR `history` 상호 작용을 사용하는 경우 `vread` HealthLake는 항상 리소스 메타데이터의 최신 버전을 반환합니다.
HealthLake는 지원되는 각 리소스에 대해에서 버전 관리를 지원한다고 선언[https://hl7.org/fhir/R4/capabilitystatement-definitions.html#CapabilityStatement.rest.resource.versioning](https://hl7.org/fhir/R4/capabilitystatement-definitions.html#CapabilityStatement.rest.resource.versioning)합니다. 모든 HealthLake 데이터 스토어는 모든 리소스에 `Resource.meta.versionId` (`vid`)를 포함합니다.
FHIR `history` 상호 작용이 활성화된 경우(기본적으로 10/25/2024 이후에 생성된 데이터 스토어의 경우 또는 이전 데이터 스토어의 요청에 따라) `Bundle` 응답에는 [https://hl7.org/fhir/R4/bundle-definitions.html#Bundle.entry.response.location](https://hl7.org/fhir/R4/bundle-definitions.html#Bundle.entry.response.location) 요소의 `vid` 일부로가 포함됩니다. 다음 예제에서는 숫자 로 `vid` 표시됩니다`1`. 전체 예제를 보려면 [예제 번들/번들 응답(JSON)](https://build.fhir.org/bundle-response.json.html)을 참조하세요.
```
"response" : {
"status" : "201 Created",
"location" : "Patient/12423/_history/1",
...}
```
**버전별 FHIR 리소스 기록을 읽으려면**
1. HealthLake `region` 및 `datastoreId` 값을 수집합니다. 자세한 내용은 [데이터 스토어 속성 가져오기](managing-data-stores-describe.md) 단원을 참조하십시오.
1. 연결된 및 `id` `vid` 값을 읽고 수집할 FHIR `Resource` 유형을 결정합니다. 자세한 내용은 [조건 키](reference-fhir-resource-types.md) 단원을 참조하십시오.
1. HealthLake 및 FHIR에 대해 수집된 값을 사용하여 요청에 대한 URL을 구성합니다. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id/_history/vid
```
1. 요청을 보냅니다. FHIR `history` 상호 작용은 FHIR 권한 부여 시 [AWS 서명 버전 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 또는 SMART와 함께 `GET` 요청을 사용합니다. 다음 `vread` 상호 작용은에서 지정한 `Patient` 리소스 메타데이터 버전의 FHIR 리소스에 지정된 콘텐츠가 있는 단일 인스턴스를 반환합니다`vid`. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다.
------
#### [ SigV4 ]
SigV4 권한 부여
```
curl --request GET \
'https://healthlake.region.amazonaws.com/datastore/datastore-id/r4/Patient/id/_history/vid' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json'
```
------
#### [ SMART on FHIR ]
[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 데이터 형식에 대한 SMART on FHIR 권한 부여 예제입니다.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
호출자는 권한 부여 Lambda에 권한을 할당할 수 있습니다. 자세한 내용은 [OAuth 2.0 범위](reference-smart-on-fhir-oauth-scopes.md) 단원을 참조하십시오.
------
# FHIR 리소스 업데이트
FHIR `update` 상호 작용은 기존 리소스에 대한 새 현재 버전을 생성하거나 지정된에 대한 리소스가 아직 없는 경우 초기 버전을 생성합니다`id`. 자세한 내용은 **FHIR R4 RESTful API 설명서**[https://hl7.org/fhir/R4/http.html#update](https://hl7.org/fhir/R4/http.html#update)의 섹션을 참조하세요.
**FHIR 리소스를 업데이트하려면**
1. HealthLake `region` 및 `datastoreId` 값을 수집합니다. 자세한 내용은 [데이터 스토어 속성 가져오기](managing-data-stores-describe.md) 단원을 참조하십시오.
1. 연결된 `id` 값을 `Resource` 업데이트하고 수집할 FHIR 유형을 결정합니다. 자세한 내용은 [조건 키](reference-fhir-resource-types.md) 단원을 참조하십시오.
1. HealthLake `region` 및에 대해 수집된 값을 사용하여 요청에 대한 URL을 구성합니다`datastoreId`. FHIR `Resource` 유형 및 관련 도 포함합니다`id`. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다.
```
PUT https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id
```
1. 요청에 대한 `JSON` 본문을 구성하여 수행할 FHIR 데이터 업데이트를 지정합니다. 이 절차의 목적상 파일을 로 저장합니다`update-patient.json`.
```
{
"id": "2de04858-ba65-44c1-8af1-f2fe69a977d9",
"resourceType": "Patient",
"active": true,
"name": [
{
"use": "official",
"family": "Doe",
"given": [
"Jane"
]
},
{
"use": "usual",
"given": [
"Jane"
]
}
],
"gender": "female",
"birthDate": "1985-12-31"
}
```
1. 요청을 보냅니다. FHIR `update` 상호 작용은 FHIR 권한 부여에서 [AWS 서명 버전 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 또는 SMART와 함께 `PUT` 요청을 사용합니다. 다음 `curl` 예시에서는 HealthLake에서 `Patient` 리소스를 업데이트합니다. 전체 예제를 보려면 **복사** 버튼을 스크롤합니다.
------
#### [ SigV4 ]
SigV4 권한 부여
```
curl --request PUT \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json' \
--data @update-patient.json
```
요청은 기존 리소스가 *업데이트된* 경우 `200` HTTP 상태 코드를 반환하고 새 리소스가 생성된 경우 `201` HTTP 상태 코드를 반환합니다.
------
#### [ SMART on FHIR ]
[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 데이터 형식에 대한 SMART on FHIR 권한 부여 예제입니다.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
호출자는 권한 부여 Lambda에 권한을 할당할 수 있습니다. 자세한 내용은 [OAuth 2.0 범위](reference-smart-on-fhir-oauth-scopes.md) 단원을 참조하십시오.
------
#### [ AWS Console ]
1. HealthLake 콘솔의 [쿼리 실행](https://console.aws.amazon.com/healthlake/home#/crud) 페이지에 로그인합니다.
2. **쿼리 설정** 섹션에서 다음을 선택합니다.
+ **데이터 스토어 ID** - 쿼리 문자열을 생성할 데이터 스토어 ID를 선택합니다.
+ **쿼리 유형** -를 선택합니다`Update (PUT)`.
+ **리소스 유형** - 업데이트하거나 생성할 FHIR [리소스 유형을](reference-fhir-resource-types.md) 선택합니다.
+ **요청 본문** - 리소스를 업데이트할 FHIR 데이터를 지정하여 요청에 대한 JSON 본문을 구성합니다.
3. **쿼리 실행**을 선택합니다.
------
## 조건에 따라 FHIR 리소스 업데이트
조건부 업데이트를 사용하면 논리적 FHIR이 아닌 일부 식별 검색 기준에 따라 기존 리소스를 업데이트할 수 있습니다`id`. 서버는 업데이트를 처리할 때 요청에 대한 단일 논리를 해결하기 위해 리소스 유형에 `id` 대한 표준 검색 기능을 사용하여 검색을 수행합니다.
서버가 수행하는 작업은 검색한 일치 항목 수에 따라 달라집니다.
+ **일치 항목 없음, 요청 본문에 `id` 제공되지 않음**: 서버가 FHIR 리소스를 생성합니다.
+ **일치 항목 없음, `id` 제공됨 및 리소스가에 아직 존재하지 않음`id`**: 서버는 상호 작용을 업데이트로 상호 작용 생성을 처리합니다.
+ **일치 항목 없음, `id` 제공됨 및 이미 존재**: 서버가 `409 Conflict` 오류와 함께 업데이트를 거부합니다.
+ **일치 항목 1개, 리소스`id`가 제공되지 않음 OR(리소스가 `id` 제공되고 찾은 리소스와 일치함)**: 서버는 위와 같이 일치하는 리소스에 대해 업데이트를 수행합니다. 리소스가 업데이트된 경우 서버는를 반환해야 합니다`200 OK`.
+ **One Match, 리소스가 `id` 제공되었지만 찾은 리소스와 일치하지 않음**: 서버가 클라이언트 ID 사양이 가급적이면에서 문제가었음을 나타내는 `409 Conflict` 오류를 반환합니다. `OperationOutcome`
+ **여러 일치** 항목: 서버가 클라이언트의 기준이 가급적이면 OperationOutcome으로 충분히 선택되지 않았음을 나타내는 `412 Precondition Failed` 오류를 반환합니다.
다음 예제에서는 이름이 peter이고, 생년월일이 2000년 1월 1일이며, 전화번호가 1234567890인 `Patient` 리소스를 업데이트합니다.
```
PUT https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?name=peter&birthdate=2000-01-01&phone=1234567890
```
## 리소스 업데이트에 대한 검증 수준 구성
FHIR 리소스를 업데이트할 때 선택적으로 `x-amzn-healthlake-fhir-validation-level` HTTP 헤더를 지정하여 리소스에 대한 검증 수준을 구성할 수 있습니다.는 AWS HealthLake 현재 다음 검증 수준을 지원합니다.
+ `strict`: 리소스는 리소스의 프로필 요소 또는 프로필이 없는 경우 R4 사양에 따라 검증됩니다. 이는의 기본 검증 수준입니다 AWS HealthLake.
+ `structure-only`: 리소스는 R4에 대해 검증되며 참조된 프로파일은 무시합니다.
+ `minimal`: 리소스는 특정 R4 규칙을 무시하면서 최소한으로 검증됩니다. 검색/분석에 필요한 구조 검사에 실패한 리소스는 감사 경고를 포함하도록 업데이트됩니다.
최소 검증 수준으로 업데이트된 리소스는 검색 인덱싱에 필요한 검증에 실패하더라도 데이터 스토어에 수집될 수 있습니다. 이 경우 해당 실패를 문서화하기 위한 Healthlake별 확장을 포함하도록 리소스가 업데이트됩니다.
```
{
"url": "http://healthlake.amazonaws.com/fhir/StructureDefinition/validation-issue",
"valueString": "{\"resourceType\":\"OperationOutcome\",\"issue\":[{\"severity\":\"error\",\"code\":\"processing\",\"details\":{\"text\":\"FHIR resource in payload failed FHIR validation rules.\"},\"diagnostics\":\"FHIR resource in payload failed FHIR validation rules.\"}]}"
}
```
또한 다음 HTTP 응답 헤더는 "true" 값과 함께 포함됩니다.
```
x-amzn-healthlake-validation-issues : true
```
**참고**
R4 사양에 따라 잘못된 형식으로 수집된 데이터는 이러한 오류가 있는 경우 예상대로 검색하지 못할 수 있습니다.
# PATCH 작업을 사용하여 리소스 수정
AWS HealthLake 는 FHIR 리소스에 대한 PATCH 작업을 지원하므로 전체 리소스를 업데이트하지 않고 추가, 교체 또는 삭제할 특정 요소를 대상으로 하여 리소스를 수정할 수 있습니다. 이 작업은 다음이 필요한 경우에 특히 유용합니다.
+ 대규모 리소스에 대한 대상 업데이트 수행
+ 네트워크 대역폭 사용량 감소
+ 특정 리소스 요소에 대한 원자성 수정 수행
+ 동시 변경 사항 덮어쓰기 위험 최소화
+ 배치 및 트랜잭션 워크플로의 일부로 리소스 업데이트
## 지원되는 패치 형식
AWS HealthLake 는 두 가지 표준 패치 형식을 지원합니다.
### JSON 패치(RFC 6902)
JSON 포인터 구문을 사용하여 리소스 구조의 위치별로 요소를 대상으로 지정합니다.
**Content-Type:** `application/json-patch+json`
### FHIRPath 패치(FHIR R4 사양)
FHIRPath 표현식을 사용하여 콘텐츠 및 관계를 기준으로 요소를 대상으로 지정하여 패치 적용에 대한 FHIR 네이티브 접근 방식을 제공합니다.
**Content-Type:** `application/fhir+json`
## 사용법
### 직접 패치 작업
PATCH HTTP 메서드를 사용하여 FHIR 리소스에서 PATCH 작업을 직접 호출할 수 있습니다.
```
PATCH [base]/[resource-type]/[id]{?_format=[mime-type]}
```
### 번들의 패치
패치 작업은 `batch` 또는 유형의 FHIR 번들 내에 항목으로 포함될 수 `transaction`있으므로 패치 작업을 단일 요청으로 다른 FHIR 상호 작용(생성, 읽기, 업데이트, 삭제)과 결합할 수 있습니다.
+ **트랜잭션 번들**: 모든 항목이 원자적으로 성공하거나 실패함
+ **배치 번들**: 각 항목은 독립적으로 처리됩니다.
## JSON 패치 형식
### 지원되는 작업
| 연산 | 설명 |
| --- | --- |
| add | 리소스에 새 값 추가 |
| remove | 리소스에서 값 제거 |
| replace | 리소스의 기존 값 바꾸기 |
| move | 한 위치에서 값을 제거하고 다른 위치에 추가 |
| copy | 한 위치에서 다른 위치로 값 복사 |
| test | 대상 위치의 값이 지정된 값과 동일한지 테스트 |
### 경로 구문
JSON 패치는 JSON 포인터 구문(RFC 6901)을 사용합니다.
| 경로 예제 | 설명 |
| --- | --- |
| /name/0/family | 이름의 패밀리 요소 |
| /telecom/- | 통신 배열에 추가 |
| /active | 루트 수준 활성 요소 |
| /address/0/line/1 | 첫 번째 주소의 두 번째 줄 |
### 예제
**여러 작업을 사용한 직접 JSON 패치 요청**
```
PATCH [base]/Patient/example
Content-Type: application/json-patch+json
If-Match: W/"1"
[
{
"op": "replace",
"path": "/name/0/family",
"value": "Smith"
},
{
"op": "add",
"path": "/telecom/-",
"value": {
"system": "phone",
"value": "555-555-5555",
"use": "home"
}
},
{
"op": "remove",
"path": "/address/0"
},
{
"op": "move",
"from": "/name/0/family",
"path": "/name/1/family"
},
{
"op": "test",
"path": "/gender",
"value": "male"
},
{
"op": "copy",
"from": "/name/0",
"path": "/name/1"
}
]
```
**단일 작업으로 직접 JSON 패치 요청**
```
PATCH [base]/Patient/example
Content-Type: application/json-patch+json
[
{
"op": "replace",
"path": "/active",
"value": false
}
]
```
**번들의 JSON 패치**
base64로 인코딩된 JSON 패치 페이로드를 포함하는 바이너리 리소스를 사용합니다.
```
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [{
"resource": {
"resourceType": "Binary",
"contentType": "application/json-patch+json",
"data": "W3sib3AiOiJhZGQiLCJwYXRoIjoiL2JpcnRoRGF0ZSIsInZhbHVlIjoiMTk5MC0wMS0wMSJ9XQ=="
},
"request": {
"method": "PATCH",
"url": "Patient/123"
}
}]
}
```
## FHIRPath 패치 형식
### 지원되는 작업
| 연산 | 설명 |
| --- | --- |
| add | 리소스에 새 요소 추가 |
| insert | 목록의 특정 위치에 요소 삽입 |
| delete | 리소스에서 요소 제거 |
| replace | 기존 요소의 값 바꾸기 |
| move | 목록 내 요소 재정렬 |
### 경로 구문
FHIRPath 패치는 FHIRPath 표현식을 사용하여 다음을 지원합니다.
+ **인덱스 기반 액세스**: `Patient.name[0]`
+ **를 사용한 필터링`where()`**: `Patient.name.where(use = 'official')`
+ **부울 로직**: `Patient.telecom.where(system = 'phone' and use = 'work')`
+ **함수 하위 설정**: `first()`, `last()`
+ **존재 확인**: `exists()`, `count()`
+ **다형성 탐색**: `Observation.value`
### 예제
**직접 FHIRPath 패치 요청**
```
PATCH [base]/Patient/123
Content-Type: application/fhir+json
Authorization: ...
{
"resourceType": "Parameters",
"parameter": [{
"name": "operation",
"part": [
{ "name": "type", "valueCode": "add" },
{ "name": "path", "valueString": "Patient" },
{ "name": "name", "valueString": "birthDate" },
{ "name": "value", "valueDate": "1990-01-01" }
]
}]
}
```
**번들의 FHIRPath 패치**
파라미터 리소스를의 항목 리소스로 사용합니다`method: PATCH`.
```
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [{
"resource": {
"resourceType": "Parameters",
"parameter": [{
"name": "operation",
"part": [
{ "name": "type", "valueCode": "add" },
{ "name": "path", "valueString": "Patient" },
{ "name": "name", "valueString": "birthDate" },
{ "name": "value", "valueDate": "1990-01-01" }
]
}]
},
"request": {
"method": "PATCH",
"url": "Patient/123"
}
}]
}
```
## 요청 헤더
| 헤더 | 필수 | 설명 |
| --- | --- | --- |
| Content-Type | 예 | application/json-patch\$1json JSON 패치의 경우 또는 FHIRPath 패치application/fhir\$1json의 경우 |
| If-Match | 아니요 | ETag를 사용한 버전별 조건부 업데이트 |
## 샘플 응답
작업은 새 버전 정보와 함께 업데이트된 리소스를 반환합니다.
```
HTTP/1.1 200 OK
Content-Type: application/fhir+json
ETag: W/"2"
Last-Modified: Mon, 05 May 2025 10:10:10 GMT
{
"resourceType": "Patient",
"id": "example",
"active": true,
"name": [
{
"family": "Smith",
"given": ["John"]
}
],
"telecom": [
{
"system": "phone",
"value": "555-555-5555",
"use": "home"
}
],
"meta": {
"versionId": "2",
"lastUpdated": "2025-05-05T10:10:10Z"
}
}
```
## 동작
PATCH 작업:
+ 적절한 사양에 따라 패치 구문을 검증합니다(JSON 패치의 경우 RFC 6902, FHIRPath 패치의 경우 FHIRPath R4).
+ 원자적으로 작업 적용 - 모든 작업이 성공하거나 모두 실패함
+ 리소스 버전 ID를 업데이트하고 새 기록 항목을 생성합니다.
+ 변경 사항을 적용하기 전에 기록에서 원래 리소스를 보존합니다.
+ 패치 적용 후 FHIR 리소스 제약 조건 검증
+ ETag와 If-Match 헤더를 사용한 조건부 업데이트 지원
## 오류 처리
작업은 다음 오류 조건을 처리합니다.
+ **400 잘못된 요청**: 잘못된 패치 구문(부적합 요청 또는 잘못된 패치 문서)
+ **404 찾을 수 없음**: 리소스를 찾을 수 없음(지정된 ID가 존재하지 않음)
+ **409 충돌**: 버전 충돌(동시 업데이트 또는 비최신 버전 ID 제공)
+ **422 처리 불가능한 엔**터티: 지정된 리소스 요소에 패치 작업을 적용할 수 없습니다.
## 기능 요약
| 기능 | JSON 패치 | FHIRPath 패치 |
| --- | --- | --- |
| 콘텐츠 유형 | application/json-patch\$1json | application/fhir\$1json |
| 경로 형식 | JSON 포인터(RFC 6901) | FHIRPath 표현식 |
| 직접 패치 API | 지원됨 | 지원됨 |
| 번들 배치 | 지원됨(바이너리를 통해) | 지원됨(파라미터를 통해) |
| 번들 트랜잭션 | 지원됨(바이너리를 통해) | 지원됨(파라미터를 통해) |
| 운영 | 추가, 제거, 교체, 이동, 복사, 테스트 | 추가, 삽입, 삭제, 교체, 이동 |
## 제한 사항
+ 검색 조건을 사용하는 조건부 PATCH 작업은 지원되지 않습니다.
+ 번들의 JSON 패치는 base64 인코딩 콘텐츠와 함께 바이너리 리소스를 사용해야 합니다.
+ 번들의 FHIRPath 패치는 파라미터 리소스를 사용해야 합니다.
## 추가 리소스
PATCH 작업에 대한 자세한 내용은 다음을 참조하세요.
+ [FHIR R4 패치 설명서](https://hl7.org/fhir/http.html#patch)
+ [FHIR R4 FHIRPath 패치 사양](https://hl7.org/fhir/fhirpatch.html)
+ [RFC 6902 - JSON 패치](https://datatracker.ietf.org/doc/html/rfc6902#section-4)
+ [RFC 6901 - JSON 포인터](https://datatracker.ietf.org/doc/html/rfc6901)
# FHIR 리소스 번들링
FHIR`Bundle`은의 FHIR 리소스 모음을 위한 컨테이너입니다 AWS HealthLake.는 서로 다른 처리 동작을 가진 두 가지 유형의 번들을 AWS HealthLake 지원합니다.
[https://hl7.org/fhir/R4/http.html#transaction](https://hl7.org/fhir/R4/http.html#transaction) 번들은 각 리소스를 독립적으로 처리합니다. 리소스 하나가 실패하더라도 나머지 리소스는 여전히 성공할 수 있습니다. 각 작업은 개별적으로 처리되며 일부 작업이 실패하더라도 처리가 계속됩니다. 관련 없는 여러 환자 레코드를 업로드하는 등 부분적 성공이 허용되는 대량 작업에 배치 번들을 사용합니다.
[https://hl7.org/fhir/R4/http.html#transaction](https://hl7.org/fhir/R4/http.html#transaction) 번들은 모든 리소스를 원자적으로 단일 단위로 처리합니다. 모든 리소스 작업이 성공하거나 커 AWS HealthLake 밋하지 않습니다. 모든 데이터를 함께 기록해야 하는 관련 관찰 및 조건이 있는 환자 생성과 같이 관련 리소스에서 참조 무결성을 보장해야 하는 경우 트랜잭션 번들을 사용합니다.
**배치 번들과 트랜잭션 번들의 차이점**
| 기능 | 배치 | 트랜잭션 |
| --- | --- | --- |
| 처리 모델 | 각 작업은 독립적으로 성공하거나 실패합니다. | 모든 작업은 단일 원자 단위로 성공하거나 실패합니다. |
| 장애 처리 | 개별 작업이 실패하더라도 처리는 계속됩니다. | 단일 작업이 실패하면 전체 번들이 실패합니다. |
| 실행 순서 | 실행 순서는 보장되지 않습니다. | 작업은 지정된 순서대로 처리됩니다. |
| 참조 무결성 | 작업 간에 적용되지 않습니다. | 번들 내에서 로컬로 참조되는 리소스에 적용됩니다. |
| 가장 적합한 용도 | 부분적 성공이 허용되는 대량 작업. | 함께 생성하거나 업데이트해야 하는 관련 리소스입니다. |
동일하거나 다른 유형의 FHIR 리소스를 번들링할 수 있으며, `create`, , `read`, 등의 FHIR 작업을 혼합하여 포함할 수 `update` `delete`있습니다`patch`. 자세한 내용은 **FHIR R4 설명서**의 [리소스 번들](https://hl7.org/fhir/R4/Bundle)을 참조하세요.
다음은 각 번들 유형에 대한 사용 사례의 예입니다.
배치 번들
+ 야간 데이터 동기화 중에 서로 다른 시설에서 관련 없는 여러 환자 레코드를 업로드합니다.
+ 일부 레코드에 검증 문제가 있을 수 있는 과거 약물 레코드를 대량 업로드합니다.
+ 개별 실패가 다른 항목에 영향을 미치지 않는 조직 및 실무자와 같은 참조 데이터를 로드합니다.
트랜잭션 번들
+ 모든 데이터를 함께 기록해야 하는 응급 부서 승인 중에 관련 관찰 및 조건이 있는 환자를 생성합니다.
+ 환자의 약물 목록과 일관성을 유지해야 하는 관련 알레르기 정보를 업데이트합니다.
+ 환자, 관찰, 절차 및 결제 정보와의 완전한 접촉을 단일 원자 단위로 기록합니다.
**중요**
배치 번들과 트랜잭션 번들 모두 동일한 `Bundle` 리소스 구조를 사용합니다. 유일한 차이점은 `type` 필드의 값입니다.
다음 예제에서는 여러 리소스 유형 및 작업이 있는 트랜잭션 번들을 보여줍니다.
```
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065",
"resource": {
"resourceType": "Patient",
"id": "new-patient",
"active": true,
"name": [
{
"family": "Johnson",
"given": [
"Sarah"
]
}
],
"gender": "female",
"birthDate": "1985-08-12",
"telecom": [
{
"system": "phone",
"value": "555-123-4567",
"use": "home"
}
]
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"fullUrl": "urn:uuid:7f83f473-d8cc-4a8d-86d3-9d9876a3248b",
"resource": {
"resourceType": "Observation",
"id": "blood-pressure",
"status": "final",
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "85354-9",
"display": "Blood pressure panel"
}
],
"text": "Blood pressure panel"
},
"subject": {
"reference": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065"
},
"effectiveDateTime": "2023-10-15T09:30:00Z",
"component": [
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "8480-6",
"display": "Systolic blood pressure"
}
]
},
"valueQuantity": {
"value": 120,
"unit": "mmHg",
"system": "http://unitsofmeasure.org",
"code": "mm[Hg]"
}
},
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "8462-4",
"display": "Diastolic blood pressure"
}
]
},
"valueQuantity": {
"value": 80,
"unit": "mmHg",
"system": "http://unitsofmeasure.org",
"code": "mm[Hg]"
}
}
]
},
"request": {
"method": "POST",
"url": "Observation"
}
},
{
"resource": {
"resourceType": "Appointment",
"id": "appointment-123",
"status": "booked",
"description": "Annual physical examination",
"start": "2023-11-15T09:00:00Z",
"end": "2023-11-15T09:30:00Z",
"participant": [
{
"actor": {
"reference": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065"
},
"status": "accepted"
}
]
},
"request": {
"method": "PUT",
"url": "Appointment/appointment-123"
}
},
{
"request": {
"method": "DELETE",
"url": "MedicationRequest/med-request-456"
}
}
]
}
```
## FHIR 리소스를 독립 엔터티로 번들링
**FHIR 리소스를 독립 엔터티로 번들링하려면**
1. HealthLake `region` 및 `datastoreId` 값을 수집합니다. 자세한 내용은 [데이터 스토어 속성 가져오기](managing-data-stores-describe.md) 단원을 참조하십시오.
1. HealthLake `region` 및에 대해 수집된 값을 사용하여 요청에 대한 URL을 구성합니다`datastoreId`. URL에 FHIR 리소스 유형을 지정*하지* 마십시오. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다.
```
POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/
```
1. 각 HTTP 동사를 `method` 요소의 일부로 지정하여 요청에 대한 JSON 본문을 구성합니다. 다음 예제에서는 `Bundle` 리소스와의 `batch` 유형 상호 작용을 사용하여 새 `Patient` 및 `Medication` 리소스를 생성합니다. 그에 따라 모든 필수 섹션에 주석이 추가됩니다. 이 절차의 목적상 파일을 로 저장합니다`batch-independent.json`.
```
{
"resourceType": "Bundle",
"id": "bundle-batch",
"meta": {
"lastUpdated": "2014-08-18T01:43:30Z"
},
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Patient",
"meta": {
"lastUpdated": "2022-06-03T17:53:36.724Z"
},
"text": {
"status": "generated",
"div": "Some narrative"
},
"active": true,
"name": [
{
"use": "official",
"family": "Jackson",
"given": [
"Mateo",
"James"
]
}
],
"gender": "male",
"birthDate": "1974-12-25"
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"resource": {
"resourceType": "Medication",
"id": "med0310",
"contained": [
{
"resourceType": "Substance",
"id": "sub03",
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "55452001",
"display": "Oxycodone (substance)"
}
]
}
}
],
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "430127000",
"display": "Oral Form Oxycodone (product)"
}
]
},
"form": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "385055001",
"display": "Tablet dose form (qualifier value)"
}
]
},
"ingredient": [
{
"itemReference": {
"reference": "#sub03"
},
"strength": {
"numerator": {
"value": 5,
"system": "http://unitsofmeasure.org",
"code": "mg"
},
"denominator": {
"value": 1,
"system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
"code": "TAB"
}
}
}
]
},
"request": {
"method": "POST",
"url": "Medication"
}
}
]
}
```
1. 요청을 보냅니다. FHIR `Bundle` 배치 유형은 FHIR 권한 부여 시 [AWS 서명 버전 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 또는 SMART로 `POST` 요청을 사용합니다. 다음 코드 예제에서는 데모용으로 `curl` 명령줄 도구를 사용합니다.
------
#### [ SigV4 ]
SigV4 권한 부여
```
curl --request POST \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json' \
--data @batch-type.json
```
------
#### [ SMART on FHIR ]
[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 데이터 형식에 대한 SMART on FHIR 권한 부여 예제입니다.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
호출자는 권한 부여 Lambda에 권한을 할당할 수 있습니다. 자세한 내용은 [OAuth 2.0 범위](reference-smart-on-fhir-oauth-scopes.md) 단원을 참조하십시오.
------
서버는 `Bundle` 배치 유형 요청의 결과로 생성된 `Patient` 및 `Medication` 리소스를 보여주는 응답을 반환합니다.
## 번들의 조건부 PUTs
AWS HealthLake 는 다음 쿼리 파라미터를 사용하여 번들 내에서 조건부 업데이트를 지원합니다.
+ `_id` (독립 실행형)
+ `_id` 다음 중 하나와 함께 사용할 수 있습니다.
+ `_tag`
+ `_createdAt`
+ `_lastUpdated`
번들에서 조건부 PUTs 사용하는 경우는 쿼리 파라미터를 기존 리소스와 비교하여 AWS HealthLake 평가하고 일치 결과를 기반으로 조치를 취합니다.
**조건부 업데이트 동작**
| 시나리오 | HTTP 상태 | 취해진 조치 |
| --- | --- | --- |
| ID가 제공되지 않은 리소스 | 201 생성됨 | 는 항상 새 리소스를 생성합니다. |
| 새 ID가 있는 리소스(일치하지 않음) | 201 생성됨 | 지정된 ID로 새 리소스를 생성합니다. |
| 기존 ID가 있는 리소스(단일 일치) | 200 OK | 일치하는 리소스를 업데이트합니다. |
| 기존 ID가 있는 리소스(충돌 감지됨) | 409 충돌 | 오류를 반환합니다. 변경 사항이 없습니다. |
| 기존 ID가 있는 리소스(ID 불일치) | 400 잘못된 요청 | 오류를 반환합니다. 변경 사항이 없습니다. |
| 여러 리소스 일치 조건 | 412 사전 조건 실패 | 오류를 반환합니다. 변경 사항이 없습니다. |
조건부 업데이트가 포함된 다음 번들 예제에서는 조건이 충족되는 경우에만 FHIR ID가 인 `Patient` 리소스`_lastUpdated=lt2025-04-20`가 `476` 업데이트됩니다.
```
{
"resourceType": "Bundle",
"id": "bundle-batch",
"meta": {
"lastUpdated": "2014-08-18T01:43:30Z"
},
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "476",
"meta": {
"lastUpdated": "2022-06-03T17:53:36.724Z"
},
"active": true,
"name": [
{
"use": "official",
"family": "Jackson",
"given": [
"Mateo",
"James"
]
}
],
"gender": "male",
"birthDate": "1974-12-25"
},
"request": {
"method": "PUT",
"url": "Patient?_id=476&_lastUpdated=lt2025-04-20"
}
},
{
"resource": {
"resourceType": "Medication",
"id": "med0310",
"contained": [
{
"resourceType": "Substance",
"id": "sub03",
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "55452001",
"display": "Oxycodone (substance)"
}
]
}
}
],
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "430127000",
"display": "Oral Form Oxycodone (product)"
}
]
},
"form": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "385055001",
"display": "Tablet dose form (qualifier value)"
}
]
},
"ingredient": [
{
"itemReference": {
"reference": "#sub03"
},
"strength": {
"numerator": {
"value": 5,
"system": "http://unitsofmeasure.org",
"code": "mg"
},
"denominator": {
"value": 1,
"system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
"code": "TAB"
}
}
}
]
},
"request": {
"method": "POST",
"url": "Medication"
}
}
]
}
```
## FHIR 리소스를 단일 엔터티로 번들링
**FHIR 리소스를 단일 엔터티로 번들링하려면**
1. HealthLake `region` 및 `datastoreId` 값을 수집합니다. 자세한 내용은 [데이터 스토어 속성 가져오기](managing-data-stores-describe.md) 단원을 참조하십시오.
1. HealthLake `region` 및에 대해 수집된 값을 사용하여 요청에 대한 URL을 구성합니다`datastoreId`. FHIR 리소스 유형을 URL의 `Bundle` 일부로 포함합니다. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다.
```
POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Bundle
```
1. 요청에 대한 JSON 본문을 구성하여 그룹화할 FHIR 리소스를 지정합니다. 다음 예제에서는 HealthLake에서 두 개의 `Patient` 리소스를 그룹화합니다. 이 절차의 목적상 파일을 로 저장합니다`batch-single.json`.
```
{
"resourceType": "Bundle",
"id": "bundle-minimal",
"language": "en-US",
"identifier": {
"system": "urn:oid:1.2.3.4.5",
"value": "28b95815-76ce-457b-b7ae-a972e527db4f"
},
"type": "document",
"timestamp": "2020-12-11T14:30:00+01:00",
"entry": [
{
"fullUrl": "urn:uuid:f40b07e3-37e8-48c3-bf1c-ae70fe12dabf",
"resource": {
"resourceType": "Composition",
"id": "f40b07e3-37e8-48c3-bf1c-ae70fe12dabf",
"status": "final",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "60591-5",
"display": "Patient summary Document"
}
]
},
"date": "2020-12-11T14:30:00+01:00",
"author": [
{
"reference": "urn:uuid:45271f7f-63ab-4946-970f-3daaaa0663ff"
}
],
"title": "Patient Summary as of December 7, 2020 14:30"
}
},
{
"fullUrl": "urn:uuid:45271f7f-63ab-4946-970f-3daaaa0663ff",
"resource": {
"resourceType": "Practitioner",
"id": "45271f7f-63ab-4946-970f-3daaaa0663ff",
"active": true,
"name": [
{
"family": "Doe",
"given": [
"John"
]
}
]
}
}
]
}
```
1. 요청을 보냅니다. FHIR `Bundle` 문서 유형은 [AWS 서명 버전 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 서명 프로토콜과 함께 `POST` 요청을 사용합니다. 다음 코드 예제에서는 데모용으로 `curl` 명령줄 도구를 사용합니다.
------
#### [ SigV4 ]
SigV4 권한 부여
```
curl --request POST \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Bundle' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json' \
--data @document-type.json
```
------
#### [ SMART on FHIR ]
[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 데이터 형식에 대한 SMART on FHIR 권한 부여 예제입니다.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
호출자는 권한 부여 Lambda에 권한을 할당할 수 있습니다. 자세한 내용은 [OAuth 2.0 범위](reference-smart-on-fhir-oauth-scopes.md) 단원을 참조하십시오.
------
서버는 `Bundle` 문서 유형 요청의 결과로 생성된 두 개의 `Patient` 리소스를 보여주는 응답을 반환합니다.
## 번들에 대한 검증 수준 구성
FHIR 리소스를 번들링할 때 선택적으로 `x-amzn-healthlake-fhir-validation-level` HTTP 헤더를 지정하여 리소스에 대한 검증 수준을 구성할 수 있습니다. 이 검증 수준은 번들 내의 모든 생성 및 업데이트 요청에 대해 설정됩니다.는 AWS HealthLake 현재 다음 검증 수준을 지원합니다.
+ `strict`: 리소스는 리소스의 프로필 요소 또는 프로필이 없는 경우 R4 사양에 따라 검증됩니다. 이는의 기본 검증 수준입니다 AWS HealthLake.
+ `structure-only`: 리소스는 R4에 대해 검증되며 참조된 프로파일은 무시합니다.
+ `minimal`: 리소스는 특정 R4 규칙을 무시하면서 최소한으로 검증됩니다. 검색/분석에 필요한 구조 검사에 실패한 리소스는 감사 경고를 포함하도록 업데이트됩니다.
최소 검증 수준으로 번들링된 리소스는 검색 인덱싱에 필요한 검증에 실패하더라도 데이터 스토어에 수집될 수 있습니다. 이 경우 리소스는 해당 실패를 문서화하기 위한 Healthlake별 확장을 포함하도록 업데이트되며 번들 응답 내의 항목에는 다음과 같이 OperationOutcome 리소스가 포함됩니다.
```
{
"resourceType": "Bundle",
"type": "batch-response",
"timestamp": "2025-08-25T22:58:48.846287342Z",
"entry": [
{
"response": {
"status": "201",
"location": "Patient/195abc49-ba8e-4c8b-95c2-abc88fef7544/_history/1",
"etag": "W/\"1\"",
"lastModified": "2025-08-25T22:58:48.801245445Z",
"outcome": {
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "processing",
"details": {
"text": "FHIR resource in payload failed FHIR validation rules."
},
"diagnostics": "FHIR resource in payload failed FHIR validation rules."
}
]
}
}
}
]
}
```
또한 다음 HTTP 응답 헤더는 "true" 값과 함께 포함됩니다.
```
x-amzn-healthlake-validation-issues : true
```
**참고**
R4 사양에 따라 잘못된 형식으로 수집된 데이터는 이러한 오류가 있는 경우 예상대로 검색하지 못할 수 있습니다.
## 번들 유형 "메시지"에 대한 제한된 지원
HealthLake는 내부 변환 프로세스를 `message` 통해 FHIR 번들 유형에 대한 제한된 지원을 제공합니다. 이 지원은 레거시 병원 시스템에서 ADT(Admission, Discharge, Transfer) 피드를 수집하는 등 소스에서 메시지 번들을 다시 포맷할 수 없는 시나리오를 위해 설계되었습니다.
**주의**
이 기능은 명시적 AWS 계정 허용 목록이 필요하며 FHIR R4 메시지 의미 체계 또는 참조 무결성을 적용하지 않습니다. 메시지 번들을 사용하기 전에 계정에 대한 활성화를 요청하려면 AWS Support에 문의하세요.
### 표준 메시지 처리의 주요 차이점
+ **메시지 번들**(FHIR 사양): 첫 번째 항목은 다른 리소스를 참조`MessageHeader`하는 이어야 합니다. 리소스에는 개별 `request` 객체가 없으며 MessageHeader 이벤트에 따라 처리 작업이 결정됩니다.
+ **HealthLake 처리**: 각 리소스 항목에 PUT 작업을 자동으로 할당하여 메시지 번들을 배치 번들로 변환합니다. 리소스는 메시지 의미 체계 또는 참조 무결성을 적용하지 않고 독립적으로 처리됩니다.
### 중요 제한 사항
+ FHIR R4 메시지별 처리 규칙이 적용되지 않음
+ 리소스 간 트랜잭션 무결성 없음
+ 리소스 간 참조가 검증되지 않음
+ 명시적 계정 허용 목록 지정 필요
### 예제 메시지 번들 구조
```
{
"resourceType": "Bundle",
"type": "message",
"entry": [
{
"resource": {
"resourceType": "MessageHeader",
"eventCoding": {
"system": "http://hl7.org/fhir/us/davinci-alerts/CodeSystem/notification-event",
"code": "notification-admit"
},
"focus": [{"reference": "Encounter/example-id"}]
}
},
{
"resource": {"resourceType": "Patient", "id": "example-id"}
},
{
"resource": {"resourceType": "Encounter", "id": "example-id"}
}
]
}
```
**참고**
각 리소스는 개별 PUT 작업을 통해 제출된 것처럼 독립적으로 저장됩니다. 전체 FHIR 메시징 의미 체계 또는 참조 무결성 검증이 필요한 경우 제출 전에 메시지 번들을 사전 처리하거나 애플리케이션 수준 검증을 구현합니다.
## 비동기 번들 트랜잭션
AWS HealthLake 는 최대 500개의 리소스가 있는 트랜잭션을 제출할 수 `transaction` 있는 비동기 `Bundle` 유형을 지원합니다. 비동기 트랜잭션을 제출하면 HealthLake는 처리를 위해 이를 대기열에 넣고 즉시 폴링 URL을 반환합니다. 이 URL을 사용하여 상태를 확인하고 응답을 검색할 수 있습니다. 이는 [FHIR 비동기 번들 패턴을](https://hl7.org/fhir/async-bundle.html) 따릅니다.
**비동기 트랜잭션을 사용해야 하는 경우**
+ 단일 트랜잭션에서 100개 이상의 리소스(동기 제한)를 제출해야 합니다.
+ 트랜잭션 처리가 완료될 때까지 기다리는 동안 애플리케이션을 차단하지 않으려고 합니다.
+ 처리량을 높이려면 대량의 관련 리소스를 처리해야 합니다.
**중요**
폴링 결과는 트랜잭션이 완료된 후 90일 동안 사용할 수 있습니다. 이 90일 기간이 지나면 폴링 URL이 더 이상 결과를 반환하지 않습니다. 이 기간 내에 결과를 검색하고 저장하도록 통합을 설계합니다.
**참고**
동기`Bundle`식 유형은 최대 100개의 리소스를 `transaction` 계속 지원하며 기본 처리 모드입니다. `Prefer: respond-async` 헤더 없이 리소스`transaction`가 100개 이상인 `Bundle` 유형을 제출하면 HealthLake가 `422 Unprocessable Entity` 오류를 반환합니다. 유형의 번들`batch`은 비동기 처리에 지원되지 않습니다. `Bundle` 유형만 비동기적으로 제출할 수 `transaction` 있습니다(최대 500개의 작업 사용).
### 비동기 트랜잭션 제출
비동기 트랜잭션을 제출하려면 `Prefer: respond-async` 헤더를 사용하여 데이터 스토어 엔드포인트에 `POST` 요청을 보냅니다. 번들에는 유형이 있어야 합니다`transaction`. 유형의 번들`batch`은 비동기 번들 처리에 지원되지 않습니다.
HealthLake는 제출 시 번들에 대한 초기 검증을 수행합니다. 검증에 성공하면 HealthLake는 폴링 URL이 포함된 `content-location` 응답 헤더와 함께 HTTP 202 Accepted를 반환합니다.
**비동기 `Bundle` 유형을 제출하려면 `transaction`**
1. HealthLake 데이터 스토어 엔드포인트에 `POST` 요청을 보냅니다.
```
POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/
```
1. 번들 유형이 인 요청에 대한 JSON 본문을 구성합니다`transaction`. 이 절차의 목적상 파일을 로 저장합니다`async-transaction.json`.
```
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"resource": {
"resourceType": "Patient",
"active": true,
"name": [
{
"use": "official",
"family": "Smith",
"given": ["Jane"]
}
],
"gender": "female",
"birthDate": "1990-01-15"
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"resource": {
"resourceType": "Observation",
"status": "final",
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "85354-9",
"display": "Blood pressure panel"
}
]
},
"subject": {
"reference": "urn:uuid:example-patient-id"
}
},
"request": {
"method": "POST",
"url": "Observation"
}
}
]
}
```
1. `Prefer: respond-async` 헤더와 함께 요청을 전송합니다. FHIR `Bundle` 트랜잭션 유형은 FHIR 권한 부여 시 [AWS 서명 버전 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 또는 SMART인 `POST` 요청을 사용합니다. 다음 코드 예제에서는 데모용으로 `curl` 명령줄 도구를 사용합니다.
------
#### [ SigV4 ]
SigV4 권한 부여
```
curl --request POST \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json' \
--header 'Prefer: respond-async' \
--data @async-transaction.json
```
------
#### [ SMART on FHIR ]
[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 데이터 형식에 대한 SMART on FHIR 권한 부여 예제입니다.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
호출자는 권한 부여 Lambda에 권한을 할당할 수 있습니다. 자세한 내용은 [OAuth 2.0 범위](reference-smart-on-fhir-oauth-scopes.md) 단원을 참조하십시오.
------
1. 제출에 성공하면 서버는 HTTP 202 Accepted를 반환합니다. `content-location` 응답 헤더에는 폴링 URL이 포함되어 있습니다. 응답 본문은 `OperationOutcome` 리소스입니다.
```
HTTP/1.1 202 Accepted
content-location: https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Transaction/transactionId
```
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "Submitted Asynchronous Bundle Transaction",
"location": [
"https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Transaction/transactionId"
]
}
]
}
```
### 트랜잭션 상태에 대한 폴링
비동기 트랜잭션을 제출한 후 `content-location` 응답 헤더의 폴링 URL을 사용하여 트랜잭션 상태를 확인합니다. 폴링 URL에 `GET` 요청을 보냅니다.
**참고**
FHIR 지원 데이터 스토어의 SMART의 경우, 권한 부여 토큰에는 트랜잭션 상태를 폴링할 `Transaction` 리소스 유형에 대한 `read` 권한이 포함되어야 합니다. FHIR 범위의 SMART에 대한 자세한 내용은 섹션을 참조하세요[HealthLake에서 지원하는 FHIR OAuth 2.0 범위의 SMART](reference-smart-on-fhir-oauth-scopes.md).
폴링 URL에 `GET` 요청을 보냅니다. 다음 예제에서는 `curl` 명령줄 도구를 사용합니다.
------
#### [ SigV4 ]
SigV4 권한 부여
```
curl --request GET \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Transaction/transactionId' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json'
```
------
#### [ SMART on FHIR ]
FHIR 권한 부여에 대한 SMART. 권한 부여 토큰에는 `Transaction` 리소스 유형에 대한 `read` 권한이 포함되어야 합니다.
```
curl --request GET \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Transaction/transactionId' \
--header 'Authorization: Bearer $SMART_ACCESS_TOKEN' \
--header 'Accept: application/json'
```
------
다음 표에서는 가능한 응답을 설명합니다.
**응답 코드 폴링**
| HTTP 상태 | 의미 | 응답 본문 |
| --- | --- | --- |
| 202 수락됨 | 트랜잭션이 대기열에 있음 | OperationOutcome "SUBMITTED" 진단 포함 |
| 202 수락됨 | 트랜잭션 처리 중 | OperationOutcome 진단 "IN\$1PROGRESS" 사용 |
| 200 OK | 트랜잭션이 성공적으로 완료되었습니다. | Bundle 유형 포함 transaction-response |
| 4xx/5xx | 트랜잭션 실패 | OperationOutcome 오류 세부 정보가 있는 |
다음 예제에서는 각 응답 유형을 보여줍니다.
**트랜잭션 대기 중(202)**
```
{
"resourceType": "OperationOutcome",
"id": "transactionId",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "SUBMITTED"
}
]
}
```
**트랜잭션 처리(202)**
```
{
"resourceType": "OperationOutcome",
"id": "transactionId",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "IN_PROGRESS"
}
]
}
```
**트랜잭션 완료(200)**
```
{
"resourceType": "Bundle",
"type": "transaction-response",
"entry": [
{
"response": {
"status": "201",
"location": "Patient/example-id/_history/1",
"etag": "W/\"1\"",
"lastModified": "2024-01-15T10:30:00.000Z"
}
},
{
"response": {
"status": "201",
"location": "Observation/example-id/_history/1",
"etag": "W/\"1\"",
"lastModified": "2024-01-15T10:30:00.000Z"
}
}
]
}
```
**트랜잭션 실패(4xx/5xx)**
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "exception",
"diagnostics": "Transaction failed: conflict detected on resource Patient/example-id"
}
]
}
```
### 주문 처리
유형의 비동기 번들`transaction`은 대기열에 있지만 엄격한 제출 순서로 처리되지 않습니다. HealthLake는 사용 가능한 용량 및 시스템 부하를 기반으로 처리를 최적화합니다.
**중요**
제출된 순서대로 처리 중인 트랜잭션에 의존하지 마십시오. 예를 들어 오전 10시에 트랜잭션 A를 제출하고 오전 10시 1분에 트랜잭션 B를 제출하는 경우 트랜잭션 B는 트랜잭션 A 이전에 완료될 수 있습니다. 애플리케이션을 다음과 같이 설계하세요.
out-of-order 처리합니다.
폴링 URL을 사용하여 각 트랜잭션을 독립적으로 추적합니다.
사용 사례에 주문이 중요한 경우 애플리케이션 수준 시퀀싱을 구현합니다.
### 할당량 및 제한
다음 할당량 및 속도 제한은 비동기 트랜잭션에 적용됩니다.
**비동기 트랜잭션 할당량**
| 할당량 | 값 | 조정 가능 |
| --- | --- | --- |
| 비동기 트랜잭션당 최대 작업 수 | 500 | 아니요 |
| 데이터 스토어당 최대 보류 중인 트랜잭션 수 | 500 | 예 |
+ 비동기 트랜잭션은에 정의된 것과 동일한 API 속도 제한을 공유합니다[Service Quotas](reference-healthlake-endpoints-quotas.md#reference-healthlake-quotas).
+ 트랜잭션 상태에 대한 폴링은 FHIR 리소스에 대한 읽기(`GET`) 작업과 동일한 API 속도 제한을 공유합니다.
+ 보류 중인 트랜잭션 한도에 도달하면 기존 트랜잭션이 완료될 때까지 후속 제출에서 오류가 반환됩니다.
### 오류 처리
'트랜잭션' 번들의 경우 번들에 포함된 모든 FHIR 리소스는 원자성 작업으로 처리됩니다. 작업의 모든 리소스가 성공하거나 번들의 작업이 처리되지 않아야 합니다.
오류는 HealthLake가 동기적으로 반환하는 제출 오류와 폴링을 통해 검색하는 처리 오류의 두 가지 범주로 나뉩니다.
**제출 오류**
HealthLake는 제출 시 번들을 검증하고 트랜잭션이 대기열에 추가되기 전에 동기식으로 오류를 반환합니다. 제출 오류에는 잘못된 FHIR 리소스 검증 오류, 지원되지 않는 리소스 유형, 500개의 작업 제한 초과, 배치 번들과 함께 `Prefer: respond-async` 헤더 사용 등이 포함됩니다. 데이터 스토어에 대해 보류 중인 트랜잭션 한도에 도달하면 HealthLake는를 반환합니다`ThrottlingException`. 제출 오류가 발생하면 트랜잭션이 대기열에 추가되지 않습니다.
**처리 오류**
처리 오류는 트랜잭션이 대기열에 추가되고 폴링 URL을 통해 반환된 후에 발생합니다. 여기에는 다른 작업이 트랜잭션의 일부인 리소스를 수정한 트랜잭션 충돌과 처리 중 서버 오류가 포함됩니다. 처리 오류가 발생하면 트랜잭션의 리소스에 대해 리소스 변형이 수행되지 않습니다. 폴링 URL은 오류 세부 정보와 `OperationOutcome` 함께를 반환합니다.
# FHIR 리소스 삭제
FHIR `delete` 상호 작용은 HealthLake 데이터 스토어에서 기존 FHIR 리소스를 제거합니다. 자세한 내용은 **FHIR R4 RESTful API 설명서**[https://hl7.org/fhir/R4/http.html#delete](https://hl7.org/fhir/R4/http.html#delete)의 섹션을 참조하세요.
**FHIR 리소스를 삭제하려면**
1. HealthLake `region` 및 `datastoreId` 값을 수집합니다. 자세한 내용은 [데이터 스토어 속성 가져오기](managing-data-stores-describe.md) 단원을 참조하십시오.
1. 연결된 `id` 값을 `Resource` 삭제하고 수집할 FHIR 유형을 결정합니다. 자세한 내용은 [조건 키](reference-fhir-resource-types.md) 단원을 참조하십시오.
1. HealthLake `region` 및에 대해 수집된 값을 사용하여 요청에 대한 URL을 구성합니다`datastoreId`. FHIR `Resource` 유형 및 관련 도 포함합니다`id`. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다.
```
DELETE https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id
```
1. 요청을 보냅니다. FHIR `delete` 상호 작용은 FHIR 권한 부여 시 [AWS 서명 버전 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 또는 SMART와 함께 `DELETE` 요청을 사용합니다. 다음 `curl` 예시에서는 HealthLake 데이터 스토어에서 기존 FHIR `Patient` 리소스를 제거합니다. 전체 예제를 보려면 **복사** 버튼을 스크롤합니다.
------
#### [ SigV4 ]
SigV4 권한 부여
```
curl --request DELETE \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json'
```
서버는 리소스가 HealthLake 데이터 스토어에서 제거되었음을 확인하는 `204` HTTP 상태 코드를 반환합니다. 삭제 요청이 실패하면 요청이 실패한 이유를 나타내는 `400` 일련의 HTTP 상태 코드를 받게 됩니다.
------
#### [ SMART on FHIR ]
[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 데이터 형식에 대한 SMART on FHIR 권한 부여 예제입니다.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
호출자는 권한 부여 Lambda에서 권한을 할당할 수 있습니다. 자세한 내용은 [OAuth 2.0 범위](reference-smart-on-fhir-oauth-scopes.md) 단원을 참조하십시오.
------
#### [ AWS Console ]
1. HealthLake 콘솔의 [쿼리 실행](https://console.aws.amazon.com/healthlake/home#/crud) 페이지에 로그인합니다.
2. **쿼리 설정** 섹션에서 다음을 선택합니다.
+ **데이터 스토어 ID** - 쿼리 문자열을 생성할 데이터 스토어 ID를 선택합니다.
+ **쿼리 유형** -를 선택합니다`Delete`.
+ **리소스 유형** - 삭제할 FHIR [리소스 유형을](reference-fhir-resource-types.md) 선택합니다.
+ **리소스 ID** - FHIR 리소스 ID를 입력합니다.
3. **쿼리 실행**을 선택합니다.
------
## 조건에 따라 FHIR 리소스 삭제
조건부 삭제는 특정 FHIR 리소스 ID를 모르지만 삭제하려는 리소스에 대한 다른 식별 정보가 있는 경우에 특히 유용합니다.
조건부 삭제를 사용하면 논리적 FHIR ID가 아닌 검색 기준에 따라 기존 리소스를 삭제할 수 있습니다. 서버는 삭제 요청을 처리할 때 리소스 유형에 대한 표준 검색 기능을 사용하여 검색을 수행하여 요청에 대한 단일 논리적 ID를 확인합니다.
### 조건부 삭제 작동 방식
**서버의 작업은 검색한 일치 항목 수에 따라 달라집니다.**
1. **일치 항목 없음**: 서버가 일반 삭제를 시도하고 적절하게 응답합니다(404 존재하지 않는 리소스의 경우 찾을 수 없음, 204 이미 삭제된 리소스의 경우 콘텐츠 없음).
1. **일치하는 항목 하나**: 서버가 일치하는 리소스에서 일반 삭제를 수행합니다.
1. **여러 일치** 항목: 클라이언트의 기준이 충분히 선택적이지 않음을 나타내는 412 사전 조건 실패 오류를 반환합니다.
### 대응 시나리오
AWS HealthLake 는 다음과 같은 응답 패턴으로 조건부 삭제 작업을 처리합니다.
**성공한 작업**
+ 검색 기준이 단일 활성 리소스를 성공적으로 식별하면 시스템은 표준 삭제 작업과 마찬가지로 삭제를 완료한 후 **204 콘텐츠 없음을** 반환합니다.
**ID 기반 조건부 삭제**
추가 파라미터(`createdAt`, `tag`또는 )`id`를 사용하여를 기반으로 조건부 삭제를 수행하는 경우`_lastUpdated`:
+ **204 콘텐츠 없음**: 리소스가 이미 삭제되었습니다.
+ **404 찾을 수 없음**: 리소스가 존재하지 않음
+ **409 충돌**: ID는 일치하지만 다른 파라미터는 일치하지 않음
**Non-ID-Based 조건부 삭제**
`id`가 제공되지 않거나 `createdAt`, 또는 이외의 파라미터를 사용하는 경우`tag``_lastUpdated`:
+ **404 찾을 수 없음**: 일치하는 항목을 찾을 수 없음
**충돌 상황**
여러 시나리오에서 412개의 사전 조건 실패 응답이 발생합니다.
+ 여러 리소스가 검색 기준과 일치(기준이 충분히 구체적이지 않음)
+ 에서 ETag 헤더 사용 시 버전 충돌 `If-Match`
+ 검색 및 삭제 작업 사이에 발생하는 리소스 업데이트
**성공적인 조건부 삭제의 예**
다음 예시에서는 특정 기준에 따라 환자 리소스를 삭제합니다.
```
DELETE https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?name=peter&birthdate=2000-01-01&phone=1234567890
```
이 요청은 다음과 같은 환자 리소스를 삭제합니다.
+ 이름은 "peter"입니다.
+ 생년월일은 2000년 1월 1일입니다.
+ 전화번호는 1234567890입니다.
**모범 사례**
1. 특정 검색 기준을 사용하여 여러 일치 항목을 방지하고 412 오류를 방지합니다.
1. 동시 수정을 처리하는 데 필요한 경우 버전 관리를 위해 ETag 헤더를 고려합니다.
1. 오류 응답을 적절하게 처리합니다.
+ 404의 경우: 검색 기준 구체화
+ 412의 경우: 기준을 더 구체적으로 지정하거나 버전 충돌 해결
1. 검색 작업과 삭제 작업 간에 리소스를 수정할 수 있는 동시성이 높은 환경에서 타이밍 충돌에 대비합니다.
# 자격 증명 및 동시성
## 자격 증명 키
AWS HealthLake 는 FHIR `POST` 작업에 대한 멱등성 키를 지원하여 리소스 생성 중에 데이터 무결성을 보장하는 강력한 메커니즘을 제공합니다. 고유한 UUID를 요청 헤더에 멱등성 키로 포함하면 의료 애플리케이션은 네트워크 불안정 또는 자동 재시도와 관련된 시나리오에서도 각 FHIR 리소스가 정확히 한 번 생성되도록 보장할 수 있습니다.
이 기능은 중복 의료 기록이 심각한 결과를 초래할 수 있는 의료 시스템에 특히 중요합니다. 이전 요청과 동일한 멱등성 키로 요청이 수신되면 HealthLake는 복제본을 생성하는 대신 원본 리소스를 반환합니다. 예를 들어 재시도 루프 중에 또는 중복 요청 파이프라인으로 인해 발생할 수 있습니다. 멱등성 키를 사용하면 HealthLake가 데이터 일관성을 유지하면서 간헐적인 연결 문제를 처리하는 클라이언트 애플리케이션에 원활한 환경을 제공할 수 있습니다.
### 구현
```
POST //Patient
x-amz-fhir-idempotency-key: 123e4567-e89b-12d3-a456-426614174000
{
"resourceType": "Patient",
"name": [...]
}
```
### 응답 시나리오
첫 번째 요청(201 생성됨)
+ 새 리소스가 성공적으로 생성됨
+ 응답에 리소스 ID 포함
중복 요청(409 충돌)
+ 동일한 멱등성 키가 감지됨
+ 반환된 원본 리소스
+ 새 리소스가 생성되지 않음
잘못된 요청(400 잘못된 요청)
+ 잘못된 UUID
+ 필수 필드 누락
### 모범 사례
+ 각 새 리소스 생성에 대해 고유한 UUID 생성
+ 재시도 로직에 대한 멱등성 키 저장
+ 일관된 키 형식 사용: UUID v4 권장
+ 리소스 생성을 처리하는 클라이언트 애플리케이션에서 구현
**참고**
이 기능은 엄격한 데이터 정확도를 요구하고 중복 의료 기록을 방지하는 의료 시스템에 특히 유용합니다.
## AWS HealthLake의 ETag
AWS HealthLake 는 FHIR 리소스의 낙관적 동시성 제어에 ETags 사용하여 동시 수정을 관리하고 데이터 일관성을 유지하는 신뢰할 수 있는 메커니즘을 제공합니다. ETag는 리소스의 특정 버전을 나타내는 고유 식별자로, HTTP 헤더를 통해 버전 관리 시스템으로 작동합니다. 리소스를 읽거나 수정할 때 애플리케이션은 ETags 사용하여 의도하지 않은 덮어쓰기를 방지하고 특히 잠재적 동시 업데이트가 있는 시나리오에서 데이터 무결성을 보장할 수 있습니다.
### 구현 예제
```
// Initial Read
GET /fhir/Patient/123
Response:
ETag: W/"1"
// Update with If-Match
PUT /fhir/Patient/123
If-Match: W/"1"
{resource content}
// Create with If-None-Match
PUT /fhir/Patient/123
If-None-Match: *
{resource content}
// Succeeds only if resource doesn't exist
// Fails with 412 if resource exists
```
### 응답 시나리오
성공한 작업(200 OK 또는 204 No Content)
+ ETag가 현재 버전과 일치
+ 작업이 의도한 대로 진행됨
버전 충돌(412 사전 조건 실패)
+ ETag가 현재 버전과 일치하지 않음
+ 데이터 손실을 방지하기 위해 업데이트가 거부됨
### 모범 사례
+ 모든 업데이트 및 삭제 작업에 ETags 포함
+ 버전 충돌을 처리하기 위한 재시도 로직 구현
+ If-None-Match 사용: create-if-not-exists 시나리오의 경우 \$1
+ 수정하기 전에 항상 ETag 최신 상태 확인
이 동시성 제어 시스템은 특히 여러 사용자 또는 시스템이 동일한 리소스에 액세스하고 수정하는 환경에서 의료 데이터의 무결성을 유지하는 데 필수적입니다.