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

教程：使用 Postman 签署和发出请求

  • 项目

在本教程中，我们将设置并使用 Postman 通过 HTTP 对 Azure 通信服务发出请求。 在本教程结束时，你将会成功地使用通信服务和 Postman 发送短信。 然后，将能够使用 Postman 探索 Azure 通信服务中的其他 API。

在本教程中，我们将执行以下操作：

  • 下载 Postman
  • 设置 Postman 以便对 HTTP 请求进行签名
  • 对通信服务短信 API 发出请求以发送消息。

必备条件

  • 具有活动订阅的 Azure 帐户。 有关详细信息，请参阅创建免费账户。 免费帐户为你提供了价值 200 美元的 Azure 赠金，你可用它来试用任何服务组合。
  • 活动的通信服务资源和连接字符串。 了解如何创建通信服务资源。
  • 可以发送短信的 Azure 通信服务电话号码。请参阅获取电话号码获取一个电话号码。

下载并安装 Postman

Postman 是一个桌面应用程序，能够对任何 HTTP API 发出 API 请求。 它通常用于测试和探索 API。 我们将从 Postman 网站下载最新的桌面版。 Postman 有适用于 Windows、Mac 和 Linux 的版本，因此请下载适合你的操作系统的版本。 下载后打开该应用程序。 此时会显示一个开始屏幕，其中要求你登录或创建 Postman 帐户。 创建帐户是可选操作，可以单击“跳过并转到应用”链接跳过该操作。 创建帐户会将 API 请求设置保存到 Postman，这样，你就可以在其他计算机上选取请求。

Postman 的“开始”屏幕，其中显示了用于创建帐户或跳过此创建操作并转到应用的功能。

创建帐户或者跳过创建帐户的操作后，应会看到 Postman 的主窗口。

创建并配置 Postman 集合

Postman 可通过多种方式来组织请求。 在本教程中， 我们将创建一个 Postman 集合。 为此，请选择应用程序左侧的“集合”按钮：

Postman 的主屏幕，其中突出显示了“集合”选项卡。

选择后，单击“创建新集合”启动集合创建过程。 Postman 的中心区域将打开一个新选项卡。 为集合指定任意所需名称。 此处，集合名为“Azure 通信服务”：

已打开通信服务集合且突出显示集合名称的 Postman。

创建并命名集合后，即可开始对其进行配置。

添加集合变量

为了更轻松地处理身份验证和发出请求，我们将在新建的通信服务集合中指定两个集合变量。 这些变量可用于通信服务集合中的所有请求。 若要开始创建变量，请访问集合的“变量”选项卡。

显示通信服务集合的“变量”选项卡的 Postman。

在集合选项卡上创建两个变量：

  • key - 此变量应是 Azure 门户中的 Azure 通信服务密钥页提供的一个密钥。 例如 oW...A==。
  • endpoint - 此变量应是该密钥页中提供的 Azure 通信服务终结点。 确保删除尾部斜杠。 例如 https://contoso.communication.azure.com。

在“变量”屏幕的“初始值”列中输入这些值。 输入后，按下紧靠在表格右上方的“全部保存”按钮。 正确配置后，Postman 屏幕应如下所示：

正确设置了通信服务集合的变量的 Postman。

可以阅读有关变量的 Postman 文档来详细了解变量。

创建请求前脚本

下一步是在 Postman 中创建请求前脚本。 请求前脚本是在 Postman 中每个请求之前运行的脚本，它可以代表你修改或改变请求参数。 我们将使用此脚本来为 HTTP 请求签名，使请求可由 Azure 通信服务授权。 有关签名要求的详细信息，可以阅读有关身份验证的指南。

我们将在“集合”中创建此脚本，使它针对集合中的任何请求运行。 为此，请在“集合”选项卡中单击“请求前脚本”子选项卡。

选择了通信服务集合的“预请求脚本”子选项卡的 Postman。

在此子选项卡上，可以创建一个请求前脚本，只需将此脚本输入到下面的文本区域中即可。 在 Visual Studio Code 等完整代码编辑器中编写此脚本会更方便，可以在编写完成后，将此脚本粘贴到文本区域中。 本教程将会解释该脚本的每个组成部分。 如果你只是想要将脚本复制到 Postman 并开始运行，可以尽管跳转到本文末尾。 让我们开始编写脚本。

编写请求前脚本

我们要做的第一件事是创建一个协调世界时 (UTC) 字符串，并将其添加到“Date”HTTP 头。 我们还要将此字符串存储在一个变量中，以便稍后在签名时使用：

// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});

接下来，我们使用 SHA 256 对请求正文进行哈希处理，然后将其放到 x-ms-content-sha256 头中。 Postman 包含了一些用于全局哈希处理和签名的标准库，因此我们无需安装或请求它们：

// Hash the request body using SHA256 and encode it as Base64
const hashedBodyStr = CryptoJS.SHA256(pm.request.body.raw).toString(CryptoJS.enc.Base64)
// And add that to the header x-ms-content-sha256
pm.request.headers.upsert({
    key:'x-ms-content-sha256',
    value: hashedBodyStr
});

现在，我们将使用前面指定的终结点变量来辨别 HTTP 主机头的值。 之所以需要这样做，是因为只有在处理此脚本之后，才会设置主机头：

// Get our previously specified endpoint variable
const endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" value
const hostStr = endpoint.replace('https://','');

创建此信息后，我们现在可以创建字符串用于对 HTTP 请求进行签名，此字符串由前面创建的多个值组成：

