使用 Azure 门户配置 $convert-data 的设置

本文说明如何使用 Azure 门户配置 $convert-data 的设置，将健康数据转换为 FHIR® R4。

默认模板

Microsoft 发布了一组来自 FHIR Converter 项目的预定义 Liquid 模板示例，以支持 FHIR 数据转换。 这些模板仅用于帮助开始数据转换工作流。 建议自定义并托管自己的模板，以支持自身的数据转换需求。 有关自定义模板的信息，请参阅自定义模板。

默认模板托管在公共容器注册表中，无需对 FHIR 服务进行任何其他配置或设置。 要访问和使用转换请求的默认模板，请确保在调用 $convert-data 操作时，templateCollectionReference 请求参数具有基于数据输入类型的相应值。

• HL7v2 模板
• C-CDA模板
• JSON 模板
• FHIR STU3 模板

自定义模板

可以使用 FHIR 转换器 Visual Studio Code 扩展根据自己的具体要求自定义模板。 此扩展提供交互式编辑体验，让你能够轻松地下载 Microsoft 发布的模板和示例数据。

如果需要，可以使用提供的默认模板作为起点，并在此基础上添加自定义内容。 在对模板进行更新时，请考虑遵循以下准则，以避免出现意外转换结果。

模板的编写方式应使其能够生成有效的 FHIR 捆绑资源结构。

例如，Liquid 模板应该采用如下代码格式：

<liquid assignment line 1 >
<liquid assignment line 2 >
.
.
<liquid assignment line n >	          
{
    "resourceType": "Bundle",
    "type": "xxx",
    <...liquid code...>
    "identifier":
    {
        "value":"xxxxx",
    },
    "id":"xxxx",
    "entry": [
	<...liquid code...>
   ]
}

整体模板遵循 FHIR 捆绑资源的结构和预期内容，FHIR 捆绑 JSON 位于文件的根目录。 如果你选择向模板添加的自定义字段不属于捆绑资源的 FHIR 规范，则转换请求可能会出现问题。 但是，转换后的结果可能会产生意外输出，并且不会生成可以按原样保存在 FHIR 服务中的有效 FHIR 捆绑资源。

例如，考虑以下代码：

<liquid assignment line 1 >
<liquid assignment line 2 >
.
.
<liquid assignment line n >	          
{
   “customfield_message”: “I will have a message here”,
    “customfield_data”: {
      "resourceType": "Bundle",
      "type": "xxx",
      <...liquid code...>
      "identifier":
      {
        "value":"xxxxx",
      },
       "id":"xxxx",
       "entry": [
	  <...liquid code...>
    ]
  }
}

在示例代码中，两个示例自定义字段 customfield_message 和 customfield_data 不是符号规范的 FHIR 属性，并且 FHIR 捆绑资源似乎嵌套在 customfield_data 下（也就是说，FHIR 捆绑 JSON 不在文件的根目录）。 此模板与 FHIR 捆绑资源的预期结构不符。 使用提供的模板，转换请求可能会成功。 但是，返回的转换结果可能会出现意外输出（因为跳过了某些转换后处理步骤）。 它不会被视为有效的 FHIR 捆绑（因为它是嵌套的且具有非 FHIR 规范属性），尝试将结果保留在 FHIR 服务中失败。

托管自己的模板

建议将自己的模板副本托管在 Azure 容器注册表 (ACR) 实例中。 ACR 可用于托管自定义模板和支持版本控制。

托管自己的模板并将其用于 $convert-data 操作涉及以下七个步骤。

1. 创建 Azure 容器注册表实例
2. 将模板推送到 Azure 容器注册表实例
3. 在 FHIR 服务实例中启用 Azure 托管标识
4. 向 FHIR 服务托管标识提供 Azure 容器注册表访问权限
5. 在 FHIR 服务中注册 Azure 容器注册表服务器
6. 配置 Azure 容器注册表防火墙以实现安全访问
7. 验证 $convert-data 操作

