將資料轉換成 FHIR for Azure API for FHIR

發行項
03/10/2023

$convert-dataFHIR 服務中的自訂端點適用于從不同資料類型轉換為 FHIR 的資料。它會使用 Liquid 範本引擎和來自 FHIR Converter 專案的範本作為預設範本。您可以視需要自訂這些轉換範本。

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

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

注意

$convert-data 端點可作為 ETL 管線內的元件，以將原始醫療保健資料從舊版格式轉換成 FHIR 格式。不過，它本身不是 ETL 管線。建議您使用 Logic Apps 或 Azure Data Factory 之類的 ETL 引擎，以準備 FHIR 資料以保存到 FHIR 伺服器中的完整工作流程。工作流程可能包括：資料讀取和擷取、資料驗證、進行$convert資料 API 呼叫、資料前置/後置處理、資料擴充和資料重復資料。

使用 $convert 資料端點

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

參數資源

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

參數名稱	描述	接受的值
inputData	要轉換的資料。	針對 `Hl7v2` ：string 針對 `Ccda` ：XML 針對 `Json` ：JSON 針對 `FHIR STU3` ：JSON
inputDataType	輸入的資料類型。	`HL7v2`, `Ccda`, `Json`, `Fhir`
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_A15」、「ADT_A16」、「ADT_A25」、「ADT_A26」、「ADT_A26」、「」ADT_A27「、」ADT_A28「、」ADT_A29「、」ADT_A31「、」ADT_A47「、」ADT_A60「、」OML_O21「、」ORU_R01「、」ORM_O01「、」ORM_O01「、」VXU_V04「、」SIU_S12「、」SIU_S13「、」SIU_S14「、」SIU_S15「、」SIU_S16「、」SIU_S16「、」「SIU_S17」、「SIU_S26」、「MDM_T01」、「MDM_T02」針對 C-CDA：「CCD」、「ConsultationNote」、「一體」、「HistoryandPhysical」、「Note」、「ProcedureNote」、「ProgressNote」、「ReferralNote」、「TransferSummary」針對 JSON：「ExamplePatient」、「Stu3ChargeItem」 FHIR STU3「： STU3 資源名稱，例如「病患」、「觀察」、「組織」。

注意

FHIR STU3 至 R4 範本是「diff」 Liquid 範本，其僅提供 STU3 資源與其 FHIR R4 標準中對等資源的欄位差異對應。部分 STU3 資源會從 R4 重新命名或移除。請參閱 STU3 到 R4 轉換的資源差異和條件約束。

注意

JSON 範本是要使用的範例範本，而不是遵守任何預先定義 JSON 訊息類型的「預設」範本。 JSON 沒有任何標準化的訊息類型，不同于 HL7v2 訊息或 C-CDA 檔。因此，我們不會提供預設範本，而是提供一些範例範本，供您作為自訂範本的起始指南。

警告

預設範本會在 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資料作業中的範本複本有四個步驟：

將範本推送至您的Azure Container Registry。
在 Azure API for FHIR 實例上啟用受控識別。
提供 ACR 對 Azure API for FHIR 受控識別的存取權。
在 Azure API for FHIR 中註冊 ACR 伺服器。
選擇性地設定 ACR 防火牆以進行安全存取。

將範本推送至Azure Container Registry

建立 ACR 實例之後，您可以使用 FHIR Converter： Push Templates 命令，在 FHIR Converter 擴充功能中將自訂範本推送至 ACR。或者，您也可以使用此用途的範本管理工具。

在 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 實例中[資料轉換] 底下的 [成品]刀鋒視窗。您會看到目前已註冊的 ACR 伺服器清單。選取 [新增]，然後從下拉式功能表中選取您的登錄伺服器。您必須選取 [ 儲存 ]，註冊才會生效。套用變更並重新啟動實例可能需要幾分鐘的時間。

使用 CLI 註冊 ACR 伺服器

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

視需要從 Azure PowerShell 安裝 Azure Health Data Services 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 儲存體

驗證

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

<RegistryServer>/<imageName>@<imageDigest>

下一步

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

適用于 Azure API for FHIR 的相關 GitHub 專案

FHIR® 是 HL7 的注冊商標，並搭配 HL7 的許可權使用。

Share via

將資料轉換成 FHIR for Azure API for FHIR

使用 $convert 資料端點

參數資源

範例要求

範例回應

自訂範本

裝載並使用範本

將範本推送至Azure Container Registry

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

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

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

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

使用 CLI 註冊 ACR 伺服器

註冊單一 ACR 伺服器

註冊多個 ACR 伺服器

設定 ACR 防火牆

驗證

下一步

其他資源

Share via

將資料轉換成 FHIR for Azure API for FHIR

使用 $convert 資料端點

參數資源

範例要求

範例回應

自訂範本

裝載並使用範本

將範本推送至Azure Container Registry

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

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

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

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

使用 CLI 註冊 ACR 伺服器

註冊單一 ACR 伺服器

註冊多個 ACR 伺服器

設定 ACR 防火牆

驗證

下一步

其他資源

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