Zelfstudie: Aanvragen ondertekenen en indienen met Postman

In deze zelfstudie gaan we Postman instellen en gebruiken om een aanvraag in te dienen tegen Azure Communication Services met behulp van HTTP. Aan het einde van deze zelfstudie hebt u een sms-bericht verzonden via Communication Services en Postman. Vervolgens kunt u Postman gebruiken om andere API's in Azure Communication Services te verkennen.

In deze zelfstudie doen we het volgende:

• 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 aan Azure-tegoed om een combinatie van services uit te proberen.
• Een actieve Communication Services-resource en verbindingsreeks. Meer informatie over het maken van een Communication Services-resource.
• Een Azure Communication Services Telefoonnummer waarmee sms-berichten kunnen worden verzonden, raadpleegt u ons Telefoonnummer ophalen om er een te krijgen.

Postman downloaden en installeren

Postman is een bureaubladtoepassing waarmee API-aanvragen kunnen worden gemaakt 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 'Overslaan en naar de app gaan'. Als u een account maakt, worden uw API-aanvraaginstellingen opgeslagen in Postman, zodat u uw aanvragen op andere computers kunt ophalen.

Zodra u een account hebt gemaakt of het maken ervan hebt overgeslagen, ziet u nu het hoofdvenster van Postman.

Een Postman-verzameling maken en configureren

Postman, kan aanvragen op verschillende manieren organiseren. Voor de doeleinden van deze zelfstudie. We gaan een Postman Collection maken. Selecteer hiervoor de knop Verzamelingen aan de linkerkant van de toepassing:

Als 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. Geef de verzameling een naam zoals u wilt. Hier heet de verzameling 'Azure Communication Services':

Zodra uw verzameling is gemaakt en een naam heeft, kunt u deze configureren.

Verzamelingsvariabelen toevoegen

Om verificatie af te handelen en aanvragen eenvoudiger te maken, geven we twee verzamelingsvariabelen op binnen 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:

• key: deze variabele moet een van uw sleutels zijn vanaf de sleutelpagina van uw Azure Communication Services in de 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 'Beginwaarde' van het scherm variabelen in. Nadat u dit hebt ingevoerd, drukt u op de knop 'Alles behouden' net boven de tabel aan de rechterkant. Wanneer dit correct is geconfigureerd, ziet het Postman-scherm er ongeveer als volgt uit:

U kunt meer te weten komen over variabelen door de documentatie van Postman over deze variabelen te lezen.

Een script vooraf aanvragen maken

De volgende stap is het maken van een script vooraf aanvragen in Postman. Een script vooraf aanvragen is een script dat vóór elke aanvraag in Postman wordt uitgevoerd en namens u aanvraagparameters kan wijzigen of wijzigen. We gebruiken dit 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 binnen de verzameling. Klik hiervoor op het tabblad Verzameling op het subtabblad 'Script vooraf aanvragen'.

Op dit subtabblad kunt u een script vooraf aanvragen door dit in het onderstaande tekstgebied in te voeren. Het is misschien gemakkelijker om dit te schrijven in een volledige code-editor, zoals Visual Studio Code , voordat u deze in plakt wanneer u klaar bent. In deze zelfstudie gaan we elk deel van het script doornemen. Ga gerust naar het einde als u het naar Postman wilt kopiëren en aan de slag wilt gaan. Laten we beginnen met het schrijven van het script.

Het script vooraf schrijven

Het eerste wat we gaan doen, is een UTC-tekenreeks (Coordinated Universal Time) maken en deze toevoegen aan de HTTP-header 'Date'. We slaan deze tekenreeks ook op in een variabele om deze later te gebruiken bij het ondertekenen:

// 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 gaan we de aanvraagbody hashen met behulp van SHA 256 en deze in de x-ms-content-sha256 header plaatsen. Postman bevat enkele standaardbibliotheken voor hashing en ondertekening wereldwijd, zodat we ze niet hoeven te installeren of vereisen:

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

// 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 de tekenreeks maken, die we gaan ondertekenen voor de HTTP-aanvraag. Deze bestaat uit verschillende eerder gemaakte waarden:

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

// 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 vooraf aanvragen

Het laatste script voor de aanvraag moet er ongeveer als volgt uitzien:

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

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

Wanneer u het invoert, drukt u op Ctrl+S of drukt u op de knop Opslaan om het script op te slaan in de verzameling.

Een aanvraag maken in Postman

Nu alles is ingesteld, zijn we klaar om een Communication Services-aanvraag te maken in Postman. Klik op het pluspictogram (+) naast de Verzameling Communication Services om aan de slag te gaan:

Hiermee maakt u een nieuw tabblad voor onze aanvraag in Postman. Nu het is gemaakt, moeten we het 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 naar POST en voer in {{endpoint}}/sms?api-version=2021-03-07 het veld aanvraag-URL in. Deze URL maakt gebruik van de 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'. Aan de rechterkant ziet u een vervolgkeuzelijst met de tekst 'Tekst'. Wijzig 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 aanvraagbody invoeren. Deze moet de volgende indeling hebben:

{
    "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 het in zonder spaties en voorafgegaan door uw landcode. Bijvoorbeeld: +15555551234. Uw 'bericht' kan zijn wat u wilt verzenden, maar Hello from Azure Communication Services is een goed voorbeeld. De waarde 'to' moet een telefoon zijn waartoe u toegang hebt en die sms-berichten kan ontvangen. Het gebruik van uw eigen mobiel is een goed idee.

Na invoer 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 de aanvraag wilt aanroepen en waar u deze wilt opslaan. U kunt deze een naam geven die u maar wilt, maar zorg ervoor dat u uw Communication Services-verzameling selecteert in de onderste helft van het dialoogvenster:

Een aanvraag verzenden

Nu alles is ingesteld, kunt u de aanvraag verzenden en een sms-bericht op uw telefoon ontvangen. Om dit te doen, controleert u of uw gemaakte aanvraag is geselecteerd en drukt u vervolgens op de knop Verzenden aan de rechterkant:

Als alles goed is gegaan, ziet u nu het antwoord van Communication Services. Dit moet statuscode 202 zijn:

De mobiele telefoon, die eigenaar is van het nummer dat u hebt opgegeven in de 'aan'-waarde, 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

Verken Azure Communication Services API'sLees meer over verificatieMeer informatie over Postman

U kunt ook het volgende doen:

• Chat aan uw app toevoegen
• Tokens voor gebruikerstoegang maken
• Meer leren over architectuur van client en server
• Meer leren over verificatie