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

如何使用 Postman 将请求发送到 Azure 数字孪生 API

  • 项目

Postman 是一种 REST 测试工具，它在桌面和基于插件的 GUI 中提供关键 HTTP 请求功能。 你可用它来创建 HTTP 请求并将其提交到 Azure 数字孪生 REST API。 本文介绍如何配置 Postman REST 客户端以与 Azure 数字孪生 API 进行交互。 此信息特定于 Azure 数字孪生服务。

本文包含有关以下步骤的信息：

  1. 使用 Azure CLI 获取持有者令牌，你将使用该令牌在 Postman 中发出 API 请求。
  2. 设置 Postman 集合并配置 Postman REST 客户端以使用持有者令牌进行身份验证。 设置集合时，可以选择以下任一选项：
    1. 导入预生成的 Azure 数字孪生 API 请求集合。
    2. 从头开始创建自己的集合。
  3. 将请求添加到已配置的集合，并将其发送到 Azure 数字孪生 API。

Azure 数字孪生提供了两个可用的 API 集：数据平面和控制平面。 如需详细了解这些 API 集之间的差异，请参阅 Azure 数字孪生 API 和 SDK。 本文包含这两个 API 集的信息。

先决条件

若要继续使用 Postman 访问 Azure 数字孪生 API，需要设置 Azure 数字孪生实例并下载 Postman。 本部分的其余部分将指导你完成这些步骤。

设置 Azure 数字孪生实例

若要在本文中使用 Azure 数字孪生，你需要有一个 Azure 数字孪生实例，还需具备使用它所必需的权限。 如果你已设置了一个 Azure 数字孪生实例，则可以使用该实例并跳到下一部分。 如果没有，请按照设置实例和身份验证中的说明操作。 该说明中包含可帮助你验证是否已成功完成每个步骤的信息。

设置实例后，记下实例的主机名。 可以在 Azure 门户中找到该主机名。

下载 Postman

接下来，下载 Postman 客户端的桌面版本。

获取持有者令牌

现在，你已设置 Postman 和 Azure 数字孪生实例，接下来需要获取持有者令牌，Postman 请求可使用该令牌向 Azure 数字孪生 API 授权。

可通过多种方式获取此令牌。 本文使用 Azure CLI 登录到 Azure 帐户并获取令牌。

如果已在本地安装 Azure CLI，可在计算机上启动命令提示符来运行以下命令。 否则，可以在浏览器中打开 Azure Cloud Shell 窗口，并在其中运行命令。

  1. 首先，请通过运行以下命令来确保你已使用相应的凭据登录到 Azure：

    az login

  2. 接下来，使用 az account get-access-token 命令获取具有 Azure 数字孪生服务访问权限的持有者令牌。 在此命令中，传入 Azure 数字孪生服务终结点的资源 ID，以获取可访问 Azure 数字孪生资源的访问令牌。

    令牌的必需上下文取决于所使用的 API 集，因此使用以下选项卡在数据平面和控制平面 API 之间进行选择。

    若要获取用于数据平面 API 的令牌，请对令牌上下文使用以下静态值： 0b07f429-9f4b-4714-9392-cc5e8e80c8b0 此值为 Azure 数字孪生服务终结点的资源 ID。

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

    注意

    如果需要使用属于该实例不同 Microsoft Entra 租户的服务主体或用户帐户访问 Azure 数字孪生实例，则需要从 Azure 数字孪生实例的“主页”租户请求令牌。 有关此过程的详细信息，请参阅编写应用身份验证代码。

  3. 复制结果中 accessToken 的值并将其保存，以便在下一部分中使用。 此值是你将提供给 Postman 用于授权请求的令牌值。

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

提示

此令牌的有效期至少为五分钟，最长为 60 分钟。 如果为当前令牌分配的时间不足，则可以重复本部分中的步骤来获取新令牌。

接下来，设置 Postman 以使用此令牌向 Azure 数字孪生发出 API 请求。

关于 Postman 集合

Postman 中的请求保存在集合（请求组）中。 创建集合以对请求进行分组时，可以同时将通用设置应用于多个请求。 如果计划针对 Azure 数字孪生 API 创建多个请求，则常见设置可以大大简化授权，因为只需为整个集合配置一次这些详细信息。

