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

使用 Postman 访问 FHIR 服务

项目
10/28/2024

本文介绍使用 Postman 访问 Azure Health Data Services 中的 FHIR® 服务的步骤。

先决条件

Azure 中部署的 FHIR 服务。有关详细信息，请参阅部署 FHIR 服务。
已本地安装 Postman。有关详细信息，请参阅 Postman 入门。
FHIR 服务上角色分配的用户访问管理员角色。

设置步骤

若要从 Postman 应用程序访问 FHIR 服务 ，请查看以下步骤：

在 Microsoft Entra ID 中注册客户端应用程序（应用注册）。
在 FHIR 服务下分配 FHIR 数据参与者角色。
设置 Postman - 创建工作区、集合和环境

在 Microsoft Entra ID 中注册客户端应用程序

在 Azure 门户中，选择“Microsoft Entra ID”磁贴。
在“管理”部分下，选择“应用注册”。
选择“+ 新建注册”。
输入应用注册的名称。在支持的帐户类型下，请选择“仅限此组织目录中的帐户”。选择“注册”。

应用程序 ID（客户端 ID）

注册新的应用程序后，可以在“概览”部分中找到应用程序（客户端）ID 和目录（租户）ID。 记下这些值供以后使用，因为配置 Postman 环境时需要这些值。

身份验证设置：保密与公共

选择“身份验证”以查看设置。 “允许公共客户端流”的默认值为“否”。
如果保留此默认值，则应用程序注册是“保密客户端应用程序”，并且需要证书或机密。
如果在高级设置中将“允许公共客户端流”选项的默认值更改为“是”，则应用程序注册是“公共客户端应用程序”，且不需要证书或机密。
如果要在不想存储任何机密的移动应用或 JavaScript 应用中使用客户端应用程序，则将值设置为“是”非常有用。
对于需要重定向 URL 的工具，请选择“添加平台”来配置平台。
对于 Postman，请选择“移动和桌面应用程序”。在“自定义重定向 URI”部分中输入“https://www.getpostman.com/oauth2/callback"”。选择“配置”按钮以保存设置。

证书和密码

单击“证书和机密”。单击“+ 新客户端密码”。

在“添加客户端密码”下，在“说明”字段中输入机密的名称。本指南会将机密过期设置为 6 个月。单击“添加” 。

请务必保存机密值，而不是机密 ID。

注意

尝试使用 Postman 或 REST 客户端等工具获取 FHIR 服务的访问令牌时，请使用 grant_type of client_credentials。

在 FHIR 服务中分配 FHIR 数据参与者角色

本部分介绍为 Azure Health Data Services 中的 FHIR® 服务将 FHIR 数据参与者角色分配给已注册的应用程序的步骤。

在 Azure 门户中，导航到你的 FHIR 服务。
在左侧菜单中，选择“访问控制(IAM)”边栏选项卡。单击“+ 添加”，然后选择“添加角色分配”。如果添加角色分配的选项不可用，请让你的 Azure 管理员分配你执行此步骤的权限。
在“角色”选项卡下的“添加”角色分配中，向下滚动列表并选择“FHIR 数据参与者”。然后单击“下一步”。
在“成员”选项卡下，单击“+选择成员”。在右侧的“选择”字段中键入你的 Postman 服务客户端应用的名称。选择应用。
同样，在“选择”中键入你的用户名。选择你的用户，将它和应用注册一起添加到列表，然后单击“选择”。然后单击“下一步”。
在“查看 + 分配”选项卡下单击“查看 + 分配”。

设置 Postman - 创建工作区、集合和环境。

如果不熟悉 Postman，请按照以下步骤创建工作区、集合和环境。

Postman 引入了工作区概念，让你和你的团队能够共享 API、集合、环境和其他组件。可以使用默认的“我的工作区”或“团队工作区”，或者为你或你的团队创建新的工作区。

接下来，创建一个新集合，可在其中对所有相关 REST API 请求进行分组。在工作区中，选择“创建集合”。可以保留“新集合”这一默认名称，或者将其重命名。将自动保存更改。

还可以导入和导出 Postman 集合。有关详细信息，请参阅 Postman 文档。

创建或更新环境变量

尽管可以在请求中使用完整 URL，但建议将 URL 和其他数据存储在变量中。

若要访问 FHIR 服务，需要创建或更新以下变量：

变量	描述	说明
tenantid	部署 FHIR 服务的 Azure 租户	可在应用程序注册概述中找到
subid	部署 FHIR 服务的 Azure 订阅	可在 FHIR 服务概述上找到
clientid	应用程序客户端注册 ID
clientsecret	应用程序客户端注册机密
fhirurl	FHIR 服务完整 URL（例如 `https://xxx.azurehealthcareapis.com`）	可在 FHIR 服务概述上找到
bearerToken	将 Microsoft Entra 访问令牌存储在脚本中	留空

注意

确保在客户端应用程序注册中配置了重定向 URL https://www.getpostman.com/oauth2/callback。

获取功能语句

在 GET 请求中输入 {{fhirurl}}/metadata，然后选择 Send。应该会看到 FHIR 服务的功能语句。

获取 Microsoft Entra 访问令牌

选择服务主体或 Microsoft Entra 用户帐户获取 Microsoft Entra 访问令牌。

将服务主体与客户端凭证授权类型一起使用

