你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

将数据转换为 FHIR 用于 Azure API for FHIR

项目
09/29/2024

重要

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 和医疗技术服务，并集成到其他 Azure 服务。

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 引擎（如逻辑应用或 Azure 数据工厂）实现完整的工作流，以便准备要保存到 FHIR 服务器的 FHIR 数据。工作流可能包括：数据读取和引入、数据验证、进行 $convert-data API 调用、数据预处理/后期处理、数据扩充和重复数据删除。

使用 $convert-data 终结点

该 $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	输入的数据类型。	`HL7v2`、`Ccda`、`Json`、`Fhir`
templateCollectionReference	对 Azure 容器注册表 (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 资源，例如“名称”、“患者”、“观察”、“组织”。

注意

FHIR STU3 转 R4 模板是“差异”Liquid 模板，该模板仅提供 STU3 资源与其在 FHIR R4 标准中等效资源之间的字段差异映射。部分 STU3 资源已重命名或已从 R4 中删除。请参阅 STU3 到 R4 转换的资源差异和约束。

注意

JSON 模板是要使用的示例模板，而不是遵循任何预定义 JSON 消息类型的“默认”模板。与 HL7v2 消息或 C-CDA 文档不同，JSON 没有标准化的消息类型。我们提供了一些示例模板（而不是默认模板），你可以将其用作创建自己的自定义模板的起始指南。

警告

默认模板是在 MIT 许可证下发布的，不受 Microsoft 支持部门的支持。

提供的默认模板仅用于帮助你入门。更新 Azure API for FHIR 的版本时，它们可能会更新。必须验证转换行为，并在 Azure 容器注册表上托管自己的模板副本，将这些模板注册到 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 容器注册表推送模板。
在 Azure API for FHIR 实例上启用托管标识。
提供 ACR 对 Azure API for FHIR 托管标识的访问权限。
在 Azure API for FHIR 中注册 ACR 服务器。
（可选）配置 ACR 防火墙以进行安全访问。

向 Azure 容器注册表推送模板

创建 ACR 实例后，可以使用 FHIR 转换器扩展中的“FHIR 转换器：推送模板”命令将自定义模板推送到 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 实例中“数据转换”下的“项目”边栏选项卡。你会看到当前已注册的 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 范围，以允许从 Internet 或本地网络进行访问。

你会在下表中找到预配了 Azure API for FHIR 服务的 Azure 区域的 IP 地址。

Azure 区域	公共 IP 地址
澳大利亚东部	20.53.47.210
Brazil South	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 存储

验证

调用 $convert-data API，在 templateCollectionReference 参数中指定模板引用。

<RegistryServer>/<imageName>@<imageDigest>

后续步骤

在本文中，你已了解 Azure API for FHIR 的数据转换。有关适用于 Azure API for FHIR 的相关 GitHub 项目的详细信息，请参阅

Azure API for FHIR 的相关 GitHub 项目

注意

FHIR® 是 HL7 的注册商标，经 HL7 许可使用。

通过