// This gets the part of our URL that is after the endpoint, for example in https://contoso.communication.azure.com/sms, it will get '/sms'
const url = pm.request.url.toString().replace('{{endpoint}}','');

// Construct our string which we'll sign, using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;

最后，我们需要使用通信服务密钥对此字符串进行签名，然后将此字符串添加到请求的 Authorization 头中：

// Decode our access key from previously created variables, into bytes from base64.
const key = CryptoJS.enc.Base64.parse(pm.variables.get('key'));
// Sign our previously calculated string with HMAC 256 and our key. Convert it to Base64.
const signature = CryptoJS.HmacSHA256(stringToSign, key).toString(CryptoJS.enc.Base64);

// Add our final signature in Base64 to the authorization header of the request.
pm.request.headers.upsert({
    key:'Authorization',
    value: "HMAC-SHA256 SignedHeaders=date;host;x-ms-content-sha256&Signature=" + signature
});

最终的请求前脚本

最终的请求前脚本应如下所示：

// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});

// Hash the request body using SHA256 and encode it as Base64
const hashedBodyStr = CryptoJS.SHA256(pm.request.body.raw).toString(CryptoJS.enc.Base64)
// And add that to the header x-ms-content-sha256
pm.request.headers.upsert({
    key:'x-ms-content-sha256',
    value: hashedBodyStr
});

// Get our previously specified endpoint variable
const endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" value
const hostStr = endpoint.replace('https://','');

// This gets the part of our URL that is after the endpoint, for example in https://contoso.communication.azure.com/sms, it will get '/sms'
const url = pm.request.url.toString().replace('{{endpoint}}','');

// Construct our string which we'll sign, using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;

// Decode our access key from previously created variables, into bytes from base64.
const key = CryptoJS.enc.Base64.parse(pm.variables.get('key'));
// Sign our previously calculated string with HMAC 256 and our key. Convert it to Base64.
const signature = CryptoJS.HmacSHA256(stringToSign, key).toString(CryptoJS.enc.Base64);

// Add our final signature in Base64 to the authorization header of the request.
pm.request.headers.upsert({
    key:'Authorization',
    value: "HMAC-SHA256 SignedHeaders=date;host;x-ms-content-sha256&Signature=" + signature
});

将此最终脚本输入或粘贴到“请求前脚本”选项卡中的文本区域内：

已输入 Azure 通信服务集合的预请求脚本的 Postman。

输入后，按 CTRL + S 或按“保存”按钮将脚本保存到集合中。

Postman 的“保存请求前脚本”按钮。

在 Postman 中创建请求

完成所有设置后，我们便可以在 Postman 中创建通信服务请求了。 首先，单击通信服务集合旁边的加号 (+) 图标：

Postman 中的加号按钮。

这会在 Postman 中为请求创建一个新选项卡。 创建请求后，需要对其进行配置。 我们将对“短信发送”API 发出请求，因此请务必参阅有关此 API 的文档以获取帮助。 让我们配置 Postman 的请求。

首先将请求类型设置为 POST，并在请求 URL 字段中输入 {{endpoint}}/sms?api-version=2021-03-07。 此 URL 使用我们在前面创建的 endpoint 变量自动将请求发送到通信服务资源。

一个 Postman 请求，其类型设置为 POST，URL 已正确设置。

现在，选择请求的“正文”选项卡，然后将下面的单选按钮更改为“原始”。 右侧有一个显示“文本”的下拉列表，请将其更改为“JSON”：

将请求正文设置为“原始”和“JSON”

这会将请求配置为发送和接收 JSON 格式的信息。

在下面的文本区域中，需要输入请求正文，其格式应如下所示：

{
    "from":"<Your Azure Communication Services Telephone Number>",
    "message":"<The message you'd like to send>",
    "smsRecipients": [
        {
            "to":"<The number you'd like to send the message to>"
        }
    ]
}

对于“from”值，需要根据前面所述在 Azure 通信服务门户中获取一个电话号码。 输入的电话号码不能包含空格，需要加上国家/地区代码作为前缀。 例如：+15555551234。 “message”可以是要发送的任何内容，Hello from Azure Communication Services 就是一个很好的例子。 “to”值应该是你有权使用的、能够接收短信的电话号码。 建议使用你自己的手机。

输入后，需将此请求保存到前面创建的通信服务集合中。 这可以确保该请求选取前面创建的变量和请求前脚本。 为此，请单击请求区域右上方的“保存”按钮。

Postman 请求的“保存”按钮。

此时会显示一个对话框窗口，其中询问要为请求指定哪个名称，以及要将它保存到哪个位置。 可为其指定任意名称，但请确保在对话框的下半部分选择你的通信服务集合：

选择了通信服务集合的 Postman“保存请求”对话框。

发送请求

完成所有设置后，应该可以发送请求并在手机上接收短信。 为此，请确保创建的请求已选中，然后按下右侧的“发送”按钮：

一个 Postman 请求，已突出显示“发送”按钮。

如果一切正常，现在应会看到来自通信服务的响应，其状态代码会是 202：

一个 Postman 请求，该请求已成功发送，其状态代码为 202。

拥有你在“to”值中提供的号码的手机应该也收到了短信。 现在你就有了一个有效的 Postman 配置，可以与 Azure 通信服务进行通信并发送短信了。

后续步骤

探索 Azure 通信服务 API详细了解身份验证详细了解 Postman

你可能还需要：