FHIR 服务受 Microsoft Entra ID 保护。无法禁用默认身份验证。若要访问 FHIR 服务，首先需要获取 Microsoft Entra 访问令牌。有关详细信息，请参阅 Microsoft 标识平台访问令牌。

创建新的 POST 请求：

输入请求头：https://login.microsoftonline.com/{{tenantid}}/oauth2/token
选择“正文”选项卡，然后选择“x-www-form-urlencoded”。在“密钥和值”部分中输入以下值：
- grant_type：Client_Credentials
- client_id：{{clientid}}
- client_secret：{{clientsecret}}
- resource：{{fhirurl}}

注意

如果 FHIR 服务受众参数未映射到 FHIR 服务终结点 URL，资源参数值应映射到 FHIR 服务的“身份验证”窗格上的受众值。

选择“测试”选项卡，然后在文本部分中输入 pm.environment.set("bearerToken", pm.response.json().access_token);。若要使值可用于集合，请使用 pm.collectionVariables.set 方法。有关 set 方法及其范围级别的详细信息，请参阅在脚本中使用变量。
选择保存，保存这些设置。
选择Send。应该会看到包含 Microsoft Entra 访问令牌的响应，该令牌自动保存到变量 bearerToken 中。然后，可以在所有 FHIR 服务 API 请求中使用该令牌。

可以使用联机工具（如 https://jwt.ms）检查访问令牌。选择“声明”选项卡以查看令牌中每个声明的详细说明。

使用具有授权代码授权类型的用户帐户

可以使用 Microsoft Entra 帐户凭据并按照列出的步骤获取 Microsoft Entra 访问令牌。

验证你是否是具有所需访问权限的 Microsoft Entra 租户的成员。
确保在客户端应用程序注册中为 Web 平台配置了重定向 URL https://oauth.pstmn.io/v1/callback。
在“API 权限”下的客户端应用程序注册中，从组织使用的 API 中添加 Azure Healthcare APIS 的 User_Impersonation 委派权限。

在 Postman 中，选择集合或特定 REST 调用的“授权”选项卡，选择 OAuth 2.0 作为类型，然后在“配置新令牌”部分设置以下值：
- 回调 URL：https://oauth.pstmn.io/v1/callback
- 身份验证 URL：https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/authorize
- 访问令牌 URL：https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/token
- 客户端 ID：应用程序客户端注册 ID
- 客户端密码：应用程序客户端注册机密
- 范围：{{fhirurl}}/.default
- 客户端身份验证：在正文中发送客户端凭据

选择页面底部的“获取新的访问令牌”。
提供用户凭据进行登录。
收到令牌后，选择“使用令牌”。
确保令牌位于 REST 调用的授权标头中。

使用联机工具（如 https://jwt.ms）检查访问令牌。选择“声明”选项卡以查看令牌中每个声明的详细说明。

连接到 FHIR 服务器

打开 Postman，选择要使用的工作区、集合和环境。选择 + 图标以创建新的请求。

若要对 FHIR 服务执行运行状况检查，请在 GET 请求中输入 {{fhirurl}}/health/check，然后选择“发送”。应该能够看到 Status of FHIR service - HTTP Status 代码响应，响应中显示 200 且 OverallStatus 为“运行正常”，这表示运行状况检查成功。

获取 FHIR 资源

获取 Microsoft Entra 访问令牌后，可以访问 FHIR 数据。在新的 GET 请求中，输入 {{fhirurl}}/Patient。

选择“持有者令牌”作为授权类型。在“令牌”部分输入 {{bearerToken}}。选择“发送”。作为响应，你应该会在 FHIR 资源中看到患者列表。

创建或更新 FHIR 资源

获取 Microsoft Entra 访问令牌后，可以创建或更新 FHIR 数据。例如，可以创建新的患者或更新现有患者。

创建新请求，将方法更改为 Post，并在请求部分输入值。

{{fhirurl}}/Patient

选择“持有者令牌”作为授权类型。在“令牌”部分输入 {{bearerToken}}。选择“正文”选项卡。选择“原始”选项，选择 JSON 作为正文文本格式。将以下文本复制粘贴到正文部分。

{
    "resourceType": "Patient",
    "active": true,
    "name": [
        {
            "use": "official",
            "family": "Kirk",
            "given": [
                "James",
                "Tiberious"
            ]
        },
        {
            "use": "usual",
            "given": [
                "Jim"
            ]
        }
    ],
    "gender": "male",
    "birthDate": "1960-12-25"
}

选择Send。 JSON 响应中应该会显示一名新患者。

导出 FHIR 数据

获取 Microsoft Entra 访问令牌后，可以将 FHIR 数据导出到 Azure 存储帐户。

若要配置导出设置并创建 Data Lake Storage Gen2 帐户，请参阅配置导出设置。

创建新的 GET 请求：{{fhirurl}}/$export?_container=export

选择“持有者令牌”作为授权类型。在“令牌”部分输入 {{bearerToken}}。选择“标头”来添加两个新标头：

接受：application/fhir+json
首选：respond-async

选择“发送”。应该会注意到 202 Accepted 响应。选择响应的“标头”选项卡，并记下 Content-Location 中的值。可以使用该值查询导出作业状态。

后续步骤

Postman 示例查询的初始者集合

注意

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

通过