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

使用 Postman 访问 FHIR 服务

项目
04/20/2024

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

先决条件

Azure 中部署的 FHIR 服务。有关详细信息，请参阅部署 FHIR 服务。
用于访问 FHIR 服务的已注册客户端应用程序。有关详细信息，请参阅在 Microsoft Entra ID 中注册服务客户端应用程序。
向客户端应用程序和用户帐户授予的 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 方法及其范围级别的详细信息，请参阅在脚本中使用变量。
选择保存，保存这些设置。
选择“发送”。应该会看到包含 Microsoft Entra 访问令牌的响应，该令牌自动保存到变量 bearerToken 中。然后，可以在所有 FHIR 服务 API 请求中使用该令牌。

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

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

可以使用 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"
}

选择“发送”。 JSON 响应中应该会显示一名新患者。

导出 FHIR 数据

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

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

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

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

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

后续步骤

Postman 示例查询的初始者集合

注意

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