本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 FHIR 匯出 HealthLake 資料 `$export` 您可以使用 FHIR \$1export 操作，從 HealthLake 資料存放區大量匯出資料。HealthLake 支援`$export`使用 `POST`和 `GET`請求的 FHIR。若要使用 提出匯出請求`POST`，您必須擁有具有必要許可的 IAM 使用者、群組或角色、指定 `$export`做為請求的一部分，並在請求內文中包含所需的參數。 **注意** 使用 FHIR 提出的所有 HealthLake 匯出請求`$export`都會以 `ndjson` 格式傳回，並匯出至 Amazon S3 儲存貯體，其中每個 Amazon S3 物件僅包含單一 FHIR 資源類型。 您可以根據 AWS 帳戶服務配額將匯出請求排入佇列。如需詳細資訊，請參閱[Service Quotas](reference-healthlake-endpoints-quotas.md#reference-healthlake-quotas)。 HealthLake 支援下列三種類型的大量匯出端點請求。 **HealthLake 大量`$export`類型** | 匯出類型 | Description | 語法 | | --- | --- | --- | | 系統 | 從 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` | ## 開始之前 符合下列要求，以使用 FHIR REST API for HealthLake 提出匯出請求。 + 您必須設定具有提出匯出請求必要許可的使用者、群組或角色。如需詳細資訊，請參閱 [授權 `$export`請求](#export-rest-auth)。 + 您必須已建立服務角色，授予 HealthLake 存取您要將資料匯出至其中的 Amazon S3 儲存貯體的權限。服務角色也必須指定 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 上使用 SMART 授權請求 (OAuth 2.0)** 當您在啟用 FHIR 的 HealthLake 資料存放區上對 SMART 提出`$export`請求時，您必須指派適當的範圍。如需詳細資訊，請參閱[HealthLake 的 FHIR 資源範圍上的 SMART](reference-smart-on-fhir-oauth-scopes.md#smart-on-fhir-scopes-rest)。 **注意** `$export` 具有`GET`請求的 FHIR 需要相同的身分驗證方法或承載字符 （在 FHIR 上使用 SMART 的情況下） 來請求匯出和擷取檔案。使用 FHIR `$export` 搭配 匯出的檔案`GET`可供下載 48 小時。 ## 提出`$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 在大量匯出請求中支援下列搜尋修飾詞。 下列範例包含特殊字元，在提交請求之前必須先編碼。 | 名稱 | 是否為必要？ | Description | 範例 | | --- | --- | --- | --- | | \$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 提出匯出請求，您必須指定下列標頭參數。 + Content-Type： `application/fhir+json` + 偏好： `respond-async` 接著，您必須在請求內文中指定必要的元素。 ### 步驟 3：指定 定義必要參數的請求內文。 匯出請求也需要 `JSON` 格式的內文。內文可以包含下列參數。 | 金錀 | 是否為必要？ | Description | Value | | --- | --- | --- | --- | | 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` 物件。它可能包含下列索引鍵：值對。 | 名稱 | 是否為必要？ | Description | Value | | --- | --- | --- | --- | | 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", } } ```