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

在本教程中，你将使用 HTTP 设置并使用 Postman 针对 Azure 通信服务发出请求。 在本教程结束时，你将成功使用通信服务和 Postman 发送短信服务 (SMS) 消息。 然后，可以使用 Postman 浏览通信服务中的其他 API。

本教程中，您将学习如何：

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

Prerequisites

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

下载并安装 Postman

Postman 是一个桌面应用程序，能够针对任何 HTTP API 发出 API 请求。 Postman 通常用于测试和探索 API。 在本教程中，将从 Postman 网站下载最新的桌面版本。 Postman 具有适用于 Windows、Mac 和 Linux 的版本，因此请下载适用于作系统的版本。

下载完成后，打开应用程序。 开始屏幕要求你登录或创建 Postman 帐户。 创建帐户是可选的，可以通过选择 跳过并转到应用 来跳过。 创建帐户会将 API 请求设置保存到 Postman。 然后，您可以在其他计算机上获取请求。

创建帐户或跳过步骤后，现在会看到 Postman 的主屏幕。

创建和配置 Postman 集合

Postman这个工具可以用多种方式来组织请求。 在本教程中，你将创建 Postman 集合。 若要执行此任务，请在应用程序的左侧选择“ 集合”。

选择“ 创建新集合 ”以开始创建集合的过程。 将在 Postman 的中心区域中打开一个新选项卡，在其中命名集合。 在这里，该集合名为 Azure 通信服务。

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

添加集合变量

若要处理身份验证并简化请求，请在新创建的通信服务集合中指定两个集合变量。 这些变量可用于集合中的所有请求。 若要开始创建变量，请选择“ 变量 ”选项卡。

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

• key：此变量应是 Azure 门户中通信服务 密钥 页中的密钥之一。 示例为 oW...A==。
• 终结点：此变量应是 密钥 页中的通信服务终结点。 确保移除尾随的左斜线。 示例为 https://contoso.communication.azure.com。

在“ 变量 ”选项卡上，在 “初始值 ”列中输入这些值。 选择右上角的“全部保留”。 正确配置后，Postman 窗格应如下图所示。

显示正确设置了通信服务集合变量的 Postman 的屏幕截图。

若要了解有关变量的详细信息，请参阅 Postman 文档。

创建预请求脚本

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

在集合中创建此脚本，使其在集合中的任何请求上运行。 若要执行此步骤，请在“ 集合 ”选项卡上，选择 “预请求脚本”。

现在，通过在文本区域中输入它来创建预请求脚本。 在完整代码编辑器（如 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 by 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 主机标头的值。 在处理此脚本之前，不会设置 Host 标头。

// 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, by 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 by 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, by 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
});

在 “预请求脚本 ”选项卡上的文本区域中输入或粘贴此最终脚本。

输入后，选择 Ctrl+S 或选择 “保存” 将脚本保存到集合。

在 Postman 中创建请求

设置所有内容后，即可在 Postman 中创建通信服务请求。 若要开始，请选择通信服务集合旁边的加号（+）。

在 Postman 中为请求创建了一个新选项卡，现在需要对其进行配置。 针对短信发送 API 发出请求，因此请务必参考 此 API 的文档以获取帮助。 让我们配置 Postman 请求。

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

在请求的 “正文 ”选项卡上，选择 原始。 在右侧的下拉列表中，选择 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对于该值，需要在通信服务门户中获取电话号码，如前所述。 在没有任何空格和国家/地区代码前缀的情况下输入它。 示例为 +15555551234。 你的 message 可以是你想发送的任何内容，而 Hello from Azure Communication Services 是一个不错的示例。 该值 to 应是你有权访问的电话，以便你能够接收短信。 使用自己的移动电话是个好主意。

将此请求保存到之前创建的通信服务集合中。 此步骤可确保程序能拾取已创建的变量和预请求脚本。 选择请求区域的右上角的 “保存 ”。

出现的对话框询问您希望如何命名该请求以及希望将其保存在哪里。 你可以将其命名为任何你想要的名称，但请确保在对话框的下半部分选择你的通信服务集合。

发送请求

设置所有内容后，即可发送请求并在手机上收到短信。 若要执行此步骤，请确保已选择请求，然后选择“ 发送”。

如果一切正常，则会看到来自通信服务的响应，这是 202 状态代码。

to 值中包含您提供的号码的移动电话也收到了短信。 你现在有一个功能 Postman 配置，可以与通信服务通信并发送短信。

相关内容

• 探索 Azure 通信服务 API
• 详细了解身份验证
• 了解有关 Postman 的详细信息
• 向应用中添加聊天
• 创建用户访问令牌
• 了解客户端和服务器体系结构
• 了解身份验证