FHIR REST API オペレーションを使用した HealthLake データストアからのデータのエクスポート

を完了するとエクスポートジョブのアクセス許可の設定、 FHIRRESTAPIオペレーションを使用して HealthLake データストアからデータをエクスポートできます。を使用してエクスポートリクエストを行うにはFHIRRESTAPI、必要なアクセス許可を持つIAMユーザー、グループ、またはロールがあり、POSTリクエスト$exportの一部として を指定し、リクエストの本文にリクエストパラメータを含める必要があります。FHIR 仕様に従って、FHIRサーバーは GETリクエストをサポートする必要があります。また、 は POSTリクエストをサポートできます。追加のパラメータをサポートするには、エクスポートを開始するのに本文が必要です。したがって、 はPOSTリクエスト HealthLake をサポートします。

重要

HealthLake 2023 年 6 月 1 日より前に作成された データストアは、システム全体のエクスポートに対するFHIRRESTAPIエクスポートジョブリクエストのみをサポートします。

HealthLake 2023 年 6 月 1 日より前に作成された データストアは、データストアのエンドポイントに対するGETリクエストを使用したエクスポートのステータスの取得をサポートしていません。

を使用して行うすべてのエクスポートリクエストFHIRRESTAPIは ndjson形式で返され、Amazon S3 バケットにエクスポートされます。各 S3 オブジェクトには、1 つのFHIRリソースタイプのみが含まれます。

AWS アカウントクォータに従ってエクスポートリクエストをキューに入れることができます。に関連付けられている Service Quotas の詳細については HealthLake、「」を参照してくださいAWS HealthLake エンドポイントとクォータ。

HealthLake では、次の 3 種類の一括エクスポートエンドポイントリクエストがサポートされています。

Type	説明	構文
システムエクスポート	サーバーからすべてのデータをエクスポートします HealthLake FHIR。	POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/$export
すべての患者	患者リソースタイプに関連付けられたリソースタイプを含む、すべての患者に関連するすべてのデータをエクスポートします。	POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Patient/$export
病棟のグループ	グループ ID で指定された患者のグループに関連するすべてのデータをエクスポートします。	POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Group/ID/$export

[開始する前に]

for を使用してエクスポートリクエストを行うには、次の要件を満たFHIRRESTAPIします HealthLake。

• エクスポートリクエストを行うために必要なアクセス許可を持つユーザー、グループ、またはロールを設定しておく必要があります。詳細については、「export リクエストの承認」を参照してください。

• データをエクスポートする Amazon S3 バケット HealthLake へのアクセスを許可するサービスロールを作成しておく必要があります。サービスロールでは、 をサービスプリンシパル HealthLake として指定する必要があります。アクセス許可の設定の詳細については、「」を参照してくださいエクスポートジョブのアクセス許可の設定。

export リクエストの承認

を使用してエクスポートリクエストを正常に実行するにはAPI、 IAM または FHIR REST OAuth2.0 を使用してユーザー、グループ、またはロールを承認します。サービスロールも必要です。

を使用したリクエストの承認 IAM

$export リクエストを行うとき、ユーザー、グループ、またはロールには、ポリシーに StartFHIRExportJobWithPost、DescribeFHIRExportJobWithGet、および CancelFHIRExportJobWithDeleteIAMアクションが含まれている必要があります。

重要

HealthLake SDK StartFHIRExportJobAPIオペレーションを使用したリクエストのエクスポートと StartFHIRExportJobWithPostAPIオペレーションを使用したリクエストのFHIRRESTAPIエクスポートには、個別のIAMアクションがあります。を使用したSDKエクスポートStartFHIRExportJobと を使用したFHIRRESTAPIエクスポートの各IAMアクションではStartFHIRExportJobWithPost、許可/拒否のアクセス許可を個別に処理できます。SDK と の両方のFHIRRESTAPIエクスポートを制限する場合は、各IAMアクションのアクセス許可を必ず拒否してください。

( 2FHIR.0) SMARTでOAuth を使用してリクエストを承認する

FHIR 有効な HealthLake データストアSMARTで を$exportリクエストするときは、適切なスコープを割り当てる必要があります。サポートされているスコープの詳細については、「」を参照してくださいHealthLake データストアFHIRリソース固有のスコープ。

export リクエストの実行

このセクションでは、 FHIR REST を使用してエクスポートリクエストを行うときに必要な手順について説明しますAPI。

AWS アカウントで誤って課金されないように、 export構文を指定せずに リクエストを実行してPOSTリクエストをテストすることをお勧めします。

リクエストを行うには、以下を実行する必要があります。

1. サポートされているエンドポイントURLのexportPOSTリクエストで を指定します。

2. 必要なヘッダーパラメータを指定します。

3. 必要なパラメータを定義するリクエストボディを指定します。

ステップ 1: サポートされているエンドポイントURLのPOSTリクエストexportで を指定する

