Självstudie: Signera och göra begäranden med Postman
I den här självstudien konfigurerar och använder vi Postman för att göra en begäran mot Azure Communication Services med HTTP. I slutet av den här självstudien har du skickat ett SMS med hjälp av Communication Services och Postman. Sedan kan du använda Postman för att utforska andra API:er inom Azure Communication Services.
I den här självstudien kommer vi att:
- Laddar ned Postman
- Konfigurera Postman för att signera HTTP-begäranden
- Göra en begäran mot SMS-API:et för Communication Services för att skicka ett meddelande.
Förutsättningar
- Ett Azure-konto med en aktiv prenumeration. Mer information finns i Skapa ett konto kostnadsfritt. Det kostnadsfria kontot ger dig 200 USD i Azure-krediter för att prova en valfri kombination av tjänster.
- En aktiv Communication Services-resurs och anslutningssträng. [
- Ett Azure Communication Services Telefonnummer som kan skicka SMS finns i Hämta ett telefonnummer för att få ett.
Ladda ned och installera Postman
Postman är ett skrivbordsprogram som kan göra API-begäranden mot alla HTTP-API:er. Det används ofta för att testa och utforska API:er. Vi kommer att ladda ned den senaste skrivbordsversionen från Postmans webbplats. Postman har versioner för Windows, Mac och Linux, så ladda ned den version som är lämplig för ditt operativsystem. När du har laddat ned öppnar du programmet. Du får en startskärm där du uppmanas att logga in eller skapa ett Postman-konto. Det är valfritt att skapa ett konto och kan hoppas över genom att klicka på länken "Hoppa över och gå till app". När du skapar ett konto sparas inställningarna för API-begäranden i Postman, vilket gör att du kan hämta dina begäranden på andra datorer.
När du har skapat ett konto eller hoppat över att skapa ett bör du nu se Postmans huvudfönster.
Skapa och konfigurera en Postman-samling
Postman, kan organisera begäranden på många sätt. I den här självstudien. Vi kommer att skapa en Postman-samling. Det gör du genom att välja knappen samlingar till vänster i programmet:
När du har valt klickar du på "Skapa ny samling" för att starta processen för att skapa samlingen. En ny flik öppnas i mitten av Postman. Ge samlingen namnet vad du vill. Här heter samlingen "Azure Communication Services":
När samlingen har skapats och döpts är du redo att konfigurera den.
Lägga till samlingsvariabler
För att hantera autentisering och göra begäranden enklare anger vi två samlingsvariabler i den nyligen skapade Communication Services-samlingen. Dessa variabler är tillgängliga för alla begäranden i din Communication Services-samling. Kom igång med att skapa variabler genom att gå till fliken För samlingsvariabler.
När du är på fliken Samling skapar du två variabler:
- key – Den här variabeln ska vara en av dina nycklar från Azure Communication Services nyckelsida i Azure Portal. Till exempel
oW...A==. - slutpunkt – Den här variabeln ska vara din Azure Communication Services slutpunkt från nyckelsidan. ** Till exempel
https://contoso.communication.azure.com.
Ange dessa värden i kolumnen "Initial Value" på variabelskärmen. När du har angett det trycker du på knappen "Spara alla" precis ovanför tabellen till höger. När Postman-skärmen är korrekt konfigurerad bör den se ut ungefär så här:
Du kan lära dig mer om variabler genom att läsa Postmans dokumentation om dem.
Skapa ett skript för förbegäran
Nästa steg är att skapa ett skript för förbegäran i Postman. Ett skript för förbegäran är ett skript som körs före varje begäran i Postman och kan ändra begärandeparametrar för din räkning. Vi kommer att använda detta för att signera våra HTTP-begäranden så att de kan auktoriseras av Azure Communication Services. Mer information om signeringskraven finns i vår guide om autentisering.
Vi kommer att skapa det här skriptet i samlingen så att det körs på alla begäranden i samlingen. Det gör du genom att klicka på underfliken "Skript för förbegäran" på fliken Samling.
På den här underfliken kan du skapa ett förbegärandeskript genom att ange det i textområdet nedan. Det kan vara enklare att skriva detta i en fullständig kodredigerare, till exempel Visual Studio Code , innan du klistrar in det när det är klart. Vi går igenom varje del av skriptet i den här självstudien. Hoppa över till slutet om du bara vill kopiera det till Postman och komma igång. Vi börjar skriva skriptet.
Skriva skriptet före begäran
Det första vi ska göra är att skapa en UTC-sträng (Coordinated Universal Time) och lägga till den i HTTP-huvudet "Date". Vi lagrar även den här strängen i en variabel för att använda den senare vid signering:
// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});
Nu ska vi hasha begärandetexten med SHA 256 och placera den i x-ms-content-sha256 rubriken. Postman innehåller några standardbibliotek för hashning och signering globalt, så vi behöver inte installera dem eller kräva dem:
// 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
});
Nu ska vi använda vår tidigare angivna slutpunktsvariabel för att urskilja värdet för HTTP-värdhuvudet. Vi måste göra detta eftersom värdhuvudet inte har angetts förrän det här skriptet har bearbetats:
// 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://','');
När den här informationen har skapats kan vi nu skapa strängen, som vi kommer att signera för HTTP-begäran. Den består av flera tidigare skapade värden:
// 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;
Slutligen måste vi signera den här strängen Authorization med hjälp av vår Communication Services-nyckel och sedan lägga till den i vår begäran i rubriken:
// 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
});
Det slutliga förbegärandeskriptet
Det slutliga förbegärandeskriptet bör se ut ungefär så här:
// 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
});
Ange eller klistra in det här sista skriptet i textområdet på fliken Skript för förbegäran:
När du har angett det trycker du på CTRL + S eller trycker på knappen Spara. Då sparas skriptet i samlingen.
Skapa en begäran i Postman
Nu när allt har konfigurerats är vi redo att skapa en Communication Services-begäran i Postman. Kom igång genom att klicka på plusikonen(+) bredvid Communication Services-samlingen:
Då skapas en ny flik för vår begäran i Postman. När den har skapats måste vi konfigurera den. Vi kommer att göra en begäran mot SMS Send-API:et, så se till att du hittar hjälp i dokumentationen för det här API:et. Nu ska vi konfigurera Postmans begäran.
Börja med att ange, typ av begäran till POST och ange {{endpoint}}/sms?api-version=2021-03-07 i fältet för begärande-URL. Den här URL:en använder vår tidigare skapade endpoint variabel för att automatiskt skicka den till din Communication Services-resurs.
Välj nu fliken Brödtext i begäran och ändra sedan alternativknappen under till "raw". Till höger finns en listruta med texten "Text" och ändra den till JSON:
Då konfigureras begäran för att skicka och ta emot information i JSON-format.
I textområdet nedan måste du ange en begärandetext. Den bör ha följande format:
{
"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>"
}
]
}
För värdet "från" måste du hämta ett telefonnummer i Azure Communication Services-portalen som tidigare nämnts. Ange den utan blanksteg och föregås av landskoden. Exempel: +15555551234. Ditt "meddelande" kan vara vad du vill skicka men Hello from Azure Communication Services är ett bra exempel. Värdet "till" ska vara en telefon som du har åtkomst till som kan ta emot SMS. Att använda din egen mobil är en bra idé.
När den har angetts måste vi spara den här begäran i den Communication Services-samling som vi skapade tidigare. Detta säkerställer att det hämtar variablerna och skriptet för förbegäran som vi skapade tidigare. Det gör du genom att klicka på knappen "Spara" längst upp till höger i området för begäran.
Då visas ett dialogfönster som frågar dig vad du vill anropa begäran och var du vill spara den. Du kan ge den ett namn som du vill, men se till att du väljer din Communication Services-samling i den nedre halvan av dialogrutan:
Skicka en begäran
Nu när allt har konfigurerats bör du kunna skicka begäran och få ett SMS på telefonen. Det gör du genom att se till att din skapade begäran är markerad och tryck sedan på knappen "Skicka" till höger:
Om allt gick bra bör du nu se svaret från Communication Services, som ska vara 202 Statuskod:
Mobiltelefonen, som äger numret som du angav i "till"-värdet, bör också ha fått ett SMS. Nu har du en funktionell Postman-konfiguration som kan kommunicera med Azure Communication Services och skicka SMS.
Nästa steg
Du kanske också vill: