將您的資料轉換為適用於 Azure API for FHIR 的 FHIR

發行項
09/28/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 和醫療技術服務。

FHIR® 服務中的 $convert-data 自訂端點是為了將資料從不同資料類型轉換為 FHIR。其使用 Liquid 範本引擎和 FHIR 轉換器專案的範本作為預設範本。您可以視需要自訂這些轉換範本。

目前 $convert-data 自訂端點支援四種類型的資料轉換：

原始資料格式	目的地資料格式
C-CDA	FHIR
HL7v2	FHIR
JSON	FHIR
FHIR STU3	FHIR R4

注意

$convert-data 端點可以作為匯出、轉換、載入 (ETL) 管線內的元件，將原始醫療保健資料從舊格式轉換為 FHIR 格式。不過，其本身並不是 ETL 管線。我們建議您使用 ETL 引擎 (例如 Logic Apps 或 Azure Data Factory) 以取得完整的工作流程，以便準備將 FHIR 資料保留至 FHIR 伺服器中。工作流程可能包含：資料讀取和擷取、資料驗證、進行 $convert-data API 呼叫、資料預先/後處理、資料擴充和重複資料刪除。

使用 $convert 資料端點

$convert-data 作業將整合至 FHIR 服務以作為服務一部分執行。在伺服器中啟用 $convert-data 之後，您可以使用 https://<<FHIR service base URL>>/$convert-data，對伺服器進行 API 呼叫，將資料轉換成 FHIR。

參數資源

$convert-data 將採用要求本文中的參數資源，如下表所述。在 API 呼叫要求本文中，您將包含下列參數：

參數名稱	描述	接受的值
inputData	要轉換的資料。	若為 `Hl7v2`：字串若為 `Ccda`：XML 若為 `Json`：JSON 若為 `FHIR STU3`：JSON
inputDataType	輸入的資料類型。
templateCollectionReference	Azure Container Registry (ACR) 中 OCI 映像範本集合的參考。這是包含轉換所使用 Liquid 範本的映像。其可以是預設範本的參考或 FHIR 服務中註冊的自訂範本映像。請參閱下列內容，以了解如何自訂範本、在 ACR 上裝載這些範本，以及註冊至 FHIR 服務。	若為預設/範例範本： HL7v2 範本： `microsofthealth/fhirconverter:default` `microsofthealth/hl7v2templates:default` C-CDA 範本： `microsofthealth/ccdatemplates:default` JSON 範本： `microsofthealth/jsontemplates:default` FHIR STU3 範本： `microsofthealth/stu3tor4templates:default` 若為自訂範本： <RegistryServer>/<imageName>@<imageDigest>、<RegistryServer>/<imageName>:<imageTag>
rootTemplate	轉換資料時要使用的根目錄範本。	若為 HL7v2： "ADT_A01"、"ADT_A02"、"ADT_A03"、"ADT_A04"、"ADT_A05"、"ADT_A08"、"ADT_A11"、"ADT_A13"、"ADT_A14"、"ADT_A15"、"ADT_A16"、"ADT_A25"、"ADT_A26"、"ADT_A27"、"ADT_A28"、"ADT_A29"、"ADT_A31"、"ADT_A47"、"ADT_A60"、"OML_O21"、"ORU_R01"、"ORM_O01"、"VXU_V04"、"SIU_S12"、"SIU_S13"、"SIU_S14"、"SIU_S15"、"SIU_S16"、"SIU_S17"、"SIU_S26"、"MDM_T01"、"MDM_T02" 若為 C-CDA： "CCD"、"ConsultationNote"、"DischargeSummary"、"HistoryandPhysical"、"OperativeNote"、"ProcedureNote"、"ProgressNote"、"ReferralNote"、"TransferSummary" 若為 JSON： "ExamplePatient"、"Stu3ChargeItem" FHIR STU3"： STU3 資源，例如 Name、"Patient"、"Observation"、"Organization"。

注意

FHIR STU3 至 R4 範本是「差異」的 Liquid 範本，只提供 STU3 資源與其 FHIR R4 標準中對等資源的欄位差異對應。某些 STU3 資源會重新命名或從 R4 中移除。請參閱 STU3 到 R4 轉換的資源差異和限制。

注意

JSON 範本是要使用的範例範本，而不是遵循任何預先定義 JSON 訊息類型的「預設」範本。 JSON 沒有標準化的訊息類型，與 HL7v2 訊息或 C-CDA 文件不同。我們不會提供「預設」JSON 範本，而是提供一些範例範本，讓您用於作為自己自訂範本的入門指南。

警告

預設範本的發行符合 MIT 授權，且不在 Microsoft 支援服務的支援範圍內。

僅提供預設範本來協助您開始使用。當我們更新 Azure API for FHIR 的版本時，範本也會隨之更新。您必須確認轉換行為，並在 Azure Container Registry 上裝載您自己的範本複本，將這些範本註冊到 Azure API for FHIR，以在 API 呼叫中使用。這是跨不同 Azure API for FHIR 版本一致資料轉換行為的必要項目。

範例要求

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "inputData",
            "valueString": "MSH|^~\\&|SIMHOSP|SFAC|RAPP|RFAC|20200508131015||ADT^A01|517|T|2.3|||AL||44|ASCII\nEVN|A01|20200508131015|||C005^Whittingham^Sylvia^^^Dr^^^DRNBR^D^^^ORGDR|\nPID|1|3735064194^^^SIMULATOR MRN^MRN|3735064194^^^SIMULATOR MRN^MRN~2021051528^^^NHSNBR^NHSNMBR||Kinmonth^Joanna^Chelsea^^Ms^^D||19870624000000|F|||89 Transaction House^Handmaiden Street^Wembley^^FV75 4GJ^GBR^HOME||020 3614 5541^PRN|||||||||C^White - Other^^^||||||||\nPD1|||FAMILY PRACTICE^^12345|\nPV1|1|I|OtherWard^MainRoom^Bed 183^Simulated Hospital^^BED^Main Building^4|28b|||C005^Whittingham^Sylvia^^^Dr^^^DRNBR^D^^^ORGDR|||CAR|||||||||16094728916771313876^^^^visitid||||||||||||||||||||||ARRIVED|||20200508131015||"
        },
        {
            "name": "inputDataType",
            "valueString": "Hl7v2"
        },
        {
            "name": "templateCollectionReference",
            "valueString": "microsofthealth/fhirconverter:default"
        },
        {
            "name": "rootTemplate",
            "valueString": "ADT_A01"
        }
    ]
}

範例回應

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:9d697ec3-48c3-3e17-db6a-29a1765e22c6",
      "resource": {
        "resourceType": "Patient",
        "id": "9d697ec3-48c3-3e17-db6a-29a1765e22c6",
        ...
        ...
      "request": {
        "method": "PUT",
        "url": "Location/50becdb5-ff56-56c6-40a1-6d554dca80f0"
      }
    }
  ]
}

自訂範本

您可以使用 Visual Studio Code 的 FHIR 轉換器延伸模組來根據您的需求自訂範本。此延伸模組提供互動式編輯體驗，可讓您輕鬆下載 Microsoft 發佈的範本和範例資料。如需詳細資訊，請參閱延伸模組的文件。

注意

適用於 Visual Studio Code 的 FHIR 轉換器延伸模組可支援 HL7v2、C-CDA 和 JSON Liquid 範本。目前不支援 FHIR STU3 到 R4 Liquid 範本。

裝載並使用範本

建議您在 ACR 上裝載您自己的範本複本。裝載您自己的範本複本並在 $convert-data 作業中使用這些範本複本有四個步驟：

將範本推送至您的 Azure Container Registry。
在 Azure API for FHIR 執行個體上啟用受控識別。
提供 ACR 對 Azure API for FHIR 受控識別的存取。
在 Azure API for FHIR 中註冊 ACR 伺服器。
選擇性設定 ACR 防火牆以保護存取。

將範本推送至 Azure Container Registry

建立 ACR 執行個體之後，您可以在 FHIR 轉換器延伸模組中使用 FHIR Converter: Push Templates 命令，將自訂範本推送至 ACR。或者，您也可以使用範本管理 CLI 工具。

在 Azure API for FHIR 上啟用受控識別

