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

SMART on FHIR 概述

重要

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 服务。

可替代的医学应用和可复用技术 (SMART on FHIR®) 是一项医疗保健标准，应用程序可按照该标准通过数据存储访问临床信息。 它将基于开放标准（包括 OAuth2 和 OpenID Connect）的安全层添加到 FHIR 接口，从而实现与 EHR 系统的集成。 使用 SMART on FHIR 有下面的重要好处：

• 应用程序有一种已知的方法来获取 FHIR 存储库的身份验证/授权。
• 使用 SMART on FHIR 访问 FHIR 存储库的用户只能访问与该用户关联的资源，而不是有权访问存储库中的所有数据。
• 用户可按照 SMART 临床范围仅限应用程序访问其非常有限的一组数据。

以下教程介绍使用 FHIR 服务启用 SMART on FHIR 应用程序的步骤。

先决条件

• FHIR 服务的实例
• .NET SDK 6.0
• 启用跨源资源共享 (CORS)
• 在 Microsoft Entra ID 上注册公共客户端应用程序
  • 注册应用程序后，请记下客户端应用程序的 applicationId。
• 确保有权访问 FHIR 服务的 Azure 订阅，以创建资源并添加角色分配。

使用示例 OSS 的 SMART on FHIR（SMART on FHIR（增强版））

步骤 1：设置 FHIR SMART 用户角色

按照管理用户：向用户分配角色下列出的步骤操作。 任何添加到角色“FHIR SMART 用户”的用户都能够访问 FHIR 服务，前提是其请求符合 SMART on FHIR 实现指南，如具有访问令牌的请求，其包括 fhirUser 声明和临床范围声明。 然后，向拥有此角色的用户授予的访问权限将仅限访问与其 fhirUser 分区关联的资源，并且受到临床范围中的限制。

步骤 2：FHIR 服务器与示例集成

按照 Azure 运行状况数据和 AI 示例 OSS 中的步骤操作。 这样可实现 FHIR 服务器与其他 Azure 服务（如 APIM、Azure 函数等）的集成。

注意

示例包括开源代码；在使用它之前，应查看 GitHub 上的信息和许可条款。 它们不是 Azure Health Data Service 的一部分，不受 Microsoft 支持部门支持。 这些示例可用于演示如何结合使用 Azure Health Data Services 和其他开放源代码工具来演示 ONC (g)(10) 合规性，使用 Microsoft Entra ID 作为标识提供者工作流。

SMART on FHIR 代理

单击可展开！

注意

这是所述 SMART on FHIR（增强版）的另一个路径。 SMART on FHIR 代理选项仅启用 EHR 启动序列。

步骤 1：为客户端应用程序设置管理员同意

若要使用 SMART on FHIR，必须先对应用进行身份验证和授权。 首次使用 SMART on FHIR 时，还必须获得管理同意才能让应用访问 FHIR 资源。

如果你在应用中没有所有权角色，请联系应用所有者，并要求他们在应用中为你授予管理员同意。

如果具有管理权限，请完成以下步骤，直接向你自己授予管理员同意。 （也可稍后在应用中出现提示时，向你自己授予管理员同意。）可完成相同步骤来将其他用户添加为所有者，让他们可以查看和编辑此应用注册。

若要将自己或其他用户添加为应用的所有者，请执行以下操作：

1. 在 Azure 门户中，转到 Microsoft Entra ID。
2. 在左侧菜单中，选择“应用注册”。
3. 搜索之前创建的应用注册，然后将其选中。
4. 在左侧菜单中的“管理”下，选择“所有者”。
5. 选择“添加所有者”，然后添加你自己或你想要其获得管理员同意的用户。
6. 选择“保存”

步骤 2：启用 SMART on FHIR 代理

SMART on FHIR 要求 Audience 的标识符 URI 与 FHIR 服务的 URI 相同。 Azure API for FHIR 的标准配置使用 https://azurehealthcareapis.com 的 Audience 值。 但是，你也可以设置与 FHIR 服务的特定 URL 匹配的值（例如 https://MYFHIRAPI.azurehealthcareapis.com）。 使用 SMART on FHIR 代理时必须这样做。

若要在 Azure API for FHIR 实例的“身份验证”设置中启用 SMART on FHIR 代理，请选中“SMART on FHIR 代理”复选框。

SMART on FHIR 代理充当 SMART on FHIR 应用与 Microsoft Entra ID 之间的中介。 身份验证回复（身份验证代码）必须进入 SMART on FHIR 代理，而不是进入应用本身。 然后，代理会将回复转发到应用。

由于验证码的这种两步中继方式，你需要将 Microsoft Entra 客户端应用程序的回复 URL（回调）设置为由 SMART on FHIR 代理的回复 URL 与 SMART on FHIR 应用的回复 URL 组合而成的 URL。 组合的回复 URL 采用以下形式。

https://MYFHIRAPI.azurehealthcareapis.com/AadSmartOnFhirProxy/callback/aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA

在该回复中，aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA 是 SMART on FHIR 应用回复 URL 的 base64 编码 URL 安全版本。 对于 SMART on FHIR 应用启动器，当应用在本地运行时，回复 URL 将是 https://localhost:5001/sampleapp/index.html。

可以使用如下所示的脚本生成组合的回复 URL。

