Kurz: Podepisování a vytváření žádostí pomocí Nástroje Postman

V tomto kurzu nastavíte a použijete Nástroj Postman k vytvoření požadavku na službu Azure Communication Services pomocí protokolu HTTP. Na konci tohoto kurzu úspěšně odešlete zprávu sms (Short Message Service) pomocí komunikačních služeb a nástroje Postman. Pomocí nástroje Postman pak můžete prozkoumat další rozhraní API v komunikačních službách.

V tomto kurzu se naučíte:

• Stáhněte si Postmana.
• Nastavte Postman pro podepisování požadavků HTTP.
• Odešlete požadavek na rozhraní SMS API komunikačních služeb k odeslání zprávy.

Prerequisites

• Účet Azure s aktivním předplatným. Pokud nemáte předplatné Azure, můžete si vytvořit účet zdarma. Bezplatný účet poskytuje 200 USD v kreditech Azure a umožňuje vyzkoušet libovolnou kombinaci služeb.
• Aktivní prostředek Komunikační služby a připojovací řetězec. Pokud nemáte prostředek, viz Vytvoření prostředku komunikačních služeb.
• Telefonní číslo komunikační služby, které může posílat sms zprávy. Pokud chcete získat telefonní číslo, přečtěte si článek Získání telefonního čísla.

Stažení a instalace nástroje Postman

Postman je aplikace pro stolní počítače, která dokáže vytvářet požadavky na jakékoli rozhraní HTTP API. Postman se běžně používá k testování a zkoumání rozhraní API. V tomto kurzu si stáhnete nejnovější desktopovou verzi z webu Postman. Postman má verze pro Windows, Mac a Linux, takže si stáhněte verzi, která je vhodná pro váš operační systém.

Po dokončení stahování otevřete aplikaci. Na úvodní obrazovce se zobrazí žádost o přihlášení nebo vytvoření účtu Postman. Vytvoření účtu je volitelné a můžete ho přeskočit tak, že vyberete Přeskočit a přejdete do aplikace. Vytvoření účtu uloží nastavení API požadavků do Postman. Žádosti pak můžete vyzvednout na jiných počítačích.

Po vytvoření účtu nebo přeskočení tohoto kroku se teď zobrazí hlavní obrazovka Postmana.

Vytvoření a konfigurace kolekce Postman

Postman může žádosti uspořádat mnoha způsoby. Pro účely tohoto kurzu vytvoříte kolekci Postman. Chcete-li provést tuto úlohu, vyberte na levé straně aplikace kolekce.

Výběrem možnosti Vytvořit novou kolekci zahájíte proces vytváření kolekce. V centrální oblasti nástroje Postman se otevře nová karta, ve které pojmenujete kolekci. V této kolekci se jmenuje Azure Communication Services.

Jakmile kolekci vytvoříte a pojmenujete, můžete ji nakonfigurovat.

Přidání proměnných kolekce

Pro zjednodušení ověřování a snazší zadávání požadavků zadáte dvě proměnné kolekce v právě vytvořené kolekci Communication Services. Tyto proměnné jsou k dispozici pro všechny požadavky ve vaší kolekci. Pokud chcete začít vytvářet proměnné, vyberte kartu Proměnné .

Na kartě Kolekce vytvořte dvě proměnné:

• key: Tato proměnná by měla být jedním z vašich klíčů ze stránky Klíč komunikační služby na webu Azure Portal. Příklad: oW...A==.
• koncový bod: Tato proměnná by měla být koncovými body komunikačních služeb na stránce Klíč . Nezapomeňte odebrat koncové lomítko. Příklad: https://contoso.communication.azure.com.

Na kartě Proměnné zadejte tyto hodnoty do sloupce Počáteční hodnota . V pravém horním rohu vyberte Zachovat vše . Po správné konfiguraci by mělo podokno Postman vypadat přibližně jako na následujícím obrázku.

Další informace o proměnných najdete v dokumentaci k Nástroji Postman.

Vytvoření skriptu předběžného požadavku

Dalším krokem je vytvoření skriptu předžádosti v Postmanu. Skript předběžného požadavku se spustí před každým požadavkem v Nástroji Postman. Za vás může upravit nebo změnit parametry požadavku. Tento skript použijete k podepsání požadavků HTTP, aby je služba Communication Services mohl autorizovat. Další informace o požadavcích na podepisování najdete v našem průvodci ověřováním.

Tento skript vytvoříte v kolekci tak, aby běžel na libovolném požadavku v kolekci. Tento krok provedete tak, že na kartě Kolekce vyberete Skript předběžné žádosti.

