Zelfstudie: Aanvragen ondertekenen en indienen met Postman
Artikel
In deze zelfstudie gaan we Postman instellen en gebruiken om een aanvraag in te dienen bij Azure Communication Services met behulp van HTTP. Aan het einde van deze zelfstudie hebt u een sms-bericht verzonden met behulp van Communication Services en Postman. Vervolgens kunt u Postman gebruiken om andere API's in Azure Communication Services te verkennen.
In deze zelfstudie zijn we:
Postman downloaden
Postman instellen voor het ondertekenen van HTTP-aanvragen
Een aanvraag indienen bij de SMS-API van Communication Services om een bericht te verzenden.
Vereisten
Een Azure-account met een actief abonnement. Zie Gratis een account maken voor meer informatie. Met het gratis account krijgt u $ 200 in Azure-tegoed om een combinatie van services uit te proberen.
Een telefoonnummer van Azure Communication Services waarmee sms-berichten kunnen worden verzonden. Zie ons Telefoonnummer ophalen om er een te krijgen.
Postman downloaden en installeren
Postman, is een bureaubladtoepassing die API-aanvragen kan indienen voor elke HTTP-API. Het wordt vaak gebruikt voor het testen en verkennen van API's. We downloaden de nieuwste desktopversie van de website van Postman. Postman heeft versies voor Windows, Mac en Linux, dus download de versie die geschikt is voor uw besturingssysteem. Nadat u de toepassing hebt gedownload, opent u de toepassing. U krijgt een startscherm te zien waarin u wordt gevraagd u aan te melden of een Postman-account te maken. Het maken van een account is optioneel en kan worden overgeslagen door te klikken op de koppeling 'Skip and go to app'. Als u een account maakt, worden uw API-aanvraaginstellingen opgeslagen in Postman, zodat u vervolgens uw aanvragen op andere computers kunt ophalen.
Nadat u een account hebt gemaakt of een account hebt overgeslagen, ziet u nu het hoofdvenster van Postman.
Een Postman-verzameling maken en configureren
Postman, kan aanvragen op veel manieren organiseren. Voor deze zelfstudie. We gaan een Postman Collection maken. Hiervoor selecteert u de knop Verzamelingen aan de linkerkant van de toepassing:
Nadat u deze optie hebt geselecteerd, klikt u op Nieuwe verzameling maken om het proces voor het maken van de verzameling te starten. Er wordt een nieuw tabblad geopend in het middelste gedeelte van Postman. Noem de verzameling wat u wilt. Hier heet de verzameling 'Azure Communication Services':
Zodra uw verzameling is gemaakt en benoemd, kunt u deze configureren.
Verzamelingsvariabelen toevoegen
Om verificatie af te handelen en aanvragen eenvoudiger te maken, geven we twee verzamelingsvariabelen op in de zojuist gemaakte Communication Services-verzameling. Deze variabelen zijn beschikbaar voor alle aanvragen binnen uw Communication Services-verzameling. Ga naar het tabblad Variabele van de verzameling om aan de slag te gaan met het maken van variabelen.
Maak op het tabblad Verzameling twee variabelen:
sleutel: deze variabele moet een van uw sleutels zijn van de sleutelpagina van Uw Azure Communication Services in Azure Portal. Bijvoorbeeld: oW...A==.
eindpunt: deze variabele moet het eindpunt van uw Azure Communication Services zijn vanaf de sleutelpagina.
Zorg ervoor dat u de afsluitende slash verwijdert. Bijvoorbeeld: https://contoso.communication.azure.com.
Voer deze waarden in de kolom 'Initiële waarde' van het scherm variabelen in. Nadat u alles hebt ingevoerd, drukt u op de knop Alles behouden net boven de tabel aan de rechterkant. Wanneer uw Postman-scherm correct is geconfigureerd, ziet er ongeveer als volgt uit:
Meer informatie over variabelen vindt u in de documentatie van Postman.
Een script vooraf aanvragen maken
De volgende stap is het maken van een script vooraf in Postman. Een pre-aanvraagscript is een script dat wordt uitgevoerd vóór elke aanvraag in Postman en namens u aanvraagparameters kan wijzigen of wijzigen. We gebruiken deze om onze HTTP-aanvragen te ondertekenen, zodat ze kunnen worden geautoriseerd door Azure Communication Services. Lees onze handleiding over verificatie voor meer informatie over de ondertekeningsvereisten.
We maken dit script in de verzameling, zodat het wordt uitgevoerd op elke aanvraag in de verzameling. Klik hiervoor op het tabblad Verzameling op het subtabblad Pre-request Script.
Op dit subtabblad kunt u een script vooraf aanvragen door het in het onderstaande tekstgebied in te voeren. Het kan eenvoudiger zijn om dit te schrijven in een volledige code-editor, zoals Visual Studio Code , voordat u deze plakt wanneer u klaar bent. In deze zelfstudie doorlopen we elk deel van het script. Ga naar het einde als u het gewoon naar Postman wilt kopiëren en aan de slag wilt gaan. Laten we beginnen met het schrijven van het script.
Het script vóór de aanvraag schrijven
Het eerste wat we gaan doen, is het maken van een UTC-tekenreeks (Coordinated Universal Time) en dit toevoegen aan de HTTP-header 'Datum'. Deze tekenreeks wordt ook opgeslagen in een variabele om deze later te gebruiken bij het ondertekenen:
JavaScript
// Set the Date header to our Date as a UTC String.const dateStr = newDate().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});
Vervolgens hashen we de aanvraagbody met behulp van SHA 256 en plaatsen we deze in de x-ms-content-sha256 header. Postman bevat enkele standaardbibliotheken voor hashing en ondertekening wereldwijd, dus we hoeven ze niet te installeren of te vereisen:
JavaScript
// Hash the request body using SHA256 and encode it as Base64const 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 gebruiken we onze eerder opgegeven eindpuntvariabele om de waarde voor de HTTP-hostheader te onderscheiden. We moeten dit doen omdat de hostheader pas is ingesteld nadat dit script is verwerkt:
JavaScript
// Get our previously specified endpoint variableconst endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" valueconst hostStr = endpoint.replace('https://','');
Nu deze informatie is gemaakt, kunnen we nu de tekenreeks maken, die we gaan ondertekenen voor de HTTP-aanvraag. Dit bestaat uit verschillende eerder gemaakte waarden:
JavaScript
// 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;
Ten slotte moeten we deze tekenreeks ondertekenen met behulp van onze Communication Services-sleutel en deze vervolgens toevoegen aan onze aanvraag in de Authorization header:
JavaScript
// 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
});
Het laatste script vóór aanvraag
Het laatste script vóór de aanvraag moet er ongeveer als volgt uitzien:
JavaScript
// Set the Date header to our Date as a UTC String.const dateStr = newDate().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});
// Hash the request body using SHA256 and encode it as Base64const 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 variableconst endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" valueconst 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
});
Typ of plak dit laatste script in het tekstgebied op het tabblad Script vooraf aanvragen:
Nadat u het script hebt ingevoerd, drukt u op Ctrl+S of drukt u op de knop Opslaan, zodat het script in de verzameling wordt opgeslagen.
Een aanvraag maken in Postman
Nu alles is ingesteld, zijn we klaar om een Communication Services-aanvraag in Postman te maken. Klik op het pluspictogram (+) naast de Communication Services-verzameling om aan de slag te gaan:
Hiermee maakt u een nieuw tabblad voor onze aanvraag in Postman. Nu het is gemaakt, moeten we deze configureren. We doen een aanvraag voor de SMS Send-API, dus raadpleeg de documentatie voor deze API voor hulp. Laten we de aanvraag van Postman configureren.
Begin met het instellen van het aanvraagtype voor POST het aanvraag-URL-veld en het invoeren {{endpoint}}/sms?api-version=2021-03-07 van het aanvraag-URL-veld. Deze URL maakt gebruik van onze eerder gemaakte endpoint variabele om deze automatisch naar uw Communication Services-resource te verzenden.
Selecteer nu het tabblad Hoofdtekst van de aanvraag en wijzig het keuzerondje eronder in 'raw'. Rechts ziet u een vervolgkeuzelijst met de tekst 'Tekst', wijzigt u deze in JSON:
Hiermee configureert u de aanvraag voor het verzenden en ontvangen van informatie in een JSON-indeling.
In het onderstaande tekstgebied moet u een aanvraagtekst invoeren. Deze moet de volgende indeling hebben:
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>"
}
]
}
Voor de waarde 'van' moet u een telefoonnummer ophalen in de Azure Communication Services-portal zoals eerder vermeld. Voer deze in zonder spaties en voorafgegaan door uw landcode. Voorbeeld: +15555551234. Uw 'bericht' kan zijn wat u wilt verzenden, maar Hello from Azure Communication Services is een goed voorbeeld. De waarde 'aan' moet een telefoon zijn waartoe u toegang hebt om sms-berichten te ontvangen. Het gebruik van uw eigen mobiele telefoon is een goed idee.
Zodra dit is ingevoerd, moeten we deze aanvraag opslaan in de Communication Services-verzameling die we eerder hebben gemaakt. Dit zorgt ervoor dat de variabelen en het script dat we eerder hebben gemaakt, worden opgehaald. Klik hiervoor op de knop Opslaan in de rechterbovenhoek van het aanvraaggebied.
Er wordt dan een dialoogvenster weergegeven waarin u wordt gevraagd wat u wilt aanroepen en waar u de aanvraag wilt opslaan. U kunt deze desgewenst een naam geven, maar zorg ervoor dat u uw Communication Services-verzameling selecteert in de onderste helft van het dialoogvenster:
Een aanvraag verzenden
Nu alles is ingesteld, moet u de aanvraag kunnen verzenden en een sms-bericht op uw telefoon ontvangen. U doet dit door ervoor te zorgen dat uw gemaakte aanvraag is geselecteerd en druk vervolgens op de knop Verzenden aan de rechterkant:
Als alles goed is gegaan, zou u nu de reactie van Communication Services moeten zien. Dit moet de statuscode 202 zijn:
De mobiele telefoon, die eigenaar is van het nummer dat u hebt opgegeven in de waarde 'aan', moet ook een sms-bericht hebben ontvangen. U hebt nu een functionele Postman-configuratie die kan communiceren met Azure Communication Services en sms-berichten kan verzenden.
In deze module maakt u een C#-consoletoepassing waarmee sms-berichten worden verzonden met behulp van een telefoonnummer dat is ingericht via Azure Communication Services.
Met Microsoft Entra ID kunt u Toegang tot Azure Communication Services autoriseren vanuit toepassingen die worden uitgevoerd in Azure-VM's, functie-apps en andere resources.