このページでは、FHIR リソースのコレクションである FHIR バンドルと、HIR リソースに対して行うオペレーションを実行して、FHIR リソースを管理する方法について説明します。
ExecuteBundle
メソッドは、FHIR の標準バッチ/トランザクション インタラクション(DSTU2、STU3、R4)と履歴オペレーションを実装します。
FHIR バンドル
FHIR バンドルにはエントリの配列が含まれ、それぞれが Observation や Patient などのリソースに対するオペレーション(作成、更新、削除など)を表します。詳しくは、バンドル リソースの要素についての詳細な説明をご覧ください。
FHIR バンドルの実行時に、バンドルタイプによってバンドルでのオペレーションの実行方法が決定されます。使用できるバンドルのタイプは次のとおりです。
batch
: 複数の独立したリクエストとしてオペレーションが実行されます。transaction
: 相互に依存する複数のリクエストとしてオペレーションが実行されます。history
: リソースの履歴にエントリを挿入します。
たとえば、トランザクション バンドルに Patient リソースと Observation リソースの作成が含まれているとします。Patient リソースの作成リクエストが失敗した場合、Observation リソースは作成されません。
バンドルタイプが batch
のときにオペレーションが失敗した場合、Cloud Healthcare API でバンドル内の残りのオペレーションが実行されます。バンドルタイプが transaction
のときにオペレーションが失敗した場合、Cloud Healthcare API でオペレーションの実行が停止され、トランザクションがロールバックされます。
履歴バンドル
履歴バンドルは FHIR 標準のカスタム拡張機能で、同期などのバックアップと復元のユースケースに対応しています。履歴バンドルを使用すると、FHIR リソースの履歴に対してリソース バージョンの挿入または置き換えを行うことができます。リソース バージョンを削除できるのは、Resource-purge
メソッドを使用する場合のみです。history
バンドルは単一のトランザクションとして実行されます。バンドルごとのエントリ数の上限は 100 個です。history
バンドルのリソース バージョンのタイムスタンプが FHIR ストアの最新バージョンよりも大きい場合、それに応じて最新バージョンが更新されます。history
バンドルが正常に挿入されると、空のレスポンスが返されます。それ以外の場合は、失敗を示す OperationOutcome
が返されます。
履歴バンドルのサポートはデフォルトでは有効になっていません。FHIR ストア管理者は、FHIR ストア構成で enableHistoryModifications
を true
に設定する必要があります。FHIR ストアの構成で disableResourceVersioning
が true
に設定されている場合、履歴バンドルを使用できません。
履歴バンドルは、fhir.history
メソッドから返される際の形式と同じ形式で提供されます。各バンドル エントリが有効であるためには、リソース ID、変更タイムスタンプ、ステータスが必要です。また、すべてのエントリに同じリソース ID を指定する必要があります。リソース ID は、resource.id
フィールドまたは request.url
フィールドで指定します。フィールドが指定されている場合、指定されたリソース ID は同じになります。リソースのタイムスタンプは、リソースの meta.lastUpdated
フィールドまたは response.lastModified
フィールドで指定します。
バンドルを実行するための権限の付与
バンドルを実行するには、datasets.fhirStores.fhir.executeBundle
権限のロールが必要です。この権限を付与するには、healthcare.fhirResourceReader
ロールを使用します。この権限を付与するための手順については、ポリシーの変更をご覧ください。
履歴バンドルを実行するには、datasets.fhirStores.fhir.import
権限のロールも必要です。
Cloud Healthcare API では、バンドル内の各オペレーションの権限を確認します。healthcare.fhirResources.create
権限は持っているものの、healthcare.fhirResources.update
権限は持っていない場合、healthcare.fhirResources.create
オペレーションが含まれるバンドルのみを実行できます。
バンドルを実行する
FHIR バンドルを実行するには、projects.locations.datasets.fhirStores.fhir.executeBundle
メソッドを使用します。
以下のサンプルでは、BUNDLE.json は JSON でエンコードされた FHIR バンドルへのパスとファイル名です。また、リクエストの本文にバンドルを含めることもできます。
次のサンプル バンドルは、患者リソースの作成と別の患者リソースの削除を行います。
{
"resourceType": "Bundle",
"id": "bundle-transaction",
"meta": {
"lastUpdated": "2018-03-11T11:22:16Z"
},
"type": "transaction",
"entry": [
{
"resource": {
"resourceType": "Patient",
"name": [
{
"family": "Smith",
"given": [
"Darcy"
]
}
],
"gender": "female",
"address": [
{
"line": [
"123 Main St."
],
"city": "Anycity",
"state": "CA",
"postalCode": "12345"
}
]
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"request": {
"method": "DELETE",
"url": "Patient/1234567890"
}
}
]
}
次のサンプルは、バンドルを実行する方法を示しています。
curl
バンドルを実行するには、POST
リクエストを行い、次の情報を指定します。
- 親データセットと FHIR ストアの名前とロケーション
- ローカルマシン上のバンドル ファイルの場所
- アクセス トークン
次のサンプルは、curl を使用した POST
リクエストを示しています。
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data @BUNDLE_FILE.json \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"
個々のオペレーションの結果に関係なく、バッチバンドルの実行後に、サーバーは batch-response
タイプの Bundle
リソースの JSON エンコード表現を返します。Bundle
リソースには、リクエストのエントリごとに 1 つのエントリが含まれます。エントリの処理により、結果は成功かエラーになります。
トランザクション バンドルが成功した場合、サーバーはオペレーションが成功したリクエスト中の各エントリごとに 1 つのエントリを含む、transaction-response
タイプの Bundle
リソースの JSON エンコード表現を返します。
トランザクション バンドルの実行中にエラーが発生した場合、レスポンスの本文にバンドルは含まれません。代わりに、エラーの理由を説明する JSON エンコードされた OperationOutcome
リソースが含まれます。ロールバックされた正常なオペレーションは、レスポンスでは報告されません。
次のサンプル バンドルは、上記の例を正常に実行した際の出力です。最初のエントリは、Patient を作成するオペレーションの成功を示していて、新しいリソースの ID が含まれています。2 番目のエントリは、削除オペレーションが成功したことを示しています。
{ "entry": [ { "response": { "location": projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE/RESOURCE_ID, "status": "201 Created" } }, { "response": { "status": "200 OK" } } ], "resourceType": "Bundle", "type": "transaction-response" }
PowerShell
バンドルを実行するには、POST
リクエストを行い、次の情報を指定します。
- 親データセットと FHIR ストアの名前とロケーション
- ローカルマシン上のバンドル ファイルの場所
- アクセス トークン
次のサンプルは、Windows PowerShell を使用した POST
リクエストを示しています。
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json" ` -InFile BUNDLE_FILE.json ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir" | ConvertTo-Json
個々のオペレーションの結果に関係なく、バッチバンドルの実行後に、サーバーは batch-response
タイプの Bundle
リソースの JSON エンコード表現を返します。Bundle
リソースには、リクエストのエントリごとに 1 つのエントリが含まれます。エントリの処理により、結果は成功かエラーになります。
トランザクション バンドルが成功した場合、サーバーはオペレーションが成功したリクエスト中の各エントリごとに 1 つのエントリを含む、transaction-response
タイプの Bundle
リソースの JSON エンコード表現を返します。
トランザクション バンドルの実行中にエラーが発生した場合、レスポンスの本文にバンドルは含まれません。代わりに、エラーの理由を説明する JSON エンコードされた OperationOutcome
リソースが含まれます。ロールバックされた正常なオペレーションは、レスポンスでは報告されません。
次のサンプル バンドルは、上記の例を正常に実行した際の出力です。最初のエントリは、Patient を作成するオペレーションの成功を示していて、新しいリソースの ID が含まれています。2 番目のエントリは、削除オペレーションが成功したことを示しています。
{ "entry": [ { "response": { "etag": "ETAG", "lastModified": "2020-08-03T04:12:47.312669+00:00", "location": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE/RESOURCE_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-03T04:12:47.312669+00:00", "status": "200 OK" } } ], "resourceType": "Bundle", "type": "transaction-response" }
Go
Java
Node.js
サンプル バンドル ファイルは、コードサンプルの GitHub リポジトリで入手できます。
Python
サンプル バンドル ファイルは、コードサンプルの GitHub リポジトリで入手できます。
PATCH
リクエストを作成する
FHIR バンドルを使用して、FHIR リソースに対して JSON PATCH
リクエストを実行できます。詳細については、FHIR バンドルでの PATCH
リクエストの実行をご覧ください。
バンドル内に作成されたリソースへの参照の解決
トランザクション バンドルのリソースには、ターゲット システム内に存在しないものの、バンドルの実行中に作成されたリソースへの参照を含めることができます。Cloud Healthcare API は、entry.fullUrl
フィールドを使用してリソース間の関連付けを解決します。バンドル内にある別のリソースの entry.fullUrl
値に一致する参照は、ストア内の対応するリソースの ID に書き換えられます。これは、バンドル内のオペレーションの順序に関係なく成功します。
Cloud Healthcare API は、次の形式の fullUrl
を受け入れます。
urn:uuid:UUID
urn:oid:OID
- 任意の URL
RESOURCE_TYPE/RESOURCE_ID
形式のリソース名(例:Patient/123
)。fullUrl
はバンドルのローカル プレースホルダであるため、この形式の使用はおすすめしません。ストア内のリソースの名前が同じであっても、バンドル内のリソースが作成オペレーションの結果として別の名前に解決された場合、混乱を招く可能性があります。
次のサンプル バンドルでは、Patient リソースを参照する Patient リソースと Observation リソースを作成します。
{
"resourceType": "Bundle",
"type": "transaction",
"entry":[
{
"request": {
"method":"POST",
"url":"Patient"
},
"fullUrl": "urn:uuid:05efabf0-4be2-4561-91ce-51548425acb9",
"resource": {
"resourceType":"Patient",
"gender":"male"
}
},
{
"request": {
"method":"POST",
"url":"Observation"
},
"resource": {
"resourceType":"Observation",
"subject": {
"reference": "urn:uuid:05efabf0-4be2-4561-91ce-51548425acb9"
},
"status":"preliminary",
"code": {
"text":"heart rate"
}
}
}
]
}
次のサンプルは、バンドルを実行する方法を示しています。
curl
サンプル バンドル ファイルは、コードサンプルの GitHub リポジトリで入手できます。
バンドルを実行するには、POST リクエストを行い、次の情報を指定します。
- 親データセットと FHIR ストアの名前とロケーション
- Cloud Storage 内のバンドル ファイルのロケーション
- アクセス トークン
次のサンプルは、curl を使用した POST
リクエストを示しています。
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data @BUNDLE_FILE.json \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"
次のサンプル バンドルは、上記の例を正常に実行した際の出力です。最初のエントリは、Patient を作成するオペレーションの成功を示していて、新しいリソースの ID が含まれています。2 番目のエントリは、Observation を作成するオペレーションの成功を示していて、新しいリソースの ID が含まれています。
{ "entry": [ { "response": { "etag": "ETAG1", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID/_history/HISTORY_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Observation/OBSERVATION_ID/_history/HISTORY_ID", "status": "201 Created" } } ], "resourceType": "Bundle", "type": "transaction-response" }
PowerShell
サンプル バンドル ファイルは、コードサンプルの GitHub リポジトリで入手できます。
バンドルを実行するには、POST リクエストを行い、次の情報を指定します。
- 親データセットと FHIR ストアの名前とロケーション
- Cloud Storage 内のバンドル ファイルのロケーション
- アクセス トークン
次のサンプルは、Windows PowerShell を使用した POST
リクエストを示しています。
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json" ` -InFile BUNDLE_FILE.json ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir" | ConvertTo-Json
次のサンプル バンドルは、上記の例を正常に実行した際の出力です。最初のエントリは、Patient を作成するオペレーションの成功を示していて、新しいリソースの ID が含まれています。2 番目のエントリは、Observation を作成するオペレーションの成功を示していて、新しいリソースの ID が含まれています。
{ "entry": [ { "response": { "etag": "ETAG1", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID/_history/HISTORY_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Observation/OBSERVATION_ID/_history/HISTORY_ID", "status": "201 Created" } } ], "resourceType": "Bundle", "type": "transaction-response" }