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

SMART on FHIR

可替代的医学应用和可复用技术 (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 订阅，以创建资源并添加角色分配。

使用 Azure Health Data Services 示例的 SMART on FHIR（SMART on FHIR [增强版]）

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

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

注意

SMART on FHIR 实现指南定义了对设有范围的 FHIR 资源类型的访问权限。 这些范围会影响应用程序可能对 FHIR 资源拥有的访问权限。 具有 SMART 用户角色的用户有权在 FHIR 服务上执行读取 API 交互。 SMART 用户角色不授予对 FHIR 服务的写入访问权限。

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

单击此链接，以导航到 Azure Health Data 和 AI 示例开放源代码解决方案。 本文档中列出的步骤支持将 FHIR 服务器与其他 Azure 服务（例如 APIM、Azure Functions 等）集成。

注意

示例包括开源代码；在使用它之前，应查看 GitHub 上的信息和许可条款。 它们不是 Azure Health Data Service 的一部分，不受 Microsoft 支持部门支持。 这些示例用于演示如何将 Azure Health Data Services (AHDS) 和其他开放源代码工具一起使用，以通过将 Microsoft Entra ID 用作标识提供者工作流来展示 §170.315(g)(10) 适用于患者和人群服务标准的标准化 API 合规性。

SMART on FHIR 代理

单击可展开！

注意

这是使用前面提到的 AHDS 示例的 SMART on FHIR（增强型）的另一个选项。 建议你采用 SMART on 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 的要求。

步骤 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 相同。 FHIR 服务的标准配置使用 https://fhir.azurehealthcareapis.com 的 Audience 值。 但是，你也可以设置与 FHIR 服务的特定 URL 匹配的值（例如 https://MYFHIRAPI.fhir.azurehealthcareapis.com）。 使用 SMART on FHIR 代理时必须这样做。

若要在“身份验证”设置中为 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.fhir.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：获取测试患者

若要测试 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.fhir.azurehealthcareapis.com",
    "ClientId": "APP-ID",
    "DefaultSmartAppUrl": "/sampleapp/launch.html"
}

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

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

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

dotnet run

步骤 5：测试 SMART on FHIR 代理

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

输入“患者”、“就诊”或“医师”信息时，会发现“启动上下文”已更新。 使用 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 许可使用。