$replyUrl = "https://localhost:5001/sampleapp/index.html"
$fhirServerUrl = "https://MYFHIRAPI.azurewebsites.net"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($ReplyUrl)
$encodedText = [Convert]::ToBase64String($bytes)
$encodedText = $encodedText.TrimEnd('=');
$encodedText = $encodedText.Replace('/','_');
$encodedText = $encodedText.Replace('+','-');

$newReplyUrl = $FhirServerUrl.TrimEnd('/') + "/AadSmartOnFhirProxy/callback/" + $encodedText

将回复 URL 添加到前面为 Microsoft Entra ID 创建的公共客户端应用程序。

步骤 3：获取测试患者

若要测试 Azure API for FHIR 和 SMART on FHIR 代理，数据库中至少需要有一个患者。 如果你尚未与该 API 交互过，并且数据库中没有数据，请按照使用 Postman 访问 FHIR 服务来加载患者。 请记下具体患者的 ID。

步骤 4：下载 SMART on FHIR 应用启动器

开源的适用于 Azure 的 FHIR 服务器存储库包含一个简单的 SMART on FHIR 应用启动器和一个示例 SMART on FHIR 应用。 本教程将在本地使用 SMART on FHIR 启动器来测试设置。

可使用以下命令克隆 GitHub 存储库并转到应用程序。

git clone https://github.com/Microsoft/fhir-server
cd fhir-server/samples/apps/SmartLauncher

该应用程序需要一些配置设置，可以在 appsettings.json 中进行设置：

{
    "FhirServerUrl": "https://MYFHIRAPI.azurehealthcareapis.com",
    "ClientId": "APP-ID",
    "DefaultSmartAppUrl": "/sampleapp/launch.html"
}

我们建议使用 dotnet user-secrets 功能。

dotnet user-secrets set FhirServerUrl https://MYFHIRAPI.azurehealthcareapis.com
dotnet user-secrets set ClientId <APP-ID>

使用以下命令运行应用程序。

dotnet run

步骤 5：测试 SMART on FHIR 代理

启动 SMART on FHIR 应用启动器后，可将浏览器指向 https://localhost:5001，在其中应会看到以下屏幕。

输入“患者”、“就诊”或“医师”信息时，会发现“启动上下文”已更新。 使用 Azure API for FHIR 时，启动上下文只是一个 JSON 文档，其中包含有关患者、医师等等的信息。 此启动上下文采用 base64 编码，作为 launch 查询参数传递给 SMART on FHIR 应用。 根据 SMART on FHIR 规范，此变量对于 SMART on FHIR 应用是不透明的，并且将传递给标识提供者。

SMART on FHIR 代理使用此信息来填充令牌响应中的字段。 SMART on FHIR 应用可以使用这些字段来控制它要请求哪个患者的数据，以及如何在屏幕上呈现应用程序。 SMART on FHIR 代理支持以下字段。

• patient
• encounter
• practitioner
• need_patient_banner
• smart_style_url

这些字段旨在向应用提供指导，而不会传达任何安全信息。 SMART on FHIR 应用程序可以忽略这些字段。

请注意，SMART on FHIR 应用启动器会在页面底部更新“启动 URL”信息。

选择“启动”以启动示例应用。

从 SMART on FHIR 代理迁移到 SMART on FHIR（增强版）

重要

SMART on FHIR 代理将于 2026 年 9 月停用，在该日期之前过渡到 SMART on FHIR（增强版）。 从 2026 年 9 月开始，当访问 FHIR 服务时，依赖 SMART on FHIR 代理的应用程序将报告出错。

与 SMART on FHIR 代理相比，SMART on FHIR（增强版）提供的功能更多。 SMART on FHIR（增强版）可被视为满足 SMART on FHIR 实施指南 (v 1.0.0) 和 §170.315(g)(10) 用于患者和人群服务标准的标准化 API 的要求。下表列出了 SMART on FHIR 代理与 SMART on FHIR（增强版）之间的差异。

功能	SMART on FHIR（增强版）	SMART on FHIR 代理
支持独立启动	是	否
支持 EHR 启动	是	是
支持范围限制	是	否
依赖第一方 Azure 产品	是，需要集成 Azure API 管理 (APIM) 等 Azure 产品	否
Microsoft 支持	支持 FHIR 服务。需要通过 GitHub 报告和监视开源示例支持	支持 FHIR 服务

迁移步骤

• 步骤 1：设置 FHIR SMART 用户角色。按照管理用户：向用户分配角色部分下列出的步骤操作。 添加到 SMART 用户角色的任何用户都可访问 FHIR 服务，前提是他们的请求符合 SMART on FHIR 实现指南。
• 步骤 2：部署 Azure 健康数据和 AI OSS 示例下的 SMART on FHIR 示例
• 步骤 3：将 FHIR 服务 URL 的终结点更新为“{{BASEURL_FROM_APIM}}/smart”。
• 步骤 4：取消选中 FHIR 服务的“身份验证”边栏选项卡下的 SMART on FHIR 代理设置。

如有疑问，可在 Microsoft Q&A 中获取来自社区专家的答案。 如需技术支持，还可创建支持请求。

后续步骤

现在你已了解如何启用 SMART on FHIR 功能，接下来请查看搜索示例页，详细了解如何使用搜索参数、修饰符和其他 FHIR 搜索方法进行搜索。

FHIR 搜索示例

注意

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