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

导入操作

项目
09/07/2023

导入操作允许使用$import操作以高吞吐量将快速医疗保健互操作性资源 (FHIR®) 数据加载到 FHIR 服务器。导入支持初始和增量数据加载到 FHIR 服务器。

使用$import操作

注意

必须在 FHIR 服务器上具有 FHIR 数据导入程序 角色才能使用 $import。

若要使用 $import，需要按照配置导入设置一文中的说明配置 FHIR 服务器。要导入的 FHIR 数据必须存储在 Azure Blob 存储上采用 FHIR NDJSON 格式的资源特定文件中。

对于导入操作，请确保

文件中的所有资源必须属于同一类型。每个资源类型可能有多个文件。
要导入的数据必须与 FHIR 服务位于同一租户中。
每个操作要导入的最大文件数为 10，000。

注意：

导入操作不支持资源中的条件引用。
在导入操作期间，如果多个资源共享同一资源 ID，则只会随机导入其中一个资源。共享同一资源 ID 的资源记录了错误。

呼叫$import

POST调用时<<FHIR service base URL>>/$import显示请求标头和正文：

请求头

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

正文

参数名称	说明	卡。	接受的值
inputFormat	表示数据源格式的名称的字符串。目前仅支持 FHIR NDJSON 文件。	1..1	`application/fhir+ndjson`
mode	导入模式值	1..1	对于初始导入，请使用 `InitialLoad` 模式值。对于增量导入模式，请使用 `IncrementalLoad` 模式值。如果未提供任何模式值，则默认情况下会考虑 IncrementalLoad 模式值。
input	输入文件的详细信息。	1..*	包含下表所述的三个部分的 JSON 数组。

输入部件名称	说明	卡。	接受的值
类型	输入文件的资源类型	1..1	与输入文件匹配的有效 FHIR 资源类型。
URL	输入文件的 Azure 存储 URL	1..1	无法修改的输入文件的 URL 值。
etag	Azure 存储上用于验证文件内容未更改的输入文件的 Etag。	0..1	无法修改的输入文件的 Etag 值。

初始加载导入的示例正文：

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "inputFormat",
            "valueString": "application/fhir+ndjson"
        },
        {
            "name": "mode",
            "valueString": "InitialLoad"
        },
        {
            "name": "input",
            "part": [
                {
                    "name": "type",
                    "valueString": "Patient"
                },
                {
                    "name": "url",
                    "valueUri": "https://example.blob.core.windows.net/resources/Patient.ndjson"
                },
                {
                    "name": "etag",
                    "valueUri": "0x8D92A7342657F4F"
                }
            ]
        },
        {
            "name": "input",
            "part": [
                {
                    "name": "type",
                    "valueString": "CarePlan"
                },
                {
                    "name": "url",
                    "valueUri": "https://example.blob.core.windows.net/resources/CarePlan.ndjson"
                }
            ]
        }
    ]
}

检查导入状态

启动$import后，响应标头中Content-location将返回一个包含回调链接的空响应正文以及202-Accepted状态代码。存储此回调链接以检查导入状态。

若要检查导入状态，请使用方法对上一步中返回的回调链接进行 REST 调用GET。可以使用下表解释响应：

响应代码	响应正文	说明
202 已接受		操作仍在运行。
200 正常	响应正文不包含任何 error.url 条目	已成功导入所有资源。
200 正常	响应正文包含一些 error.url 条目	导入某些资源时出错。有关详细信息，请参阅位于 error.url 处的文件。已成功导入其余资源。
其他		发生严重错误，操作已停止。已成功导入的资源尚未回滚。

下表提供了响应正文中的一些重要字段：

字段	说明
transactionTime	批量导入操作的开始时间。
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": "Patient",
            "count": 10000,
            "inputUrl": "https://example.blob.core.windows.net/resources/Patient.ndjson"
        },
        {
            "type": "CarePlan",
            "count": 199949,
            "inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.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"
        }
    ]
}

故障排除

让我们逐步解决在导入操作过程中可能会遇到的一些错误代码。

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

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

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

原因： NDJSON 文件包含具有条件引用的资源，$import目前不支持这些资源。

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

400 错误的请求

行为： 导入操作失败并 400 Bad Request 返回。响应正文包含以下内容：

{
    "resourceType": "OperationOutcome",
    "id": "13876ec9-3170-4525-87ec-9e165052d70d",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: No such host is known. (example.blob.core.windows.net:443)"
        }
    ]
}

解决方案： 验证指向 Azure 存储的链接是否正确。检查网络和防火墙设置，确保 FHIR 服务器能够访问存储。如果服务位于 VNet 中，请确保存储位于同一 VNet 中，或者位于与 FHIR 服务 VNet 对等互连的 VNet 中。

403 禁止访问

行为： 导入操作失败并 403 Forbidden 返回。响应正文包含以下内容：

{
    "resourceType": "OperationOutcome",
    "id": "bd545acc-af5d-42d5-82c3-280459125033",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature."
        }
    ]
}

原因： 我们使用托管标识进行源存储身份验证。此错误可能是由于角色分配缺失或错误导致的。

解决方案：按照 RBAC 指南将存储 Blob 数据参与者角色分配给 FHIR 服务器。

500 内部服务器错误

行为： 导入操作失败并 500 Internal Server Error 返回。响应正文包含以下内容：

{
    "resourceType": "OperationOutcome",
    "id": "0d0f007d-9e8e-444e-89ed-7458377d7889",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: The database '****' has reached its size quota. Partition or delete data, drop indexes, or consult the documentation for possible resolutions."
        }
    ]
}

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

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

后续步骤

本文介绍了导入操作如何以高吞吐量将 FHIR 数据导入到 FHIR 服务器。有关将数据转换为 FHIR、导出设置以设置存储帐户以及将数据移动到Azure Synapse的详细信息，请参阅

将数据转换为 FHIR

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

将数据从 Azure API for FHIR 复制到 Azure Synapse Analytics

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

通过