Kurz: Podepisování a vytváření požadavků pomocí nástroje Postman

V tomto kurzu nastavíme a použijeme Nástroj Postman k vytvoření požadavku na Azure Communication Services pomocí protokolu HTTP. Na konci tohoto kurzu úspěšně odešlete zprávu SMS pomocí komunikačních služeb a nástroje Postman. Pak budete moct pomocí Nástroje Postman prozkoumat další rozhraní API v rámci Azure Communication Services.

V tomto kurzu budeme:

• Stažení nástroje Postman
• Nastavení nástroje Postman pro podepisování požadavků HTTP
• Vytvoření žádosti o odeslání zprávy v rozhraní SMS API komunikačních služeb

Požadavky

• Účet Azure s aktivním předplatným. Podrobnosti najdete v tématu Bezplatné vytvoření účtu. Bezplatný účet vám poskytne 200 USD v kreditech Azure, abyste si mohli vyzkoušet libovolnou kombinaci služeb.
• Aktivní prostředek komunikačních služeb a připojovací řetězec. Zjistěte, jak vytvořit prostředek komunikačních služeb.
• Azure Communication Services Telefonní číslo, které může posílat SMS zprávy, najdete v článku Získání telefonního čísla.

Stažení a instalace nástroje Postman

Postman je desktopová aplikace, která je schopná vytvářet požadavky rozhraní API na libovolné rozhraní API HTTP. Běžně se používá k testování a zkoumání rozhraní API. Z webu Postman stáhneme nejnovější desktopovou verzi. 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 stažení otevřete aplikaci. Zobrazí se úvodní obrazovka s žádostí o přihlášení nebo vytvoření účtu Postman. Vytvoření účtu je volitelné a můžete ho přeskočit kliknutím na odkaz Přeskočit a přejít do aplikace. Vytvořením účtu se nastavení požadavků rozhraní API uloží do nástroje Postman, který vám pak umožní vyzvednout požadavky na jiných počítačích.

Jakmile vytvoříte účet nebo ho přeskočíte, měli byste teď vidět hlavní okno nástroje Postman.

Vytvoření a konfigurace kolekce Postman

Postman, může uspořádat žádosti mnoha způsoby. Pro účely tohoto kurzu. Vytvoříme kolekci Postman. Uděláte to tak, že vyberete tlačítko kolekce na levé straně aplikace:

Po výběru klikněte na Vytvořit novou kolekci a spusťte proces vytváření kolekce. Ve středové oblasti nástroje Postman se otevře nová karta. Pojmenujte kolekci, jak chcete. Zde má kolekce název "Azure Communication Services":

Jakmile se kolekce vytvoří a pojmenuje, můžete ji nakonfigurovat.

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

Abychom zvládli ověřování a usnadnili požadavky, určíme v nově vytvořené kolekci Komunikačních služeb dvě proměnné kolekce. Tyto proměnné jsou k dispozici pro všechny požadavky v rámci vaší kolekce Communication Services. Pokud chcete začít vytvářet proměnné, přejděte na kartu Proměnné v kolekci.

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

• key – tato proměnná by měla být jedním z klíčů ze stránky klíče Azure Communication Services v rámci Azure Portal. Například, oW...A==.
• koncový bod – tato proměnná by měla být koncovým bodem Azure Communication Services ze stránky klíče. Nezapomeňte odebrat koncové lomítko. Například, https://contoso.communication.azure.com.

Zadejte tyto hodnoty do sloupce Počáteční hodnota na obrazovce proměnných. Po zadání stiskněte tlačítko "Zachovat vše" přímo nad tabulkou na pravé straně. Při správné konfiguraci by měla obrazovka Nástroje Postman vypadat nějak takto:

Další informace o proměnných najdete v dokumentaci společnosti Postman k nim.

Vytvoření skriptu před vyžádáním

Dalším krokem je vytvoření skriptu před vyžádáním v postmanu. Skript před vyžádáním je skript, který se spouští před každým požadavkem v nástroji Postman a může za vás upravovat nebo měnit parametry požadavku. Použijeme ho k podepisování požadavků HTTP, aby je mohl autorizovat Azure Communication Services. Další informace o požadavcích na podepisování najdete v našem průvodci ověřováním.

Tento skript vytvoříme v kolekci tak, aby běžel na libovolném požadavku v kolekci. Uděláte to tak, že na kartě kolekce kliknete na dílčí kartu Předžadovací skript.