在 Azure 入口網站中瀏覽至 Azure API for FHIR 服務的執行個體，然後選取 [身分識別] 刀鋒視窗。在 Azure API for FHIR 中將狀態變更為 [開啟] 以啟用受控識別。

提供對 ACR 對 Azure API for FHIR 的存取

瀏覽至 [存取控制 (IAM)] 刀鋒視窗。
選擇 [新增]，然後選取 [新增角色指派] 以開啟 [新增角色指派] 頁面。
指派 AcrPull 角色。

如需在 Azure 入口網站中指派角色的詳細資訊，請參閱 Azure 內建角色 (部分機器翻譯)。

在 Azure API for FHIR 中註冊 ACR 伺服器

您可以使用 Azure 入口網站或 CLI 來註冊 ACR 伺服器。

使用 Azure 入口網站註冊 ACR 伺服器

在 Azure API for FHIR 執行個體中，瀏覽至 [資料轉換] 下的 [Artifacts] 刀鋒視窗。您會看到目前註冊的 ACR 伺服器清單。選取 [新增]，然後從下拉式清單功能表選取您的登錄伺服器。您必須選取 [儲存]，註冊才會生效。套用變更和重新啟動執行個體可能需要幾分鐘的時間。

使用 CLI 註冊 ACR 伺服器

您可以在 Azure API for FHIR 中註冊最多 20 部 ACR 伺服器。

視需要從 Azure PowerShell 安裝 Azure 健康資料服務 CLI：

az extension add -n healthcareapis

遵循下方範例，將 ACR 伺服器註冊至 Azure API for FHIR：

註冊單一 ACR 伺服器

az healthcareapis acr add --login-servers "fhiracr2021.azurecr.io" --resource-group fhir-test --resource-name fhirtest2021

註冊多個 ACR 伺服器

az healthcareapis acr add --login-servers "fhiracr2021.azurecr.io fhiracr2020.azurecr.io" --resource-group fhir-test --resource-name fhirtest2021

設定 ACR 防火牆

從入口網站選取 Azure 儲存體帳戶的 [網路]。

容器登錄的畫面影像。

選取 [選取的網路]。

在 [防火牆] 區段下，於 [位址範圍] 方塊中指定 IP 位址。新增 IP 範圍以允許來自網際網路或內部部署網路的存取。

您可以在下表中找到 Azure API for FHIR 服務佈建所在 Azure 區域的 IP 位址。

Azure 區域	公用 IP 位址
澳大利亞東部	20.53.47.210
巴西南部	191.238.72.227
加拿大中部	20.48.197.161
印度中部	20.192.47.66
美國東部	20.62.134.242、20.62.134.244、20.62.134.245
美國東部 2	20.62.60.115、20.62.60.116、20.62.60.117
法國中部	51.138.211.19
德國北部	51.116.60.240
德國中西部	20.52.88.224
日本東部	20.191.167.146
日本西部	20.189.228.225
南韓中部	20.194.75.193
美國中北部	52.162.111.130、20.51.0.209
北歐	52.146.137.179
卡達中部	20.21.36.225
南非北部	102.133.220.199
美國中南部	20.65.134.83
東南亞	20.195.67.208
瑞典中部	51.12.28.100
瑞士北部	51.107.247.97
英國南部	51.143.213.211
英國西部	51.140.210.86
美國中西部	13.71.199.119
西歐	20.61.103.243、20.61.103.244
美國西部 2	20.51.13.80、20.51.13.84、20.51.13.85
美國西部 3	20.150.245.165

注意

上述步驟與＜如何匯出 FHIR 資料＞文件中所述的設定步驟相似。如需詳細資訊，請參閱安全匯出至 Azure 儲存體

Verify

呼叫 $convert-data API 以在 templateCollectionReference 參數中指定範本參考。

<RegistryServer>/<imageName>@<imageDigest>

下一步

在本文中，您已了解 Azure API for FHIR 的資料轉換。如需 Azure API for FHIR 相關 GitHub 專案的詳細資訊，請參閱

Azure API for FHIR 相關的 GitHub 專案

注意

FHIR® 是 HL7 的註冊商標，在 HL7 的許可下使用。

共用方式為