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

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

项目
03/10/2023

$convert-data FHIR 服务中的自定义终结点用于将数据从不同数据类型转换为 FHIR。它使用 Liquid 模板引擎和来自 FHIR 转换器项目的模板作为默认模板。可根据需要自定义这些转换模板。

目前， $convert-data 自定义终结点支持 four 数据转换类型：

源数据格式	目标数据格式
C-CDA	FHIR
HL7v2	FHIR
JSON	FHIR
FHIR STU3	FHIR R4

注意

$convert-data 终结点可用作 ETL 管道中的组件，用于将原始医疗保健数据从旧格式转换为 FHIR 格式。但是，它本身不是 ETL 管道。建议使用 ETL 引擎（例如逻辑应用或Azure 数据工厂）来准备 FHIR 数据以保存到 FHIR 服务器中的完整工作流。工作流可能包括：数据读取和引入、数据验证、进行$convert数据 API 调用、数据预处理/后处理、数据扩充和重复数据删除。

使用 $convert-data 终结点

该 $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 容器注册表 (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 资源名称，例如“Patient”、“Observation”、“Organization”。

注意

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 操作中使用这些模板涉及 4 个步骤：

向 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
巴西南部	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
Japan East	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 许可使用。