Teď vytvoříte skript předběžného požadavku tak, že ho zadáte do textové oblasti. Tento krok může být jednodušší, pokud ho napíšete v úplném editoru kódu, jako je Visual Studio Code , než ho vložíte. Tento kurz vás provede jednotlivými částmi procesu skriptu. Pokud chcete zkopírovat skript do nástroje Postman, přejděte na konec a začněte. Začněme psát skript.

Napsání skriptu předběžného požadavku

Prvním krokem je vytvoření řetězce koordinovaného univerzálního času (UTC) a jeho přidání do hlavičky Date HTTP. Uložte tento řetězec do proměnné, abyste ho později použili při podepsání.

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

Dále zatřiďte text požadavku pomocí SHA 256 a umístěte ho do hlavičky x-ms-content-sha256 . Postman obsahuje některé standardní knihovny pro zatřiďování a podepisování globálně, takže je nemusíte instalovat ani vyžadovat.

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

Použijte dříve zadanou proměnnou koncového bodu k rozlišení hodnoty hlavičky hostitele HTTP. Hlavička hostitele není nastavená, dokud se tento skript nezpracuje.

// 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://','');

Pomocí těchto informací teď můžete vytvořit řetězec, který podepíšete pro požadavek HTTP. Řetězec se skládá z několika dříve vytvořených hodnot.

// 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;

Nakonec tento řetězec podepíšete pomocí klíče komunikační služby. Potom tento klíč přidejte do požadavku v Authorization hlavičce.

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

Konečný skript předběžného požadavku

Konečný skript předběžného požadavku by měl vypadat přibližně jako v tomto příkladu:

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

Zadejte nebo vložte tento konečný skript do textové oblasti na kartě Skript před vyžádáním .

Až ho zadáte, vyberte Ctrl+S nebo vyberte Uložit a uložte skript do kolekce.

Vytvořte požadavek v Postmanu

Teď, když je všechno nastavené, můžete v Nástroji Postman vytvořit žádost o komunikační služby. Začněte tím, že vyberete znaménko plus (+) vedle kolekce Communication Services.

V nástroji Postman jste vytvořili novou kartu pro vaši žádost a teď ji musíte nakonfigurovat. Odešlete požadavek proti API pro odesílání SMS, proto se podívejte do dokumentace k tomuto rozhraní API pro pomoc. Pojďme nakonfigurovat požadavek Postman.

Začněte tak, že typ POST požadavku nastavíte a zadáte {{endpoint}}/sms?api-version=2021-03-07 do pole adresy URL požadavku. Tato adresa URL používá dříve vytvořenou proměnnou endpoint k automatickému odeslání do prostředku komunikačních služeb.

Na kartě Tělo požadavku vyberte surový. V rozevíracím seznamu napravo vyberte JSON.

Nakonfigurovali jste požadavek na odesílání a příjem informací ve formátu JSON.

Do textové oblasti zadejte text požadavku v následujícím formátu:

{
    "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 Pro hodnotu musíte získat telefonní číslo na portálu Komunikační služby, jak jsme už zmínili. Zadejte ho bez mezer a předpony kódu vaší země. Příklad: +15555551234. Může message to být cokoli, co chcete poslat, ale Hello from Azure Communication Services je to dobrý příklad. Hodnota to by měla být telefon, ke kterému máte přístup, abyste mohli přijímat zprávy SMS. Použití vlastního mobilního telefonu je dobrý nápad.

Uložte tento požadavek do kolekce služby Communication Services, kterou jste vytvořili dříve. Tento krok zajistí, že převezme proměnné a skript předběžného požadavku, který jste vytvořili dříve. V pravém horním rohu oblasti žádosti vyberte Uložit .

V dialogovém okně, které se objeví, budete dotázáni, jak chcete označit žádost a kam ji chcete uložit. Můžete ji pojmenovat cokoliv, ale ujistěte se, že vyberete kolekci Komunikační služby v dolní polovině dialogového okna.

Odeslání žádosti

Teď, když je všechno nastavené, můžete poslat žádost a získat sms zprávu na telefonu. Pokud chcete tento krok provést, ujistěte se, že je vybraná vaše žádost, a pak vyberte Odeslat.

Pokud všechno proběhlo dobře, uvidíte odpověď z komunikačních služeb, což je stavový kód 202.

Mobilní telefon, který vlastní číslo, které jste zadali v hodnotě to , obdržel také zprávu SMS. Teď máte funkční konfiguraci Nástroje Postman, která může komunikovat se komunikačními službami a odesílat zprávy SMS.

Související obsah

• Prozkoumání rozhraní API služeb Azure Communication Services
• Další informace o ověřování
• Další informace o Postmanu
• Přidání chatu do aplikace
• Vytvoření přístupových tokenů uživatele
• Další informace o architektuře klienta a serveru
• Další informace o ověřování