HealthLake は、3 種類の一括エクスポートエンドポイントリクエストをサポートしています。一括エクスポートリクエストを行うには、サポートされている 3 つのエンドポイントのいずれかに対して POSTベースのリクエストを行う必要があります。次の例は、リクエスト exportで を指定する方法を示していますURL。

• POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/$export

• POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Patient/$export

• POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Group/ID/$export

そのPOSTリクエスト文字列では、以下のサポートされている検索パラメータを使用できます。

サポートされている検索パラメータ

HealthLake では、一括エクスポートリクエストで次の検索修飾子がサポートされています。

これらの例には、リクエストを送信する前にエンコードする必要がある特殊文字が含まれています。

名前	必須?	説明	例
_outputFormat	いいえ	リクエストされた一括データファイルを生成する形式。使用できる値は、application/fhir+ndjson、application/ndjson、 ですndjson。
_type	いいえ	エクスポートジョブに含めるカンマ区切りのFHIRリソースタイプの文字列。すべてのリソースをエクスポートするとコストがかかる_type可能性があるため、 を含めることをお勧めします。	&_type=MedicationStatement, Observation
_since	いいえ	日付タイムスタンプ以降に変更されたリソースタイプ。リソースタイプに最終更新時刻がない場合、レスポンスに含まれます。	&_since=2024-05-09T00%3A00%3A00Z

ステップ 2: 必要なヘッダーパラメータを指定する

を使用してエクスポートリクエストを行うにはAPI、次の 2 FHIR REST つのヘッダーパラメータを指定する必要があります。

• Content-Type：application/fhir+json

• 優先: respond-async

次に、リクエストボディに必要な要素を指定する必要があります。

ステップ 3: で必要なパラメータを定義するリクエスト本文を指定します。

エクスポートリクエストには、 JSON 形式の本文も必要です。本文には、次のパラメータを含めることができます。

キー	必須?	説明	値
DataAccessRoleArn	はい	HealthLake サービスロールARNの 。使用するサービスロールは、サービスプリンシパル HealthLake として を指定する必要があります。	arn:aws:iam::444455556666:role/your-healthlake-service-role
JobName	いいえ	エクスポートリクエストの名前。	your-export-job-name
S3Uri	はい	OutputDataConfig キーの一部。エクスポートされたデータがダウンロードされる送信先バケットURIの S3。	s3://DOC-EXAMPLE-DESTINATION-BUCKET/EXPORT-JOB/
KmsKeyId	はい	OutputDataConfig キーの一部。Amazon S3 バケットの保護に使用される AWS KMS キーARNの 。 Amazon S3	arn:aws:kms:region-of-bucket:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab

例 – を使用して行われたエクスポートリクエストの本文 FHIR REST API

を使用してエクスポートリクエストを行うにはFHIRRESTAPI、次に示すように本文を指定する必要があります。

{
  "DataAccessRoleArn": "arn:aws:iam::444455556666:role/your-healthlake-service-role",
  "JobName": "your-export-job",
  "OutputDataConfig": {
    "S3Configuration": {
      "S3Uri": "s3://DOC-EXAMPLE-DESTINATION-BUCKET/EXPORT-JOB",
      "KmsKeyId": "arn:aws:kms:region-of-bucket:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab"
    }
  }
}

リクエストが成功すると、次のレスポンスを受け取ります。

レスポンスヘッダー

content-location: https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/export/your-export-request-job-id

レスポンス本文

{
  "datastoreId": "your-data-store-id",
  "jobStatus": "SUBMITTED",
  "jobId": "your-export-request-job-id"
}

エクスポートリクエストの管理

エクスポートリクエストが成功したら、 exportを使用して現在のエクスポートリクエストのステータスを記述し、 exportを使用して現在のエクスポートリクエストをキャンセルすることで、そのリクエストを管理できます。

を使用してエクスポートリクエストをキャンセルするとRESTAPI、キャンセルリクエストを送信した時点までにエクスポートされたデータの一部に対してのみ請求されます。

以下のトピックでは、現在のエクスポートリクエストのステータスを取得またはキャンセルする方法について説明します。

エクスポートリクエストのキャンセル

エクスポートリクエストをキャンセルするには、DELETEリクエストを作成し、リクエスト でジョブ ID を指定しますURL。

DELETE https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/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.your-region.amazonaws.com/datastore/your-datastore-id/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 オブジェクトの一部。エクスポートされたデータがダウンロードされるレプリケート先バケットURIの Amazon S3。	s3://DOC-EXAMPLE-DESTINATION-BUCKET/EXPORT-JOB/
KmsKeyId	はい	OutputDataConfig オブジェクトの一部。Amazon S3 バケットの保護に使用される AWS KMS キーARNの 。 Amazon S3	arn:aws:kms:region-of-bucket:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab

例 : を使用して行われた describe エクスポートリクエストの本文 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://DOC-EXAMPLE-DESTINATION-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",
  }
}