教學課程：使用 Postman 簽署並提出要求

發行項
04/28/2024

在本教學課程中，我們將設定並使用 Postman，以對使用 HTTP 的 Azure 通訊服務提出要求。在本教學課程結束時，您將成功使用通訊服務和 Postman 傳送了簡訊。然後，您將能夠使用 Postman 來探索 Azure 通訊服務內的其他 API。

在本教學課程中，我們將：

下載 Postman
設定 Postman 以簽署 HTTP 要求
對通訊服務 SMS API 提出要求以傳送訊息。

必要條件

具有有效訂用帳戶的 Azure 帳戶。如需詳細資訊，請參閱免費建立帳戶。免費帳戶提供您價值 200 USD 的 Azure 點數，讓您可以試用各種服務組合。
作用中的 Azure 通訊服務資源和連接字串。了解如何建立通訊服務資源。
可以傳送簡訊的 Azure 通訊服務電話號碼，請參閱取得電話號碼，以取得電話號碼。

下載並安裝 Postman

Postman 是一種桌面應用程式，能夠針對任何 HTTP API 提出 API 要求。通常用於測試和探索 API。我們將從 Postman 網站下載最新的桌面版本。 Postman 具有適用於 Windows、Mac 和 Linux 的版本，因此請下載適合您作業系統的版本。下載後，請開啟應用程式。此時將呈現開始畫面，要求您登入或建立 Postman 帳戶。建立帳戶是選擇性的動作，您可以按一下 [略過並移至應用程式] 連結來略過此動作。建立帳戶會將您的 API 要求設定儲存至 Postman，然後可讓您在其他電腦上挑選您的要求。

Postman's Start screen showing the ability to create an account or to skip and go to the app.

一旦建立了帳戶或略過了建立帳戶，您現在應該就會看到 Postman 的主視窗。

建立並設定 Postman 集合

Postman 可以透過許多方式組織要求。基於本教學課程的目的。我們將要建立 Postman 集合。若要這樣做，請選取應用程式左側的集合按鈕：

Postman's main screen with the Collections tab highlighted.

一旦選取，請按一下 [建立新的集合]，以啟動集合建立流程。新的索引標籤將會在 Postman 的中心區域開啟。將集合命名為您喜歡的任何名稱。在這裡，集合命名為 "Azure Communication Services"：

Postman with a Communication Services Collection opened and the name of the collection highlighted.

一旦建立並命名了您的集合，您就準備好對其進行設定。

新增集合變數

為了處理驗證，並更輕鬆地提出要求，我們將在新建立的通訊服務集合內指定兩個集合變數。這些變數可供通訊服務集合內的所有要求使用。若要開始建立變數，請瀏覽集合的變數索引標籤。

Postman with a Communication Services Collection's Variables Tab.

一旦在集合索引標籤上，請建立兩個變數：

key - 此變數應該是 Azure 入口網站內 Azure 通訊服務金鑰頁面的其中一個金鑰。例如： oW...A== 。
endpoint - 此變數應該是來自金鑰頁面的 Azure 通訊服務端點。 確定您移除結尾斜線。例如： https://contoso.communication.azure.com 。

將這些值輸入至變數畫面的 [初始值] 資料行中。一旦輸入，請按右邊資料表正上方的 [全部保存] 按鈕。正確設定後，Postman 畫面看起來應該像這樣：

Postman with a Communication Services Collection's variables set up correctly.

您可以閱讀 Postman 有關變數的文件來深入了解變數。

建立預先要求指令碼

下一個步驟是在 Postman 內建立預先要求指令碼。預先要求指令碼是在 Postman 中每個要求之前執行的指令碼，其可以代表您修改或變更要求參數。我們將使用此指令碼來簽署 HTTP 要求，以便 Azure 通訊服務可以授權這些要求。如需簽署需求的詳細資訊，您可以閱讀我們的驗證指南。

我們將在集合內建立此指令碼，以便其可在集合內的任何要求上執行。若要這樣做，請在集合索引標籤內按一下 [預先要求指令碼] 子索引標籤。

Postman with a Communication Services Collection's pre-request Script Sub-Tab Selected.

在這個子索引標籤上，您可以將預先要求指令碼輸入至下列文字區域來建立此指令碼。在完整程式碼編輯器 (例如 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
});

將此最終指令碼輸入或貼入至 [預先要求指令碼] 索引標籤內的文字區域：

Postman with an Azure Communication Services Collection's Pre-request script entered.

一旦輸入，請按 CTRL + S 或按儲存按鈕，這會將指令碼儲存至集合。

Postman's Save Pre-request script button.

在 Postman 中建立要求

現在一切都已設定完畢，我們準備好在 Postman 內建立通訊服務要求。若要開始，請按一下通訊服務集合旁邊的加號 (+) 圖示：

Postman's plus button.

這將會為 Postman 內我們的要求建立新的索引標籤。建立之後，我們需要對其進行設定。我們將針對 SMS 傳送 API 提出要求，因此請務必參閱此 API 的文件，以取得協助。讓我們設定 Postman 的要求。

首先將要求類型設定為 POST，並將 {{endpoint}}/sms?api-version=2021-03-07 輸入至要求 URL 欄位。此 URL 會使用我們先前建立的 endpoint 變數，自動將其傳送至您的通訊服務資源。

A Postman request, with the type set to POST and the URL set correctly.

現在選取要求的 [本文] 索引標籤，然後將下方的選項按鈕變更為 [原始]。右側有一個下拉式清單顯示「文字」，將其變更為 JSON：

Setting the request body to raw and 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>"
        }
    ]
}

針對「傳送者」值，您必須在 Azure 通訊服務入口網站中取得電話號碼，如先前所述。輸入時不要包含任何空格，並在前面加上您的國家/地區代碼。例如： +15555551234 。您的「訊息」可以是您想要傳送的任何內容，但 Hello from Azure Communication Services 是一個很好的範例。「接收者」值應該是您有權存取的手機，其可以接收簡訊。使用您自己的行動裝置是個好主意。

一旦輸入，我們就必須將此要求儲存到我們先前建立的通訊服務集合中。這將確保其會挑選我們先前建立的變數和預先要求指令碼。若要這樣做，請按一下要求區域右上方的 [儲存] 按鈕。

The save button for a Postman request.

這將會出現一個對話視窗，詢問您要如何稱呼要求，以及您要將其儲存在何處。您可以將其命名為您喜歡的任何名稱，但請確定您在對話方塊的下半部選取您的通訊服務集合：

The Postman save request dialog with the Communication Services collection selected.

傳送要求

現在一切都已設定完畢，您應該能夠傳送要求，並在手機上收到簡訊。若要這樣做，請確定已選取您建立的要求，然後按右邊的 [傳送] 按鈕：

A Postman request, with the Send button highlighted.

如果一切順利，您現在應該會看到來自通訊服務的回應，這應該是 202 狀態碼：

A Postman request, sent successfully with a 202 status code.

擁有您在「接收者」值中所提供號碼的行動電話也應該收到簡訊。您現在具有功能性 Postman 設定，可以與 Azure 通訊服務交談並傳送簡訊。

下一步

探索 Azure 通訊服務 API 深入了解驗證深入了解 Postman

您可能也想要：

共用方式為