导出 FHIR 数据

可以使用 import 操作将 FHIR® 数据引入到具有高吞吐量的 FHIR 服务器。

导入操作模式

import 操作支持两种模式：初始模式和增量模式。 每种模式都有不同的功能和用例。

初始模式

• 用于将 FHIR 资源加载到空的 FHIR 服务器。

• 阻止 API 写入 FHIR 服务器。

增量模式

• 针对定期将数据加载到 FHIR 服务器进行优化，不阻止通过 API 进行写入。

• 允许在资源 JSON 中存在 lastUpdated 和 versionId 值时从资源元数据加载这两个值。

• 允许以非版本连续顺序加载资源。 有关资源的非连续引入的说明

  • 如果导入文件没有指定 version 和 lastUpdated 字段值，则不能保证将所有资源导入到 FHIR 服务中。
  • 如果导入文件的资源具有重复的 version 和 lastUpdated 字段值，则 FHIR 服务中仅随机引入一个资源。
  • 在并行执行期间，如果多个资源共享相同的资源 ID，则仅随机导入其中一个资源。

下表显示了导入模式之间的差别。

区域	初始模式	增量模式
能力	将数据初始加载到 FHIR 服务	将数据连续引入到 FHIR 服务（增量或近实时）。
并发 API 调用	阻止并发写入操作	在 FHIR 服务器上执行 API CRUD 操作时，可以同时引入数据。
引入版本控制的资源	不支持	支持在保持资源历史记录的同时，在单个批次中引入多个版本的 FHIR 资源。
保留“lastUpdated”字段值	不支持	在引入过程中保留 FHIR 资源中的“lastUpdated”字段值。
计费	不会产生任何费用	根据成功引入的资源产生费用。 按 API 定价产生费用。

性能注意事项

若要通过 import 操作实现最佳性能，请考虑以下因素。

• 使用大型文件进行导入。 导入的最佳 NDJSON 文件大小是 >=50 MB（或 >=20 K 资源，没有上限）。 请考虑将较小的文件组合在一起。

• 将 FHIR 资源文件作为单个批次导入。 如需实现最优性能，请借助一个 import 操作将要引入的所有 FHIR 资源文件导入到 FHIR 服务器。 借助一个操作导入所有文件，可降低创建和管理多个导入作业的开销。 或者，单次导入的文件总大小应较大（>=100 GB 或 >=100M 资源没有上限）。

• 限制并行导入作业数。 可以同时运行多个 import 作业，但可能会影响 import 操作的总体吞吐量。

执行导入操作

先决条件

• 若要使用 import 操作 ，需要 FHIR 服务器上的 FHIR 数据导入者角色。

• 配置 FHIR 服务器。 必须在 Azure Blob 存储上将 FHIR 数据以 FHIR NDJSON 格式存储在资源特定的文件中。 有关详细信息，请参阅配置导入设置。

• 数据必须与 FHIR 服务位于同一租户中。

• 若要获取访问令牌，请参阅访问令牌

进行调用

使用以下请求标头和正文对 POST 进行 <<FHIR service base URL>>/$import 调用。

请求标头

Prefer:respond-async
Content-Type:application/fhir+json

身体

下表描述了正文参数和输入。

参数名称	DESCRIPTION	基数	接受的值
inputFormat	表示数据源格式名称的字符串。 仅支持 FHIR NDJSON 文件。	1..1	application/fhir+ndjson
mode	导入模式值。	1..1	对于初始模式导入，请使用 InitialLoad 模式值。 对于增量模式导入，请使用 IncrementalLoad 模式值。 如果未提供模式值，则默认使用 IncrementalLoad 模式值。
allowNegativeVersions	允许 FHIR 服务器为具有显式“lastUpdated”值的资源记录分配负版本，并且当输入不适合存储中现有正版本的连续空间时，指定无版本。	0..1	若要启用此功能，请传递 true。 默认为 false。
errorContainerName	字符串，表示将在导入过程中遇到错误的容器的名称。	0..1	错误日志的自定义容器名称。 名称应介于 3-63 个字符之间，并且只包含小写字母、数字和连字符。 如果未指定，将使用默认容器。
input	输入文件的详细信息。	1..*	一个 JSON 数组，其中包含下表中所述的三个部分。

输入部分名称	DESCRIPTION	基数	接受的值
type	输入文件的资源类型。	0..1	与输入文件匹配的有效 FHIR 资源类型。 此字段可选。
url	输入文件的 Azure 存储 URL。	1..1	输入文件的 URL 值。 此值不可修改。
etag	Azure 存储中输入文件的 ETag。 用于验证 import 注册后文件内容是否未更改。	0..1	输入文件的 ETag 值。

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "inputFormat",
            "valueString": "application/fhir+ndjson"
        },
        {
            "name": "mode",
            "valueString": "<Use "InitialLoad" for initial mode import / Use "IncrementalLoad" for incremental mode import>"
        }, 
        {
            "name": "allowNegativeVersions",
            "valueBoolean": true
        },
        {
            "name": "errorContainerName",
            "valueString": "import-error-logs"
        },
        {
            "name": "input",
            "part": [
                { 
                    "name": "url",
                    "valueUri": "https://example.blob.core.windows.net/resources/filename.ndjson"
                },
                {
                    "name": "etag",
                    "valueUri": "\"0x8D92A7342657F4F\""
                }
            ]
        }
    ]
}

查看导入状态

启动 import 操作后，响应的 callback 标头中将返回具有 Content-location 链接的空响应正文，以及 202 Accepted 状态代码。 存储 callback 链接以检查导入状态。

import 操作的注册作为幂等调用实现。 相同的注册有效负载会生成相同的注册，这会影响重新处理同名文件的能力。 不要就地更新文件。 相反，建议对更新的数据使用不同的文件名。 或者，如果无法避免对相同文件名进行就地更新，请在注册有效负载中添加 ETag。

若要检查导入状态，请使用 GET 方法对上一步中返回的 callback 链接进行 REST 调用。

使用此表解释响应。

响应代码	响应正文	DESCRIPTION
202 Accepted		操作仍在运行。
200 OK	The response body doesn't contain any error.url entry	所有资源都已成功导入。
200 OK	The response body contains some error.url entry	导入某些资源时发生错误。 有关详细信息，请参阅 error.url 的文件。 其余资源已成功导入。
Other		发生致命错误，操作已停止。 成功导入的资源不会回滚。

下表介绍响应正文中的重要字段：

字段	DESCRIPTION
transactionTime	批量 import 操作的开始时间。
output.count	已成功导入的资源计数。
error.count	由于错误而未导入的资源计数。
error.url	包含错误详细信息的文件的 URL。 每个 error.url 实例对输入 URL 是唯一的。

{
    "transactionTime": "2021-07-16T06:46:52.3873388+00:00",
    "request": "https://importperf.azurewebsites.net/$Import",
    "output": [
        {
            "type": <null in case type parameter in not populated in request. If provided, resource name will be added>,
            "count": 10000,
            "inputUrl": "https://example.blob.core.windows.net/resources/filename.ndjson"
        }
    ],
    "error": [
        { 
        "type": "OperationOutcome",
        "count": 51,
        "inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.ndjson",
        "url": "https://example.blob.core.windows.net/fhirlogs/CarePlan06b88c6933a34c7c83cb18b7dd6ae3d8.ndjson"
        }
    ]
}

引入软删除的资源

增量模式导入支持引入软删除的资源。 需要使用扩展在 FHIR 服务中引入软删除的资源。

将扩展添加到资源，以通知 FHIR 服务该资源已软删除。

{"resourceType": "Patient", "id": "example10", "meta": { "lastUpdated": "2023-10-27T04:00:00.000Z", "versionId": 4, "extension": [ { "url": "http://azurehealthcareapis.com/data-extensions/deleted-state", "valueString": "soft-deleted" } ] } }

import 操作成功完成后，对资源执行历史记录搜索以验证软删除的资源。 如果知道已删除资源的 ID，请使用以下示例中的 URL 模式。

<FHIR_URL>/<resource-type>/<resource-id>/_history

如果不知道资源的 ID，请对资源类型执行历史记录搜索。

<FHIR_URL>/<resource-type>/_history

排查导入操作问题

此处是 import 操作失败时产生的错误消息以及建议的操作，用于解决问题。

200 正常，但响应中的 URL 有错误

import 操作成功，返回 200 OK。 但是，响应正文中存在 error.url。 位于 error.url 位置的文件包含类似于以下示例的 JSON 片段。

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "details": {
                "text": "Given conditional reference '{0}' doesn't resolve to a resource."
            },
            "diagnostics": "Failed to process resource at line: {0} with stream start offset: {1}"
        }
    ]
}

原因：NDJSON 文件包含具有 import 不支持的条件引用的资源。

解决方案：将条件引用替换为 NDJSON 文件中的普通引用。

400 错误的请求

import 操作失败，返回 400 Bad Request。 响应正文包含诊断内容

导入操作失败，原因如下：此类主机未知。 （example.blob.core.windows.net:443） 解决方案：验证指向 Azure 存储的链接是否正确。 检查网络和防火墙设置，确保 FHIR 服务器可以访问存储。 如果服务位于虚拟网络中，请确保存储位于同一虚拟网络或位于与 FHIR 服务的虚拟网络对等互连的虚拟网络。

导入无法处理 SearchParameter 资源 解决方案：当通过导入过程引入搜索参数资源时，导入操作将返回 HTTP 400 错误。 此更改旨在防止在使用导入操作引入时搜索参数处于无效状态。

403 禁止访问

import 操作失败，返回 403 Forbidden。 响应正文包含诊断内容。

导入操作失败，原因如下：服务器未能对请求进行身份验证。 请确保授权标头的值构成正确，且包括签名。 原因：FHIR 服务使用托管标识进行源存储身份验证。 此错误表示角色分配缺失或不正确。 解决方案：将“存储 Blob 数据参与者”角色分配给 FHIR 服务器。 有关详细信息，请参阅分配 Azure 角色。

500 内部服务器错误

import 操作失败，返回 500 Internal Server Error。 响应正文包含诊断内容

导入操作失败，原因如下：数据库“****”已达到其大小配额。 请将数据分区或删除、删除索引或查阅文档以找到可能的解决方案。

原因：已达到 FHIR 服务的存储限制。

解决方案：减小数据大小，或考虑使用适用于 FHIR 的 Azure API，该 API 具有更高的存储限制。

423 已锁定

行为： 操作失败，返回 import。423 Locked 响应正文包含以下内容：

{
    "resourceType": "OperationOutcome",
    "id": "13876ec9-3170-4525-87ec-9e165052d70d",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: Service is locked for initial import mode."
        }
    ]
}

原因：FHIR 服务配置了阻止其他操作的初始导入模式。

解决方案：关闭 FHIR 服务的初始导入模式，或选择“增量模式”。

局限性

• 每个 import 操作允许的最大文件数为 10,000。
• FHIR 服务器中引入的“lastUpdated”字段值及毫秒数相同的文件数不得超过 10,000。
• SearchParameter 资源类型不支持导入操作。
• 导入操作不支持资源中的条件引用。

后续步骤

将数据转换为 FHIR

配置导出设置并设置存储帐户

将数据复制到 Azure Synapse Analytics

注释

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