適用於 Azure API for FHIR 的 FHIR REST API 功能

發行項
05/12/2024

重要

Azure API for FHIR 將於 2026 年 9 月 30 日淘汰。 遵循移轉策略，在該日期前轉換至 Azure 健康資料服務 FHIR 服務。由於 Azure API for FHIR 已淘汰，因此從 2025 年 4 月 1 日開始，將不允許新的部署。 Azure 健康資料服務 FHIR 服務是已演進的 Azure API for FHIR 版本，可讓客戶透過與其他 Azure 服務整合來管理 FHIR、DICOM 和醫療技術服務。

在本文中，我們將討論 Azure API for FHIR 的 RESTful 互動方面一些細微的差別。

條件式建立/更新

Azure API for FHIR 支援建立、條件式建立、更新和條件式更新，如 FHIR 規格所定義。在這些案例中，有一個有用的標頭是 If-Match 標頭。會使用 If-Match 標頭，並會在進行更新之前，驗證要更新的版本。如果 ETag 不符合預期的 ETag，則其會產生錯誤訊息 412 前置條件失敗。

刪除和條件式刪除

Azure API for FHIR 提供兩種刪除類型。有刪除，也稱為硬式 + 虛刪除，以及條件式刪除。

您可以針對個別資源識別碼或大量執行刪除。若要深入了解如何大量刪除資源，請瀏覽 $bulk-delete 作業。

刪除 (硬式 + 虛移除)

FHIR 規格所定義的刪除需要刪除資源之後，後續非版本特定的資源讀取會傳回 410 HTTP 狀態碼。因此，無法再透過搜尋找到資源。此外，Azure API for FHIR 可讓您完全刪除資源 (包括所有歷程記錄)。若要完全刪除資源，您可以將參數設定 hardDelete 傳遞至 true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true)。如果您未傳遞此參數或將 hardDelete 設定為 false，則仍可使用資源的歷程記錄版本。

注意

如果您只想要刪除歷程記錄，Azure API for FHIR 支援稱為 $purge-history 的自訂作業。這項作業可讓您刪除資源的歷程記錄。

條件式刪除

條件式刪除可讓您傳遞搜尋準則來刪除資源。根據預設，條件式刪除可讓您一次刪除一個項目。您也可以指定 _count 參數，一次刪除最多 100 個項目。以下是使用條件式刪除的一些範例。

若要使用條件式刪除來刪除單一項目，您必須指定傳回單一項目的搜尋準則。

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

復原已刪除的檔案

如果您未使用硬式刪除參數，則 Azure API for FHIR 中的記錄應該仍存在。您可以在資源上執行歷程記錄搜尋，並尋找含有資料的最後一個版本，從而找到記錄。

如果已知已刪除的資源識別碼，請使用下列 URL 模式：

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

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

如果不知道資源的識別碼，請在整個資源類型上執行歷程記錄搜尋：

<FHIR_URL>/<resource-type>/_history

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

找到您要還原的記錄之後，請使用 PUT 作業，以相同的識別碼重新建立資源，或使用 POST 作業來建立具有相同資訊的新資源。

注意

歷程記錄/虛刪除資料沒有以時間為基礎的到期日。移除歷程記錄/虛刪除資料的唯一方法是使用硬式刪除或清除記錄作業。

修補檔和條件式修補檔

當您只需要更新部分 FHIR 資源時，修補檔是一項寶貴的 RESTful 作業。使用修補檔可讓您指定您要在資源中更新的元素，而不必更新整個記錄。 FHIR 定義三種方式來修補資源：JSON Patch、XML Patch 和 FHIRPath Patch。 FHIR 服務同時支援 JSON Patch 和 FHIRPath Patch，以及條件式 JSON Patch 和條件式 FHIRPath Patch (可讓您根據搜尋準則而非資源識別碼來修補資源)。若要逐步解說一些範例，請參閱範例 FHIRPath Patch REST 檔案，以及每個方法的 JSON Patch REST 檔案。如需其他詳細資料，請參閱使用 FHIR 進行修補作業的 HL7 文件。

注意

針對 STU3 使用 PATCH 時，如果您要求歷程記錄套件組合，則修補的資源 Bundle.entry.request.method 會對應至 PUT。這是因為 STU3 不包含 HTTPVerb 值集中 PATCH 動詞的定義。

使用 FHIRPath Patch 進行修補

這個修補是最強大的方法，因為其會運用 FHIRPath 來選取要設為目標的元素。其中一個常見案例是在不知道清單順序的情況下，使用 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 作業都必須有 application/fhir+json 內容-類型標頭集。 FHIRPatch Patch 支援新增、插入、刪除、移除和移動作業。 FHIRPatch Patch 作業也可以輕鬆地整合到套件組合中。如需更多範例，請參閱範例 FHIRPath Patch REST 檔案。

使用 JSON Patch 進行修補

FHIR 服務中的 JSON Patch 符合網際網路工程工作組所定義的妥善使用規格。承載格式不會使用 FHIR 資源，而是使用運用 JSON 指標進行元素選取的 JSON 文件。 JSON Patch 比較精簡，且具有測試作業，可讓您先驗證條件是否成立後，再執行修補。例如，如果您想要將患者設定為已故，但前提是尚未將患者標示為已故，則可以使用下列範例。

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 Patch 作業都必須有 application/json-patch+json 內容-類型標頭集。 JSON Patch 支援新增、移除、取代、複製、移動和測試作業。如需更多範例，請參閱範例 JSON Patch REST 檔案。

套件組合中的 JSON Patch

根據預設，套件組合資源不支援 JSON Patch。這是因為套件組合僅支援 FHIR 資源，而 JSON Patch 承載並非 FHIR 資源。為了解決這個問題，我們將使用二進位資源搭配 "application/json-patch+json" 的內容-類型以及套件組合內 JSON 承載的 base64 編碼。如需此因應措施的相關資訊，請檢視本主題中的 FHIR Chat Zulip。

在下列範例中，我們要將患者的性別變更為女性。我們已取得 JSON 修補檔 [{"op":"replace","path":"/gender","value":"female"}]，並將其編碼為 base64。

POST https://{FHIR-SERVICE-HOST-NAME}/
內容-類型：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}"
			}
		}
	]
}

條件式作業的效能考量

條件式互動可能相當複雜且需要大量效能。若要增強涉及條件式互動的查詢延遲，您可以選擇使用要求標頭 x-conditionalquery-processing-logic。將此標頭設定為平行會允許使用條件式互動同時執行查詢。

下一步

在本文中，您已了解 Azure API for FHIR 的一些 REST 功能。接下來，您可以深入了解在 FHIR 中搜尋資源的重要層面。

Azure API for FHIR 中的搜尋概觀

(FHIR®) 是 HL7 的註冊商標，可與 HL7 的權限搭配使用。

共用方式為