Na této dílčí kartě můžete vytvořit skript předběžné žádosti tak, že ho zadáte do textové oblasti níže. Může být jednodušší to napsat v rámci úplného editoru kódu, jako je Visual Studio Code , než ho po dokončení vložíte. V tomto kurzu si projdeme jednotlivé části skriptu. Pokud byste ho chtěli jednoduše zkopírovat do Postmanu a začít, můžete přeskočit na konec. Začněme psát skript.

Psaní skriptu před vyžádáním

První věc, kterou budeme dělat, je vytvořit řetězec UTC (Coordinated Universal Time) a přidat ho do hlavičky HTTP "Date". Tento řetězec také ukládáme do proměnné, abychom ho mohli později použít při podepisová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 použijeme algoritmus SHA 256 k hashování textu požadavku a umístíme ho do hlavičky x-ms-content-sha256 . Postman obsahuje některé standardní knihovny pro globální hashování a podepisování, takže je nemusíme instalovat ani vyžadovat:

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

Teď použijeme naši dříve zadanou proměnnou koncového bodu k rozlišení hodnoty hlavičky hostitele HTTP. Musíme to udělat, protože hlavička Host se nenastaví, 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://','');

Po vytvoření těchto informací teď můžeme vytvořit řetězec, který budeme podepisovat pro požadavek HTTP, který 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, using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;

Nakonec musíme tento řetězec podepsat pomocí klíče komunikačních služeb a pak ho Authorization přidat do našeho požadavku v 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
});

Poslední skript před vyžádáním

Konečný skript před vyžádáním by měl vypadat nějak takto:

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

Zadejte nebo vložte tento konečný skript do textové oblasti na kartě Předžadovací skript:

Po zadání stiskněte kombinaci kláves CTRL + S nebo stiskněte tlačítko Uložit, čímž se skript uloží do kolekce.

Vytvoření požadavku v nástroji Postman

Teď, když je všechno nastavené, jsme připraveni vytvořit žádost o komunikační služby v nástroji Postman. Začněte kliknutím na ikonu plus(+) vedle kolekce komunikačních služeb:

Tím se v postmanu vytvoří nová karta pro naši žádost. Když je vytvořený, musíme ho nakonfigurovat. Odešleme požadavek na rozhraní SMS Send API, proto se nezapomeňte podívat na dokumentaci k tomuto rozhraní API, kde najdete pomoc. Pojďme nakonfigurovat požadavek postmana.

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

Teď vyberte kartu Text požadavku a pak změňte přepínač pod na "raw". Na pravé straně je rozevírací seznam s textem "Text", změňte ho na JSON:

Tím se požadavek nakonfiguruje tak, aby odesílal a přijímal informace ve formátu JSON.

Do textové oblasti níže budete muset zadat text požadavku, který by měl být 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>"
        }
    ]
}

Jako hodnotu "od" budete muset získat telefonní číslo na portálu Azure Communication Services, jak jsme zmínili dříve. Zadejte ho bez mezer a uveďte před ním kód země. Příklad: +15555551234. Vaše "zpráva" může 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 a který může přijímat zprávy SMS. Použití vlastního mobilního telefonu je dobrý nápad.

Po zadání musíme tento požadavek uložit do kolekce komunikačních služeb, kterou jsme vytvořili dříve. Tím se zajistí, že převezme proměnné a skript předběžné žádosti, které jsme vytvořili dříve. Uděláte to tak, že kliknete na tlačítko Uložit v pravém horním rohu oblasti žádosti.

Zobrazí se dialogové okno s dotazem, na co chcete žádost volat a kam ji chcete uložit. Můžete ji pojmenovat libovolným způsobem, ale ujistěte se, že jste svoji kolekci Communication Services vybrali v dolní polovině dialogového okna:

Odeslání požadavku

Teď, když je všechno nastavené, byste měli být schopni odeslat žádost a dostat na telefon zprávu SMS. Pokud to chcete udělat, ujistěte se, že je váš vytvořený požadavek vybraný, a pak stiskněte tlačítko Odeslat na pravé straně:

Pokud vše proběhlo správně, měla by se vám teď zobrazit odpověď od komunikačních služeb, která by měla být stavový kód 202:

Mobilní telefon, který vlastní číslo, které jste zadali v hodnotě "to", by také měl obdržet zprávu SMS. Teď máte funkční konfiguraci Nástroje Postman, která může komunikovat s Azure Communication Services a posílat zprávy SMS.

Další kroky

Prozkoumání Azure Communication Services rozhraní APIPřečtěte si další informace o ověřováníDalší informace o nástroji Postman

Můžete také chtít:

• Přidání chatu do aplikace
• Vytvoření přístupových tokenů uživatelů
• Informace o architektuře klienta a serveru
• Informace o ověřování