在 Azure API for FHIR 中匯出 FHIR 數據

  • 發行項

重要

Azure API for FHIR 將於 2026 年 9 月 30 日淘汰。 請遵循移轉策略，依該日期轉換至 Azure Health Data Services FHIR 服務。 由於 Azure API for FHIR 已淘汰，因此從 2025 年 4 月 1 日開始，將不允許新的部署。 Azure Health Data Services FHIR 服務 是已演進的 Azure API for FHIR 版本，可讓客戶管理 FHIR、DICOM 和 MedTech 服務，並整合至其他 Azure 服務。

大量匯出功能可讓您根據 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

目前我們支援已啟用 ADLS Gen2 的記憶體帳戶$export，但有下列限制：

  • 用戶無法利用 階層命名空間，但無法將導出目標設為容器內的特定子目錄。 我們只提供以特定容器為目標的能力（我們會為每個匯出建立新的資料夾）。
  • 匯出完成後，我們永遠不會再將任何項目匯出至該資料夾，因為後續匯出至相同的容器將會位於新建立的資料夾內。

設定和參數

標題

必須針對$export作業設定兩個必要的標頭參數。 這些值是由目前的 $export規格所定義。

  • Accept - application/fhir+json
  • 偏好 - respond-async

查詢參數

Azure API for FHIR 支援下列查詢參數。 所有這些參數都是選擇性的：

查詢參數 由 FHIR 規格定義？ 描述
_outputFormat Yes 目前支援三個值來對齊 FHIR 規格：application/fhir+ndjson、application/ndjson 或 ndjson。 所有導出作業都會傳回 ndjson ，且傳遞的值不會影響程式代碼行為。
_因為 Yes 可讓您只匯出自提供的時間以來已修改的資源
_類型 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 的記憶體帳戶訪問許可權授與。 如需詳細資訊，請參閱 設定導出設定和設定記憶體帳戶。

Azure Storage Networking Settings.

在 [例外狀況] 區段底下，選取 [允許信任 Microsoft 服務 存取此儲存器帳戶並儲存設定的方塊。

Allow trusted Microsoft services to access this storage account.

您現在可以安全地將 FHIR 數據匯出至記憶體帳戶。 請注意，記憶體帳戶位於選取的網路上，且無法公開存取。 若要存取檔案，您可以啟用並使用記憶體帳戶的私人端點，或為記憶體帳戶啟用短期內的所有網路。

重要

稍後會更新使用者介面，讓您選取 Azure API for FHIR 和特定服務實例的資源類型。

允許特定IP位址從其他 Azure 區域存取 Azure 記憶體帳戶

  1. 在 Azure 入口網站 中，移至 Azure Data Lake 儲存體 Gen2 帳戶。

  2. 在左側功能表上，選取 [網络]。

  3. 從 選取的虛擬網路和IP位址選取 [已啟用]。

  4. 在 [防火牆] 區段中的 [位址範圍] 方塊中，指定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 的許可權使用。