在 Azure API for FHIR 中匯出 FHIR 數據
重要
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 和醫療技術服務。
「大量匯出」功能允許根據 FHIR 規格從 FHIR® 伺服器匯出數據。
使用 $export
之前,請確定 Azure API for FHIR 已設定為使用它。 如需設定匯出設定和建立 Azure 記憶體帳戶,請參閱設定 匯出數據頁面。
注意
只有與 Azure API for FHIR 相同訂用帳戶中的記憶體帳戶,才能註冊為$export作業的目的地。
使用 $export 命令
設定 Azure API for FHIR 進行匯出之後,您可以使用 $export
命令將數據匯出出服務。 數據會儲存在您設定匯出時指定的記憶體帳戶中。 若要瞭解如何在 FHIR 伺服器中叫$export
用命令,請閱讀 HL7 FHIR $export規格中的檔。
作業停滯在不良狀態
在某些情況下,工作可能會卡在不良狀態中。 如果記憶體帳戶許可權尚未正確設定,就會發生這種情況。 驗證導出的其中一種方法是檢查記憶體帳戶,以查看對應的容器(也就是 ndjson
) 檔案是否存在。 如果它們不存在,而且沒有其他執行中的導出作業,則目前的作業可能會停滯在不良狀態。 您應該傳送取消要求來取消匯出作業,然後再次嘗試重新排入佇列。 導出的預設運行時間處於不良狀態為10分鐘,才會停止並移至新作業,或重試匯出。
Azure API For FHIR 支援 $export
下列層級:
- 系統:
GET https://<<FHIR service base URL>>/$export>>
- 病患:
GET https://<<FHIR service base URL>>/Patient/$export>>
- 病患群組* - Azure API for FHIR 會匯出所有相關資源,但不會匯出群組的特性:
GET https://<<FHIR service base URL>>/Group/[ID]/$export>>
數據會匯出在多個檔案中,每個檔案只包含一種類型的資源。 個別檔案中的資源數目將會受到限制。 資源數目上限是以系統效能為基礎。 它目前設定為 5,000,但可以變更。 結果是您可能會取得資源類型的多個檔案。 檔名會遵循 'resourceName-number-number.ndjson' 格式。 不保證檔案的順序會對應至資料庫中資源的任何順序。
注意
Patient/$export
如果資源位於多個資源的區間中,或位於多個群組中,則和 Group/[ID]/$export
可能會匯出重複的資源。
此外,支援透過位置標頭在佇列期間傳回的 URL 檢查導出狀態,以及取消實際的導出作業。
將 FHIR 數據匯出至 ADLS Gen2
目前我們支援 $export
已啟用ADLS Gen2的記憶體帳戶,但有下列限制:
- 用戶無法利用 階層命名空間 - 沒有方法可將導出目標設為容器內的特定子目錄。 我們只提供以特定容器為目標的能力(其中會針對每個匯出建立新資料夾)。
- 匯出完成後,再也沒有匯出到該資料夾。 後續匯出至相同的容器將會位於新建立的資料夾內。
設定和參數
標題
必須為 $export
作業設定兩個必要的標頭參數。 這些值是由目前的 $export規格所定義。
- Accept - application/fhir+json
- 偏好 - respond-async
查詢參數
Azure API for FHIR 支援下列查詢參數。 所有這些參數都是選擇性的。
查詢參數 | 由 FHIR 規格定義? | 描述 |
---|---|---|
_outputFormat | Yes | 目前支援三個值來對齊 FHIR 規格:application/fhir+ndjson、application/ndjson 或 ndjson。 所有導出作業都會傳回 ndjson ,且傳遞的值不會影響程式代碼行為。 |
_since | Yes | 可讓您只匯出自提供的時間以來已修改的資源。 |
_type | Yes | 可讓您指定將包含哪些類型的資源。 例如,_type=Patient 只會傳回病患資源。 |
_typefilter | Yes | 若要要求更精細的篩選,您可以使用 _typefilter 和 _type 參數。 _typeFilter參數的值是以逗號分隔的 FHIR 查詢清單,進一步限制結果。 |
_容器 | No | 指定設定的記憶體帳戶內應匯出數據的容器。 如果指定了容器,數據就會匯出至該容器中的資料夾。 如果未指定容器,數據就會匯出至新的容器。 |
_直到 | No | 只允許您匯出已修改到所提供時間的資源。 此參數僅適用於系統層級匯出。 在此情況下,如果歷程記錄版本尚未停用或清除,匯出會保證真正的快照集檢視。 換句話說,啟用時間移動。 |
includeAssociatedData | No | 可讓您匯出歷程記錄和虛刪除的資源。 此篩選不適用於 『_typeFilter』 查詢參數。 將值納入為 「_history」,以導出歷程記錄(非最新版本的資源)。 將值包含為 『_deleted』,以匯出虛刪除的資源。 |
_isparallel | No | 您可以將 「_isparallel」 查詢參數新增至匯出作業,以增強其輸送量。 值必須設定為 true,才能啟用平行處理。 注意:使用此參數可能會導致要求單位耗用量在導出生命週期內增加。 |
注意
作業有一個已知問題 $export
,可能會導致狀態成功的匯出不完整。 使用is_parallel旗標時,就會發生此問題。 從 2024 年 2 月 13 日起,使用 _isparallel 查詢參數執行的導出作業會受到此問題的影響。
保護導出至 Azure 儲存體
Azure API for FHIR 支援安全的導出作業。 選擇下列兩個選項之一。
允許 Azure API for FHIR 作為Microsoft信任的服務存取 Azure 記憶體帳戶。
允許與 Azure API for FHIR 相關聯的特定 IP 位址存取 Azure 記憶體帳戶。 此選項提供兩個不同的組態,視記憶體帳戶位於與 Azure API for FHIR 位於相同或不同的位置而定。
允許 Azure API for FHIR 作為Microsoft信任的服務
從 Azure 入口網站 選取記憶體帳戶,然後選取 [網络] 刀鋒視窗。 選取 [防火牆和虛擬網络] 索引標籤底下的 [選取的網络]。
重要
請確定您已使用其受控識別,將 Azure API for FHIR 的記憶體帳戶訪問許可權授與。 如需詳細資訊,請參閱 設定導出設定和設定記憶體帳戶。
在 [例外狀況] 區段底下,選取 [允許信任 Microsoft 服務 存取此儲存器帳戶並儲存設定的方塊。
您現在可以安全地將 FHIR 數據匯出至記憶體帳戶。 注意:記憶體帳戶位於選取的網路上,且無法公開存取。 若要存取檔案,您可以啟用並使用記憶體帳戶的私人端點,或為記憶體帳戶啟用短期內的所有網路。
重要
稍後會更新使用者介面,讓您選取 Azure API for FHIR 和特定服務實例的資源類型。
允許特定IP位址從其他 Azure 區域存取 Azure 記憶體帳戶
在 Azure 入口網站 中,移至 Azure Data Lake Storage Gen2 帳戶。
在左側功能表上,選取 [網路]。
選取 [從選取的虛擬網路和 IP 位址啟用]。
在 [防火牆] 區段中的 [位址範圍] 方塊中,指定IP位址。 新增 IP 範圍以允許來自網際網路或內部部署網路的存取。 您可以在下表中找到已布建 FHIR 服務之 Azure 區域的 IP 位址。
Azure 區域 公用 IP 位址 澳大利亞東部 20.53.44.80 加拿大中部 20.48.192.84 美國中部 52.182.208.31 美國東部 20.62.128.148 美國東部 2 20.49.102.228 美國東部 2 EUAP 20.39.26.254 德國北部 51.116.51.33 德國中西部 51.116.146.216 日本東部 20.191.160.26 南韓中部 20.41.69.51 美國中北部 20.49.114.188 北歐 52.146.131.52 南非北部 102.133.220.197 美國中南部 13.73.254.220 東南亞 23.98.108.42 瑞士北部 51.107.60.95 英國南部 51.104.30.170 英國西部 51.137.164.94 美國中西部 52.150.156.44 西歐 20.61.98.66 美國西部 2 40.64.135.77
允許特定IP位址存取相同區域中的 Azure 記憶體帳戶
相同區域中IP位址的設定程式與上一個程式相同,不同之處在於您改用無類別網域間路由 (CIDR) 格式的特定IP位址範圍(也就是100.64.0.0/10)。 您必須指定IP位址範圍 (100.64.0.0.0至100.127.255.255),因為每次發出作業要求時都會配置 FHIR 服務的IP位址。
注意
在 10.0.2.0/24 的範圍內可以使用私人 IP 位址,但無法保證作業會在這類情況下成功。 如果作業要求失敗,您可以重試,但直到您在 100.64.0.0/10 的範圍內使用 IP 位址,要求才會成功。
IP 位址範圍的這個網路行為是設計好的。 替代方法是設定不同區域中的儲存體帳戶。
下一步
在本文中,您已瞭解如何使用 $export
命令導出 FHIR 資源。 接下來,若要瞭解如何匯出已取消識別的數據,請參閱
注意
FHIR® 是 HL7 的註冊商標,在 HL7 的許可下使用。