Lezen in het Engels

Delen via


Zelfstudie: Aanvragen ondertekenen en indienen met Postman

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

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.

Het startscherm van Postman met de mogelijkheid om een account te maken of over te slaan en naar de app te gaan.

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:

Het hoofdscherm van Postman met het tabblad Verzamelingen gemarkeerd.

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':

Postman met een Communication Services Collection geopend en de naam van de verzameling gemarkeerd.

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.

Postman met het tabblad Variabelen van een Communication Services-verzameling.

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:

Postman met de variabelen van een Communication Services Collection correct ingesteld.

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.

Postman met het subtabblad Script van een Communication Services-verzameling vooraf aanvragen geselecteerd.

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 = new Date().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 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 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 variable
const endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" value
const 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 = 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
});

Typ of plak dit laatste script in het tekstgebied op het tabblad Script vooraf aanvragen:

Postman met het preaanvraagscript van een Azure Communication Services-verzameling ingevoerd.

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.

De knop Script voor opslaan vooraf aanvragen van Postman.

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:

Postman's plusknop.

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.

Een Postman-aanvraag, waarbij het type is ingesteld op POST en de URL correct is ingesteld.

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:

De hoofdtekst van de aanvraag instellen op onbewerkt en 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.

De knop Opslaan voor een Postman-aanvraag.

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:

Het dialoogvenster Voor opslaan van postman met de Communication Services-verzameling geselecteerd.

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:

Een Postman-aanvraag, met de knop Verzenden gemarkeerd.

Als alles goed is gegaan, zou u nu de reactie van Communication Services moeten zien. Dit moet de statuscode 202 zijn:

Een Postman-aanvraag, verzonden met een 202-statuscode.

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.

Volgende stappen

U kunt ook het volgende doen: