Azure API for FHIR の FHIR REST API 機能

[アーティクル]
06/01/2023

この記事では、Azure API for FHIR の RESTful 相互作用の微妙な違いについて説明します。

条件付き作成/更新

Azure API for FHIR では、FHIR 仕様で定義されているように、作成、条件付き作成、更新、条件付き更新がサポートされます。これらのシナリオで役に立つヘッダーの 1 つは、If-Match ヘッダーです。 If-Matchヘッダーが使用され、更新前に更新されるバージョンが検証されます。が ETag 予期した ETagと一致しない場合は、エラーメッセージ 412 Precondition Failed が生成されます。

削除と条件付き削除

Azure API for FHIR には、2 つの削除の種類が用意されています。 [ 削除] があります。これは、"ハード + 論理的な削除" と "条件付き削除" とも認識されます。

削除 (ハード + 論理的な削除)

FHIR 仕様で定義された削除では、リソースを削除した後、それ以降のバージョン以外のリソース固有の読み取りでは、410 HTTP 状態コードが返される必要があります。そのため、リソースは検索によって見つかりません。さらに、Azure API for FHIR を使用すると、リソースを完全に削除できます (すべての履歴を含む)。リソースを完全に削除するには、パラメーター設定 hardDelete を true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true)に渡します。このパラメーターを渡さない場合、または false に設定 hardDelete した場合でも、リソースの履歴バージョンは引き続き使用できます。

注意

履歴のみを削除する場合、Azure API for FHIR ではという $purge-historyカスタム操作がサポートされます。この操作を使用すると、リソースの履歴を削除できます。

条件付き削除

条件付き削除を使用すると、検索条件を渡してリソースを削除できます。既定では、条件付き削除では、一度に 1 つのアイテムを削除できます。パラメーターを _count 指定して、一度に最大 100 個のアイテムを削除することもできます。条件付き削除の使用例を次に示します。

条件付き削除を使用して 1 つのアイテムを削除するには、1 つのアイテムを返す検索条件を指定する必要があります。

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704

同じ検索を行うことができますが、を含めて hardDelete=true すべての履歴も削除できます。

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true

複数のリソースを削除するには、パラメーターを含めます _count=100 。このパラメーターは、検索条件に一致する最大 100 個のリソースを削除します。

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100

削除されたファイルの回復

hard delete パラメーターを使用しない場合は、Azure API for FHIR のレコードがまだ存在している必要があります。レコードは、リソースの履歴検索を実行し、データを含む最後のバージョンを検索することで見つけることができます。

削除されたリソースの ID がわかっている場合は、次の URL パターンを使用します。

<FHIR_URL>/<resource-type>/<resource-id>/_history

例: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history

リソースの ID が不明な場合は、リソースの種類全体で履歴検索を行います。

<FHIR_URL>/<resource-type>/_history

例: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history

復元するレコードが見つかったら、操作を PUT 使用して同じ ID でリソースを再作成するか、操作を POST 使用して同じ情報を持つ新しいリソースを作成します。

注意

履歴/論理的な削除データの時間ベースの有効期限はありません。履歴または論理的に削除されたデータを削除する唯一の方法は、ハード削除または消去履歴操作を使用することです。

パッチと条件付きパッチ

パッチは、FHIR リソースの一部のみを更新する必要がある場合に、重要な RESTful 操作です。 patch を使用すると、レコード全体を更新することなく、リソースで更新する要素を指定できます。 FHIR では、リソースにパッチを適用する 3 つの方法 (JSON パッチ、XML パッチ、FHIRPath パッチ) が定義されています。 FHIR サービスでは、JSON パッチと FHIRPath パッチの両方と、条件付き JSON パッチと条件付き FHIRPath パッチ (リソース ID ではなく検索条件に基づいてリソースにパッチを適用できます) がサポートされています。いくつかの例を確認するには、各アプローチのサンプル FHIRPath Patch REST ファイルと JSON Patch REST ファイルを参照してください。詳細については、FHIR を使用したパッチ操作に関する HL7 ドキュメントを参照してください。

注意

STU3 に対してを使用 PATCH し、履歴バンドルを要求する場合、修正プログラムが適用されたリソース Bundle.entry.request.method はに PUTマップされます。これは、STU3 に HTTPVerb 値セット内のPATCH動詞の定義が含まれていないためです。

FHIRPath パッチを使用したパッチ

このパッチの方法は、ターゲットとなる要素を選択するために FHIRPath を利用するため、最も強力です。一般的なシナリオの 1 つは、FHIRPath Patch を使用して、リストの順序を知らずにリスト内の要素を更新することです。たとえば、インデックスを知らずに患者の自宅通信情報を削除する場合は、次の例を使用できます。

PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
コンテンツタイプ: application/fhir+json

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "operation",
            "part": [
                {
                    "name": "type",
                    "valueCode": "delete"
                },
                {
                    "name": "path",
                    "valueString": "Patient.telecom.where(use = 'home')"
                }
            ]
        }
    ]
}

FHIRPath Patch の操作には、Content-Type ヘッダーが設定されている application/fhir+json 必要があります。 FHIRPatch Patch では、追加、挿入、削除、削除、移動の各操作がサポートされます。 FHIRPatch Patch 操作は、バンドルに簡単に統合することもできます。その他の例については、サンプルの FHIRPath Patch REST ファイルを参照してください。

JSON パッチを使用したパッチ

FHIR サービスの JSON パッチは、インターネットエンジニアリングタスクフォースによって定義されているよく使用される仕様に準拠しています。ペイロード形式では FHIR リソースは使用されず、代わりに要素の選択にJSON-Pointersを利用する JSON ドキュメントが使用されます。 JSON Patch はよりコンパクトで、パッチを実行する前に条件が true であることを検証できるテスト操作を備えています。たとえば、まだ死亡者としてマークされていない場合にのみ、患者を死亡者として設定する場合は、次の例を使用できます。

PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
コンテンツタイプ: application/json-patch+json

[
	{
		"op": "test",
		"path": "/deceasedBoolean",
		"value": false
	},
	{
		"op": "replace",
		"path": "/deceasedBoolean",
		"value": true
	}
]

JSON パッチ操作には、Content-Type ヘッダーが設定されている application/json-patch+json 必要があります。 JSON Patch では、追加、削除、置換、コピー、移動、テストの各操作がサポートされています。その他の例については、サンプルの JSON Patch REST ファイルを参照してください。

バンドル内の JSON パッチ

既定では、JSON パッチはバンドルリソースではサポートされていません。これは、バンドルは FHIR リソースでのみサポートされ、JSON Patch ペイロードは FHIR リソースではないためです。これを回避するには、Content-Type がの "application/json-patch+json" バイナリリソースと、バンドル内の JSON ペイロードの base64 エンコードを使用します。この回避策の詳細については、 FHIR Chat Zulip に関するこのトピックを参照してください。

次の例では、患者の性別を女性に変更します。 JSON パッチ [{"op":"replace","path":"/gender","value":"female"}] を取得し、base64 にエンコードしました。

POST https://{FHIR-SERVICE-HOST-NAME}/
Content-Type: application/json

{
	"resourceType": "Bundle",
	"id": "bundle-batch",
	"type": "batch",
	"entry": [
		{
			"fullUrl": "Patient/{PatientID}",
			"resource": {
				"resourceType": "Binary",
				"contentType": "application/json-patch+json",
				"data": "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ=="
			},
			"request": { 
				"method": "PATCH",
				"url": "Patient/{PatientID}"
			}
		}
	]
}

次のステップ

この記事では、Azure API for FHIR の REST 機能の一部について説明しました。次に、FHIR でリソースを検索する際の主な側面について学習できます。

Azure API for FHIR での検索の概要

(FHIR®) は HL7 の登録商標であり、HL7 の権限を得て使用しています。