使用 Azure 数字孪生时，可从导入所有 Azure 数字孪生请求的预生成集合开始。 如果要浏览 API 并想要使用请求示例快速设置项目，则可能需要导入此集合。

或者，还可选择从头开始，方法是创建自己的空集合并使用只调用所需 API 的各个请求来填充它。

以下部分对这两种方法进行了介绍。 本文余下部分的操作都是在本地 Postman 应用程序中进行的，所以请立即打开计算机上的 Postman 应用程序。

导入 Azure 数字孪生 API 集合

在 Postman 中开始使用 Azure 数字孪生的一种快速方法是导入 API 的预生成请求集合。 按照以下步骤导入包含示例请求数据的常用 Azure 数字孪生数据平面 API 请求的集合。

  1. 在 Postman 主窗口中，选择“Import”按钮。 Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. 在随后的“导入”窗口中，选择“链接”并输入以下 URL： https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json 然后选择“导入”以确认。

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

现在，可在 Postman 主视图的“Collections”选项卡中看见新导入的集合。

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

提示

若要为特定版本的 Azure 数字孪生 API（包括控制平面或数据平面）导入完整的 API 调用集，还可以将 Swagger 文件导入为集合。 有关控制平面和数据平面 API 的 Swagger 文件的链接，请参阅 Azure 数字孪生 API 和 SDK。

接下来，请继续阅读下一部分，了解如何将持有者令牌添加到集合进行授权并将其连接到 Azure 数字孪生实例。

配置授权

接下来，编辑创建的集合以配置一些访问详细信息。 突出显示已创建的集合，然后选择“ 查看更多操作 ”图标以显示操作选项。 选择“编辑” 。

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

按照以下步骤将持有者令牌添加到集合以进行授权。 使用在获取持有者令牌部分中收集的令牌值，以便将其用于集合中的所有 API 请求。

  1. 在集合的编辑对话框中，确保位于“Authorization”选项卡上。

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. 将类型设置为 OAuth 2.0 ，并将访问令牌粘贴到“访问令牌”框中。 必须为所使用的 API 类型使用正确的令牌，因为数据平面 API 与控制平面 API 有不同的令牌。 选择“保存”。

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    提示

    如果要将令牌与 Postman 云上的请求一起存储，并可能与他人共享令牌，可以选择启用令牌共享。

其他配置

可以通过设置集合提供的一些变量，帮助集合轻松连接到 Azure 数字孪生资源。 集合中的许多请求需要相同的值（如 Azure 数字孪生实例的主机名）时，可将该值存储在一个适用于集合中每个请求的变量中。 Azure 数字孪生集合附带可在集合级别设置的预先创建的变量。

  1. 还是在集合的编辑对话框中，移动到“Variables”选项卡。

  2. 使用下表设置集合中变量的值：

    变量 API 集 说明
    digitaltwins-hostname 数据平面 Azure 数字孪生实例的主机名。 可以在门户中实例的概述页上找到此值。
    subscriptionId 控制面板 Azure 订阅 ID。
    digitalTwinInstance 控制面板 Azure 数字孪生实例的名称。

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

  3. 如果集合中有额外变量，还应填充并保存这些值。

  4. 选择“保存”。

完成上述步骤后，集合的配置就完成了。 如果需要，可关闭集合的编辑选项卡。

探索请求

接下来，探索 Azure 数字孪生 API 集合中的请求。 可展开集合以查看预先创建的请求（按操作类别排序）。

不同请求需要有关实例及其数据的不同信息。 若要查看创建特定请求所需的所有信息，请在 Azure 数字孪生 REST API 参考文档中查找请求详细信息。

可使用以下步骤在 Postman 集合中编辑请求的详细信息：

  1. 从列表中选择请求以显示可编辑的详细信息。

  2. 示例集合中的大多数请求都预配置为运行，而无需进行任何进一步的更改。

  3. 以下屏幕截图显示了 DigitalTwinModels 添加 API。 在 “正文 ”选项卡上，可以看到定义要添加的新模型的 JSON 有效负载：

  4. 在“Params”选项卡中填写“Path Variables”下列出的变量的值。

    Screenshot of Postman. The collection is expanded to show the body tab of a request.

  5. 若要运行请求，请使用“ 发送 ”按钮。

还可以使用“添加单个请求”部分中所述的过程将自己的请求添加到集合。

