Kurz: Podepisování a vytváření žádostí pomocí Nástroje Postman
V tomto kurzu nastavíme a použijeme 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 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 podepsání požadavků HTTP
- Vytvoření požadavku na rozhraní SMS API komunikačních služeb k odeslání zprávy
Požadavky
- Účet Azure s aktivním předplatným. Podrobnosti najdete v tématu Vytvoření účtu zdarma. Bezplatný účet poskytuje 200 USD v kreditech Azure a umožňuje vyzkoušet libovolnou kombinaci služeb.
- Aktivní prostředek služby Communication Services a připojovací řetězec. Zjistěte, jak vytvořit prostředek komunikační služby.
- Telefonní číslo služby Azure Communication Services, které může posílat SMS zprávy, najdete v našem článku Získání telefonního čísla , abyste ho získali.
Stažení a instalace nástroje Postman
Postman je desktopová aplikace, která dokáže vytvářet požadavky rozhraní API na jakékoli rozhraní HTTP API. Běžně se používá k testování a zkoumání rozhraní API. Nejnovější verzi Desktopu si stáhneme z webu Postmana. Postman má verze pro Windows, Mac a Linux, proto si stáhněte verzi odpovídající vašemu operačnímu systému. Po stažení otevřete aplikaci. Zobrazí se úvodní obrazovka, která vás vyzve k 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í účtu uloží nastavení požadavků rozhraní API do Postmanu, což vám pak umožní vyzvednout žádosti na jiných počítačích.
Jakmile vytvoříte účet nebo ho přeskočíte, měli byste teď vidět hlavní okno Postmana.
Vytvoření a konfigurace kolekce Postman
Postman může žádosti uspořádat 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. V centrální oblasti nástroje Postman se otevře nová karta. Pojmenujte kolekci podle toho, co chcete. V této kolekci se jmenuje "Azure Communication Services":
Jakmile se kolekce vytvoří a pojmenuje, můžete ji nakonfigurovat.
Přidání proměnných kolekce
Abychom usnadnili ověřování a usnadnili požadavky, zadáme v rámci nově vytvořené kolekce Communication Services dvě proměnné kolekce. Tyto proměnné jsou k dispozici pro všechny požadavky v kolekci komunikačních služeb. Pokud chcete začít vytvářet proměnné, přejděte na kartu Proměnné kolekce.
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íče služby Azure Communication Services na webu Azure Portal. Například
oW...A==. - koncový bod – Tato proměnná by měla být koncovým bodem služby Azure Communication Services z klíčové stránky.
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 vpravo. Při správné konfiguraci obrazovky Postman by měla vypadat nějak takto:
Další informace o proměnných najdete v dokumentaci k Postmanovi.
Vytvoření skriptu s předběžným požadavkem
Dalším krokem je vytvoření skriptu předběžného požadavku v rámci nástroje Postman. Skript předběžné žádosti je skript, který se spouští před každým požadavkem v Nástroji Postman a může vaším jménem upravit nebo změnit parametry požadavku. Použijeme ho k podepsání požadavků HTTP, aby je mohly autorizovat služba Azure Communication Services. Další informace opožadavch
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 Skript před vyžádáním.
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 vložíte po dokončení. V tomto kurzu si projdeme jednotlivé části skriptu. Pokud ho chcete jednoduše zkopírovat do Postmanu, můžete přejít na konec a začít. Začněme psát skript.
Zápis skriptu s předběžným požadavkem
První věcí, kterou uděláme, je vytvoření řetězce koordinovaného univerzálního času (UTC) a jeho přidání do hlavičky HTTP "Date". Tento řetězec uložíme také do proměnné, abychom ho mohli použít později 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});
V dalším kroku zatřidíme tělo požadavku pomocí SHA 256 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 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 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://','');
Po vytvoření těchto informací teď můžeme vytvořit řetězec, který budeme podepisovat pro požadavek HTTP, skládá se 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í služby a pak ho Authorization přidat do 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
});
Konečný skript předběžné žádosti
Konečný skript před vyžádáním by měl vypadat přibližně 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ě Skript před vyžádáním:
Po zadání stiskněte kombinaci kláves CTRL+S nebo stiskněte tlačítko Uložit. Tí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 požadavek komunikačních služeb v rámci nástroje Postman. Začněte kliknutím na ikonu plus(+) vedle kolekce komunikačních služeb:
Vytvoří se nová karta pro náš požadavek v postmanu. Když jsme ho vytvořili, musíme ho nakonfigurovat. Budeme vyžadovat rozhraní SMS Send API, proto se nezapomeňte podívat do dokumentace k tomuto rozhraní API a požádat o 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á dříve vytvořenou endpoint proměnnou k automatickému odeslání do vašeho prostředku služby Communication Services.
Teď vyberte kartu Text požadavku a pak změňte přepínač pod "nezpracovaný". Vpravo je rozevírací seznam s textem Text, změňte ho na JSON:
Tím se nakonfiguruje požadavek, aby odesílal a přijímal informace ve formátu JSON.
Do textové oblasti níže budete muset zadat text požadavku, měl by 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>"
}
]
}
V případě hodnoty "from" budete muset na portálu Azure Communication Services získat telefonní číslo , jak jsme už zmínili. Zadejte ho bez mezer a předponu kódem vaší země. Například: +15555551234. Vaše "zpráva" může být cokoli, co chcete odeslat, ale Hello from Azure Communication Services je dobrým příkladem. Hodnota "komu" by měla být telefonem, ke kterému máte přístup, který může přijímat zprávy SMS. Použití vlastního mobilu 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 zajistíte, že převezme proměnné a skript před vyžádáním, 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, co byste chtěli zavolat a kam ho chcete uložit. Můžete ho pojmenovat cokoliv, ale ujistěte se, že vyberete kolekci komunikačních služeb v dolní polovině dialogového okna:
Odeslání žádosti
Teď, když je všechno nastavené, byste měli být schopni odeslat požadavek a dostat zprávu SMS na telefonu. Uděláte to tak, že vyberete vytvořenou žádost a pak vpravo stisknete tlačítko Odeslat:
Pokud všechno proběhlo dobře, měli byste vidět odpověď z komunikačních služeb, což by mělo být stavový kód 202:
Mobilní telefon, který vlastní číslo, které jste zadali v hodnotě komu, by také měl obdržet zprávu SMS. Teď máte funkční konfiguraci Postmanu, která může komunikovat se službou Azure Communication Services a odesílat zprávy SMS.
Další kroky
Můžete také chtít: