기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# FHIR을 사용하여 HealthLake 데이터 내보내기 `$export`
FHIR \$1export 작업을 사용하여 HealthLake 데이터 스토어에서 대량으로 데이터를 내보낼 수 있습니다. HealthLake는 `POST` 및 `GET` 요청을 `$export` 사용하여 FHIR을 지원합니다. 를 사용하여 내보내기 요청을 수행하려면 필요한 권한이 있는 IAM 사용자, 그룹 또는 역할이 있어야 하며 요청의 `$export` 일부로를 지정하고 요청 본문에 원하는 파라미터를 포함해야 `POST`합니다.
**참고**
FHIR을 사용하여 이루어진 모든 HealthLake 내보내기 요청은 `ndjson` 형식으로 반환되고 Amazon S3 버킷으로 내보내`$export`집니다. 여기서 각 Amazon S3 객체에는 단일 FHIR 리소스 유형만 포함됩니다.
AWS 계정 서비스 할당량당 내보내기 요청을 대기열에 넣을 수 있습니다. 자세한 내용은 [Service Quotas](reference-healthlake-endpoints-quotas.md#reference-healthlake-quotas) 단원을 참조하십시오.
HealthLake는 다음과 같은 세 가지 유형의 대량 내보내기 엔드포인트 요청을 지원합니다.
**HealthLake 대량 `$export` 유형**
| 내보내기 유형 | 설명 | 구문 |
| --- | --- | --- |
| 시스템 | HealthLake FHIR 서버에서 모든 데이터를 내보냅니다. | `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/$export` |
| 모든 환자 | 환자 리소스 유형과 연결된 리소스 유형을 포함하여 모든 환자와 관련된 모든 데이터를 내보냅니다. | `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/$export` `GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/$export` |
| 환자 그룹 | 그룹 ID로 지정된 환자 그룹과 관련된 모든 데이터를 내보냅니다. | `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Group/id/$export` `GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Group/id/$export` |
## 시작하기 전 준비 사항
HealthLake용 FHIR REST API를 사용하여 내보내기 요청을 하려면 다음 요구 사항을 충족해야 합니다.
+ 내보내기 요청을 수행하는 데 필요한 권한이 있는 사용자, 그룹 또는 역할을 설정해야 합니다. 자세한 내용은 [`$export` 요청 권한 부여](#export-rest-auth)를 참조하세요.
+ 데이터를 내보낼 Amazon S3 버킷에 대한 HealthLake 액세스 권한을 부여하는 서비스 역할을 생성해야 합니다. 또한 서비스 역할은 HealthLake를 서비스 보안 주체로 지정해야 합니다. 권한 설정에 대한 자세한 내용은 섹션을 참조하세요[내보내기 작업에 대한 권한 설정](getting-started-setting-up.md#setting-up-export-permissions).
## `$export` 요청 권한 부여
FHIR REST API를 사용하여 내보내기 요청을 성공적으로 수행하려면 IAM 또는 OAuth2.0. 서비스 역할도 있어야 합니다.
**IAM을 사용하여 요청 권한 부여**
`$export` 요청을 할 때 사용자, 그룹 또는 역할에 IAM 작업이 정책에 포함되어야 합니다. 자세한 내용은 [내보내기 작업에 대한 권한 설정](getting-started-setting-up.md#setting-up-export-permissions) 단원을 참조하십시오.
**FHIR(OAuth 2.0)에서 SMART를 사용하여 요청 권한 부여**
FHIR 지원 HealthLake 데이터 스토어의 SMART에서 `$export` 요청할 때는 적절한 범위가 할당되어 있어야 합니다. 자세한 내용은 [HealthLake의 FHIR 리소스 범위에 대한 SMART](reference-smart-on-fhir-oauth-scopes.md#smart-on-fhir-scopes-rest) 단원을 참조하십시오.
**참고**
`GET` 요청이 `$export` 있는 FHIR은 내보내기 및 검색 파일을 요청하기 위해 동일한 인증 방법 또는 보유자 토큰(FHIR에서 SMART인 경우)이 필요합니다. `$export`에서 FHIR을 사용하여 내보낸 파일은 48시간 동안 다운로드할 `GET` 수 있습니다.
## `$export` 요청하기
이 섹션에서는 FHIR REST API를 사용하여 내보내기 요청을 할 때 수행해야 하는 필수 단계를 설명합니다.
AWS 계정에 실수로 요금이 부과되지 않도록 `$export` 구문을 제공하지 않고 `POST` 요청하여 요청을 테스트하는 것이 좋습니다.
요청을 하려면 다음을 수행해야 합니다.
1. 지원되는 엔드포인트에 대한 `POST` 요청 URL`$export`에서를 지정합니다.
1. 필요한 헤더 파라미터를 지정합니다.
1. 필요한 파라미터를 정의하는 요청 본문을 지정합니다.
### 1단계: 지원되는 [엔드포인트](reference-healthlake-endpoints-quotas.md#reference-healthlake-endpoints)의 `POST` 요청 URL`$export`에서를 지정합니다.
HealthLake는 세 가지 유형의 대량 내보내기 엔드포인트 요청을 지원합니다. 대량 내보내기 요청을 하려면 지원되는 세 엔드포인트 중 하나에 대해 `POST`기반 요청을 해야 합니다. 다음 예제에서는 요청 URL`$export`에서를 지정할 위치를 보여줍니다.
+ `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/$export`
+ `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/$export`
+ `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Group/id/$export`
`POST` 요청 문자열에서 다음과 같이 지원되는 검색 파라미터를 사용할 수 있습니다.
#### 지원되는 검색 파라미터
HealthLake는 대량 내보내기 요청에서 다음과 같은 검색 한정자를 지원합니다.
다음 예제에는 요청을 제출하기 전에 인코딩해야 하는 특수 문자가 포함되어 있습니다.
| 이름 | 필수? | 설명 | 예제 |
| --- | --- | --- | --- |
| \$1outputFormat | 아니요 | 생성할 요청된 대량 데이터 파일의 형식입니다. 허용되는 값은 application/fhir\$1ndjson, application/ndjson, 입니다ndjson. | |
| \$1type | 아니요 | 내보내기 작업에 포함할 쉼표로 구분된 FHIR 리소스 유형의 문자열입니다. 모든 리소스를 내보낼 때 비용에 영향을 미칠 수 \$1type 있으므로를 포함하는 것이 좋습니다. | &\$1type=MedicationStatement, Observation |
| \$1since | 아니요 | 날짜 타임스탬프 당일 또는 이후에 수정된 리소스 유형입니다. 리소스 유형에 마지막으로 업데이트된 시간이 없는 경우 응답에 포함됩니다. | &\$1since=2024-05-09T00%3A00%3A00Z |
| \$1until | 아니요 | 날짜 타임스탬프 또는 그 이전에 수정된 리소스 유형입니다. 내보내기를 위한 특정 시간 범위를 정의\$1since하기 위해와 함께 사용됩니다. 리소스 유형에 마지막으로 업데이트된 시간이 없는 경우 응답에서 제외됩니다. | &\$1until=2024-12-31T23%3A59%3A59Z |
### 2단계: 필수 헤더 파라미터 지정
FHIR REST API를 사용하여 내보내기 요청을 하려면 다음 헤더 파라미터를 지정해야 합니다.
+ 콘텐츠 타입: `application/fhir+json`
+ 선호 사항: `respond-async`
다음으로 요청 본문에 필수 요소를 지정해야 합니다.
### 3단계: 필요한 파라미터를 정의하는 요청 본문을 지정합니다.
내보내기 요청에는 `JSON` 형식의 본문도 필요합니다. 본문에는 다음 파라미터가 포함될 수 있습니다.
| Key(키) | 필수? | 설명 | 값 |
| --- | --- | --- | --- |
| DataAccessRoleArn | 예 | HealthLake 서비스 역할의 ARN입니다. 사용되는 서비스 역할은 HealthLake를 서비스 보안 주체로 지정해야 합니다. | arn:aws:iam::444455556666:role/your-healthlake-service-role |
| JobName | 아니요 | 내보내기 요청의 이름입니다. | your-export-job-name |
| S3Uri | 예 | OutputDataConfig 키의 일부입니다. 내보낸 데이터를 다운로드할 대상 버킷의 S3 URI입니다. | s3://amzn-s3-demo-bucket/EXPORT-JOB/ |
| KmsKeyId | 예 | OutputDataConfig 키의 일부입니다. Amazon S3 버킷을 보호하는 데 사용되는 AWS KMS 키의 ARN입니다. | arn:aws:kms:region-of-bucket:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab |
**Example FHIR REST API를 사용하여 수행된 내보내기 요청의 본문**
FHIR REST API를 사용하여 내보내기 요청을 하려면 다음과 같이 본문을 지정해야 합니다.
```
{
"DataAccessRoleArn": "arn:aws:iam::444455556666:role/your-healthlake-service-role",
"JobName": "your-export-job",
"OutputDataConfig": {
"S3Configuration": {
"S3Uri": "s3://amzn-s3-demo-bucket/EXPORT-JOB",
"KmsKeyId": "arn:aws:kms:region-of-bucket:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
}
```
요청이 성공하면 다음과 같은 응답을 받게 됩니다.
*응답 헤더*
```
content-location: https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/export/your-export-request-job-id
```
*응답 본문*
```
{
"datastoreId": "your-data-store-id",
"jobStatus": "SUBMITTED",
"jobId": "your-export-request-job-id"
}
```
## 내보내기 요청 관리
내보내기 요청이 성공하면를 사용하여 요청을 관리`$export`하여 현재 내보내기 요청의 상태를 설명하고 현재 내보내기 요청을 `$export` 취소할 수 있습니다.
REST API를 사용하여 내보내기 요청을 취소하면 취소 요청을 제출한 시점까지 내보낸 데이터 부분에 대해서만 요금이 청구됩니다.
다음 주제에서는 현재 내보내기 요청의 상태를 가져오거나 취소할 수 있는 방법을 설명합니다.
### 내보내기 요청 취소
내보내기 요청을 취소하려면 `DELETE` 요청을 하고 요청 URL에 작업 ID를 입력합니다.
```
DELETE https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/export/your-export-request-job-id
```
요청이 성공하면 다음을 수신합니다.
```
{
"exportJobProperties": {
"jobId": "your-original-export-request-job-id",
"jobStatus": "CANCEL_SUBMITTED",
"datastoreId": "your-data-store-id"
}
}
```
요청이 성공하지 못하면 다음을 수신합니다.
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "not-supported",
"diagnostics": "Interaction not supported."
}
]
}
```
### 내보내기 요청 설명
내보내기 요청의 상태를 가져오려면 `export` 및를 사용하여 `GET` 요청합니다`export-request-job-id`.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/export/your-export-request-id
```
JSON 응답에는 `ExportJobProperties` 객체가 포함됩니다. 여기에는 다음과 같은 키:값 페어가 포함될 수 있습니다.
| 이름 | 필수? | 설명 | 값 |
| --- | --- | --- | --- |
| DataAccessRoleArn | 아니요 | HealthLake 서비스 역할의 ARN입니다. 사용되는 서비스 역할은 HealthLake를 서비스 보안 주체로 지정해야 합니다. | arn:aws:iam::444455556666:role/your-healthlake-service-role |
| SubmitTime | 아니요 | 내보내기 작업이 제출된 날짜입니다. | Apr 21, 2023 5:58:02 |
| EndTime | 아니요 | 내보내기 작업이 완료된 시간입니다. | Apr 21, 2023 6:00:08 PM |
| JobName | 아니요 | 내보내기 요청의 이름입니다. | your-export-job-name |
| JobStatus | 아니요 | | 유효값은 다음과 같습니다.SUBMITTED | IN_PROGRESS | COMPLETED_WITH_ERRORS | COMPLETED |
FAILED
|
| S3Uri | 예 | [OutputDataConfig](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_OutputDataConfig.html) 객체의 일부입니다. 내보낸 데이터를 다운로드할 대상 버킷의 Amazon S3 URI입니다. | s3://amzn-s3-demo-bucket/EXPORT-JOB/ |
| KmsKeyId | 예 | [OutputDataConfig](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_OutputDataConfig.html) 객체의 일부입니다. Amazon S3 버킷을 보호하는 데 사용되는 AWS KMS 키의 ARN입니다. | arn:aws:kms:region-of-bucket:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab |
**Example : FHIR REST API를 사용하여 수행된 설명 내보내기 요청의 본문**
성공하면 다음과 같은 JSON 응답을 받게 됩니다.
```
{
"exportJobProperties": {
"jobId": "your-export-request-id",
"JobName": "your-export-job",
"jobStatus": "SUBMITTED",
"submitTime": "Apr 21, 2023 5:58:02 PM",
"endTime": "Apr 21, 2023 6:00:08 PM",
"datastoreId": "your-data-store-id",
"outputDataConfig": {
"s3Configuration": {
"S3Uri": "s3://amzn-s3-demo-bucket/EXPORT-JOB",
"KmsKeyId": "arn:aws:kms:region-of-bucket:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab""
}
},
"DataAccessRoleArn": "arn:aws:iam::444455556666:role/your-healthlake-service-role",
}
}
```