步骤 1：创建 Azure 容器注册表实例

阅读 Azure 中的容器注册表简介，并按照说明创建自己的 ACR 实例。 建议将 ACR 实例放置在与 FHIR 服务相同的资源组中。

步骤 2：将模板推送到 Azure 容器注册表实例

创建 ACR 实例后，可以使用 FHIR 转换器扩展 中的 FHIR Converter: Push Templates 命令将自定义模板推送到 ACR 实例。 另外，还可使用模板管理 CLI 工具来实现此目的。

要在 Azure 容器注册表中维护不同版本的自定义模板，可以将包含自定义模板的映像推送到 ACR 实例中，并使用不同的映像标签。

• 有关 ACR 注册表、存储库和工件的详细信息，请参阅关于注册表、存储库和工件。
• 有关映像标签最佳做法的详细信息，请参阅容器映像的标记和版本控制建议。

要在 API 中引用特定模板版本，请务必使用包含要使用的模板的确切映像名称和标签，该模板已进行版本控制。 对于 API 参数 templateCollectionReference，请使用相应的“映像名称 + 标签”（例如：<RegistryServer>/<imageName>:<imageTag>）。

步骤 3：在 FHIR 服务实例中启用 Azure 托管标识

1. 转到 Azure 门户中的 FHIR 服务实例，然后选择“标识”选项。

2. 将“状态”更改为“开启”，然后选择“保存”，以在 FHIR 服务中启用系统管理的标识。

步骤 4：向 FHIR 服务托管标识提供 Azure 容器注册表访问权限

1. 在资源组中，转到“容器注册表”实例，然后选择“访问控制(IAM)”选项卡。

2. 选择添加>添加角色分配。 如果“添加角色分配”选项不可用，请让 Azure 管理员授予你执行此任务的权限。

   

3. 在“角色”窗格中，选择 AcrPull 角色。

   

4. 在“成员”选项卡上，选择“托管标识”，然后选择“选择成员”。

5. 选择 Azure 订阅。

6. 选择“系统分配的托管标识”，然后选择正在使用的 FHIR 服务。

7. 在“审核 + 指派”选项卡上，选择“审核 + 指派”以进行角色分配。

若要详细了解如何在 Azure 门户中分配角色，请参阅 Azure 内置角色。

步骤 5：在 FHIR 服务中注册 Azure 容器注册表服务器

可以使用 Azure 门户注册 ACR 服务器。

若要使用 Azure 门户，请执行以下作：

1. 在 FHIR 服务实例的“传输和转换数据”下，选择“工件”。 此时会显示当前已注册的 Azure 容器注册表服务器列表。
2. 选择“添加”，然后在下拉列表中选择你的注册表服务器。
3. 选择“保存”。

可以在 FHIR 服务中注册最多 20 个 ACR 服务器。

步骤 6：配置 Azure 容器注册表防火墙以实现安全访问

根据具体用例，可通过多种方法来使用内置防火墙保护 ACR。

• 使用 Azure 专用链接以私密方式连接到 Azure 容器注册表
• 配置公共 IP 网络规则
• Azure 容器注册表使用专用数据终结点缓解数据外泄
• 使用 Azure 虚拟网络中的服务终结点限制对容器注册表的访问
• 允许受信任的服务安全访问受网络限制的容器注册表
• 配置从防火墙后面访问 Azure 容器注册表的规则
• Azure IP Ranges and Service Tags – Public Cloud（Azure IP 范围和服务标记 - 公有云）

步骤 7：验证 $convert-data 操作

通过在 $convert-data 参数中指定模板引用来调用 templateCollectionReference 操作：

<RegistryServer>/<imageName>@<imageDigest>。

你应该会收到一个 bundle 响应，其中包含转换为 FHIR 格式的健康数据。

后续步骤

$convert-data 概述

排查 $convert-data 问题

$convert-data 常见问题解答