创建自己的集合

也可以从头开始创建自己的集合，而不是导入 Azure 数字孪生 API 的现有集合。 然后，可参照 Azure 数字孪生 REST API 参考文档，使用各个请求填充集合。

创建 Postman 集合

  1. 若要创建集合，请在 Postman 主窗口中选择“新建”按钮。

    Screenshot of the main Postman window. The 'New' button is highlighted.

    选择 Collection 类型。

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  2. 此时会打开一个选项卡。 填写新集合的详细信息。 选择集合默认名称 (New Collection) 旁边的编辑图标将其替换为自己选择使用的名称。

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

接下来，转到下一部分，将持有者令牌添加到集合以进行授权。

配置授权

按照以下步骤将持有者令牌添加到集合以进行授权。 使用在获取持有者令牌部分中收集的令牌值，以便将其用于集合中的所有 API 请求。

  1. 还是在新集合的编辑对话框中，移动到“Authorization”选项卡。

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. 将“Type”设置为“OAuth 2.0”，将访问令牌粘贴到“Access Token”框中，然后选择“Save”。

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

完成上述步骤后，集合的配置就完成了。 你可以根据需要关闭新集合的编辑选项卡。

可在 Postman 主视图的“Collections”选项卡中看到新集合。

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

添加单个请求

现在集合已设置完毕，可将自己的请求添加到 Azure 数字孪生 API。

  1. 若要创建请求，请再次使用“New”按钮。

    Screenshot of the main Postman window. The 'New' button is highlighted.

    选择 Request 类型。

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  2. 此操作会打开“SAVE REQUEST”窗口，你可以在其中输入请求的名称，为其提供可选说明，然后选择其所属的集合。 填充详细信息，并将请求保存到之前创建的集合。

Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

你现在可以查看集合下的请求，并选择它来提取其可编辑的详细信息。

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

设置请求详细信息

若要向 Azure 数字孪生 API 之一发出 Postman 请求，需要提供 API 的 URL 以及详细信息所需的内容。 可以在 Azure 数字孪生 REST API 参考文档中找到此信息。

若要继续执行示例查询，本文将使用 Azure 数字孪生查询 API 查询实例中的所有数字孪生。

  1. 获取参考文档中的请求 URL 和类型。 对于查询 API，当前为 POSThttps://digitaltwins-host-name/query?api-version=2020-10-31。

  2. 在 Postman 中，设置请求的类型并输入请求 URL，并根据需要填充 URL 中的占位符。 使用“先决条件”部分中的实例主机名。

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  3. 检查在“参数”选项卡中为请求显示的参数是否与参考文档中所述的参数匹配。 对于 Postman 中的此请求，当在上一步中输入请求 URL 时，将自动填充 api-version 参数。 对于查询 API，这是所需的唯一参数，因此已完成此步骤。

  4. 在“Authorization”选项卡中，将“Type”设置为“Inherit auth from parent”。 这表明此请求将使用之前为整个集合设置的授权。

  5. 检查在“标头”选项卡中为请求显示的标头是否与参考文档中所述的标头匹配。 对于此请求，已自动填充多个标头。 对于查询 API，无需任何标头选项，因此已完成此步骤。

  6. 检查在“正文”选项卡中为请求显示的正文是否与参考文档中所述的需求匹配。 对于查询 API，需要 JSON 正文来提供查询文本。 下面是此请求的示例正文，它将查询实例中的所有数字孪生体：

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of 'SELECT * FROM DIGITALTWINS'.

    有关创建 Azure 数字孪生查询的详细信息，请参阅查询孪生体图形。

  7. 检查参考文档中是否存在请求类型可能需要的任何其他字段。 对于查询 API，现已满足 Postman 请求中的所有要求，因此已完成此步骤。

  8. 使用“发送”按钮发送已完成的请求。 Screenshot of Postman showing the details of the new request. The Send button is highlighted.

发送请求后，响应详细信息将在 Postman 窗口中的请求下显示。 可以查看响应的状态代码和任何正文文本。

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

还可以将响应与参考文档中给定的预期响应数据进行比较，以验证结果或了解有关出现的任何错误的详细信息。

后续步骤

若要详细了解数字孪生 API，请阅读 Azure 数字孪生 API 和 SDK，或查看 REST API 的参考文档。