翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# FHIR リソースのバンドル
FHIR `Bundle`は、 の FHIR リソースのコレクション用のコンテナです AWS HealthLake。 は、処理動作が異なる 2 種類のバンドル AWS HealthLake をサポートしています。
[https://hl7.org/fhir/R4/http.html#transaction](https://hl7.org/fhir/R4/http.html#transaction) バンドルは、各リソースを個別に処理します。1 つのリソースが失敗しても、残りのリソースは成功します。各オペレーションは個別に処理され、一部のオペレーションが失敗しても処理が続行されます。複数の無関係な患者レコードのアップロードなど、部分的な成功が許容される一括操作にはバッチバンドルを使用します。
[https://hl7.org/fhir/R4/http.html#transaction](https://hl7.org/fhir/R4/http.html#transaction) バンドルは、すべてのリソースを 1 つのユニットとしてアトミックに処理します。すべてのリソースオペレーションが成功するか、コミット AWS HealthLake しません。トランザクションバンドルは、すべてのデータを一緒に記録する必要がある、関連する観測値と条件を持つ患者を作成するなど、関連するリソース全体で参照整合性を保証する必要がある場合に使用します。
**バッチバンドルとトランザクションバンドルの違い**
| 機能 | バッチ | トランザクション |
| --- | --- | --- |
| 処理モデル | 各オペレーションは個別に成功または失敗します。 | すべてのオペレーションは 1 つのアトミックユニットとして成功または失敗します。 |
| 障害処理 | 個々のオペレーションが失敗しても処理は続行されます。 | 1 回のオペレーションが失敗すると、バンドル全体が失敗します。 |
| 実行順序 | 実行順序は保証されません。 | オペレーションは指定された順序で処理されます。 |
| 参照整合性 | オペレーション間では適用されません。 | バンドル内のローカルに参照されるリソースに対して強制されます。 |
| 最適なケース | 部分的な成功が許容される一括オペレーション。 | 一緒に作成または更新する必要がある関連リソース。 |
同じタイプまたは異なるタイプの FHIR リソースをバンドルでき、、、`create`、`read``update`、 `delete`などの FHIR オペレーションの組み合わせを含めることができます`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`バッチタイプは、[AWS 署名バージョン 4 ](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)または SMART on FHIR 認可の`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) データ型の FHIR 認可の SMART の例。
```
{
"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 は、次のクエリパラメータを使用してバンドル内の条件付き更新をサポートします。
**注記**
条件付き PUTs は`batch`バンドルでのみサポートされます。 `Transaction`バンドルは条件付き PUTsをサポートしていません。
+ `_id` (スタンドアロン)
+ `_id` を次のいずれかと組み合わせて使用します。
+ `_tag`
+ `_createdAt`
+ `_lastUpdated`
バンドルで条件付き PUTs を使用する場合、 は既存のリソースに対してクエリパラメータ AWS HealthLake を評価し、一致結果に基づいてアクションを実行します。
**条件付き更新動作**
| シナリオ | HTTP ステータス | 実行されたアクション |
| --- | --- | --- |
| ID が指定されていないリソース | 201 作成 | 常に新しいリソースを作成します。 |
| 新しい ID を持つリソース (一致なし) | 201 作成 | 指定された ID で新しいリソースを作成します。 |
| 既存の ID を持つリソース (単一一致) | 200 OK | 一致するリソースを更新します。 |
| 既存の ID を持つリソース (競合が検出されました) | 409 Conflict | エラーを返します。変更は行われません。 |
| 既存の ID を持つリソース (ID の不一致) | 400 Bad Request | エラーを返します。変更は行われません。 |
| 複数のリソースの一致条件 | 412 Precondition Failed | エラーを返します。変更は行われません。 |
次の条件付き更新のバンドル例では、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`。URL `Bundle`の一部として FHIR リソースタイプを含めます。次の例の URL パス全体を表示するには、**コピー**ボタンをスクロールします。
```
POST https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/Bundle
```
1. リクエストの JSON 本文を作成し、グループ化する FHIR リソースを指定します。次の例では、HealthLake で 2 つの`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) データ型の FHIR 認可の SMART の例。
```
{
"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`ドキュメントタイプリクエストの結果として作成された 2 つの`Patient`リソースを示すレスポンスを返します。
## バンドルの検証レベルの設定
FHIR リソースをバンドルする場合、オプションで HTTP `x-amzn-healthlake-fhir-validation-level` ヘッダーを指定して、リソースの検証レベルを設定できます。この検証レベルは、バンドル内のすべての作成および更新リクエストに対して設定されます。 AWS HealthLake は現在、次の検証レベルをサポートしています。
+ `strict`: リソースは、リソースのプロファイル要素、またはプロファイルが存在しない場合は R4 仕様に従って検証されます。これは のデフォルトの検証レベルです AWS HealthLake。
+ `structure-only`: リソースは R4 に対して検証され、参照されるプロファイルは無視されます。
+ `minimal`: リソースは、特定の R4 ルールを無視して、最小限検証されます。検索/分析に必要な構造チェックに失敗したリソースは、監査の警告を含むように更新されます。
最小限の検証レベルにバンドルされたリソースは、検索インデックス作成に必要な検証に失敗しても、Datastore に取り込むことができます。この場合、リソースが更新されて 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 (入室、退室、転送) フィードを取り込むなど、メッセージバンドルをソースで再フォーマットできないシナリオ向けに設計されています。
**警告**
この機能には明示的な AWS アカウント許可リストが必要であり、FHIR R4 メッセージセマンティクスや参照整合性は適用されません。メッセージバンドルを使用する前に、 AWS サポートに連絡してアカウントの有効化をリクエストしてください。
### 標準メッセージ処理との主な違い
+ **メッセージバンドル** (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)に従います。
**非同期トランザクションを使用するタイミング**
+ 1 つのトランザクションで 100 を超えるリソース (同期制限) を送信する必要があります。
+ トランザクション処理の完了を待っている間は、アプリケーションをブロックしないようにします。
+ 大量の関連リソースをより良いスループットで処理する必要があります。
**重要**
ポーリング結果は、トランザクション完了後 90 日間使用できます。この 90 日間の期間が過ぎると、ポーリング URL は結果を返さなくなります。このウィンドウ内で結果を取得して保存する統合を設計します。
**注記**
同期`Bundle`型`transaction`は引き続き最大 100 個のリソースをサポートし、デフォルトの処理モードです。`Prefer: respond-async` ヘッダーなしで 100 を超えるリソース`transaction`を持つ`Bundle`タイプを送信すると、HealthLake は`422 Unprocessable Entity`エラーを返します。タイプのバンドル`batch`は非同期処理ではサポートされていません。`Bundle`タイプのみを非同期で送信`transaction`できます (最大 500 オペレーション）。
**注記**
`PATCH` オペレーションと条件付き PUTsは、非同期バンドルトランザクションではサポートされていません。
### 非同期トランザクションの送信
非同期トランザクションを送信するには、 `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`トランザクションタイプは、[AWS 署名バージョン 4 ](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)または SMART on FHIR 認可のいずれかの`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) データ型の FHIR 認可の SMART の例。
```
{
"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`リクエストを送信します。
**注記**
SMART on FHIR 対応データストアの場合、認可トークンにはトランザクションステータスをポーリングする`Transaction`リソースタイプの`read`アクセス許可が含まれている必要があります。SMART on FHIR スコープの詳細については、「」を参照してください[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 Accepted | トランザクションはキューに入れられます | OperationOutcome 診断「SUBMITTED」を使用する |
| 202 Accepted | トランザクションは処理中です | OperationOutcome 診断「IN\_PROGRESS」を使用する |
| 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 は、使用可能な容量とシステム負荷に基づいて処理を最適化します。
**重要**
送信された順序で処理されているトランザクションに依存しないでください。たとえば、トランザクション A を午前 10:00 に送信し、トランザクション B を午前 10:01 に送信すると、トランザクション B はトランザクション A の前に完了する可能性があります。アプリケーションを設計する目的は次のとおりです。
out-of-orderの完了を処理します。
ポーリング URL を使用して、各トランザクションを個別に追跡します。
ユースケースで注文が重要な場合は、アプリケーションレベルのシーケンスを実装します。
### クォータとスロットリング
非同期トランザクションには、次のクォータとレート制限が適用されます。
**非同期トランザクションクォータ**
| クォータ | 値 | 引き上げ可能 |
| --- | --- | --- |
| 非同期トランザクションあたりの最大オペレーション数 | 500 | いいえ |
| データストアあたりの保留中の最大トランザクション数 | 500 | はい |
+ 非同期トランザクションは、 で定義されているのと同じ API レート制限を共有します[Service Quotas](reference-healthlake-endpoints-quotas.md#reference-healthlake-quotas)。
+ トランザクションステータスのポーリングは、FHIR リソースの読み取り (`GET`) オペレーションと同じ API レート制限を共有します。
+ 保留中のトランザクション制限に達すると、後続の送信は既存のトランザクションが完了するまでエラーを返します。
### エラー処理
「トランザクション」バンドルの場合、バンドルに含まれるすべての FHIR リソースはアトミックオペレーションとして処理されます。オペレーションのすべてのリソースは成功する必要があります。成功しない場合、バンドル内のオペレーションは処理されません。
エラーは、HealthLake が同期的に返す送信エラーと、ポーリングによって取得する処理エラーの 2 つのカテゴリに分類されます。
**送信エラー**
HealthLake は送信時にバンドルを検証し、トランザクションがキューに入る前にエラーを同期的に返します。送信エラーには、無効な FHIR リソース検証エラー、サポートされていないリソースタイプ、500 オペレーション制限の超過、バッチバンドルでの `Prefer: respond-async`ヘッダーの使用が含まれます。データストアの保留中のトランザクション制限に達した場合、HealthLake は を返します`ThrottlingException`。送信エラーが発生すると、トランザクションはキューに入れられません。
**処理エラー**
処理エラーは、トランザクションがキューに入れられ、ポーリング URL を介して返された後に発生します。これには、トランザクションの一部であるリソースを別のオペレーションで変更したトランザクションの競合や、処理中のサーバーエラーが含まれます。処理エラーが発生した場合、トランザクション内のリソースに対してリソースミューテーションは行われません。ポーリング URL は、エラーの詳細`OperationOutcome`を含む を返します。