Tutorial: Signieren und Senden von Anforderungen mit Postman

Artikel
05/23/2023

In diesem Tutorial wird Postman eingerichtet und dazu verwendet, eine HTTP-Anforderung an Azure Communication Services zu senden. Am Ende dieses Tutorials werden Sie erfolgreich eine SMS-Nachricht mit Communication Services und Postman gesendet haben. Sie können dann mit Postman andere APIs in Azure Communication Services untersuchen.

Dieses Tutorial umfasst Folgendes:

Herunterladen von Postman
Einrichten von Postman zum Signieren von HTTP-Anforderungen
Senden einer Anforderung an die SMS-API von Communication Services, eine Nachricht zu senden.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Details finden Sie unter kostenloses Azure-Konto erstellen. Beim kostenlosen Konto erhalten Sie eine Azure-Gutschrift in Höhe von 200 US-Dollar, damit Sie Kombinationen verschiedener Dienste ausprobieren können.
Eine aktive Communication Services-Ressource und eine Verbindungszeichenfolge. Informieren Sie sich über das Erstellen einer Communication Services-Ressource.
Eine zum Senden von SMS geeignete Azure Communication Services-Telefonnummer. Wie Sie eine solche Telefonnummer erhalten, erfahren Sie unter Schnellstart: Beschaffen und Verwalten von Telefonnummern.

Herunterladen und Installieren von Postman

Postman ist eine Desktopanwendung, mit der API-Anforderungen an jede beliebige HTTP-API gesendet werden können. Sie wird häufig zum Testen und Erkunden von APIs verwendet. Hier wird die aktuelle Desktopversion von der Postman-Website heruntergeladen. Von Postman sind Versionen für Windows, Mac und Linux verfügbar. Laden Sie daher die passende Version für Ihr Betriebssystem herunter. Öffnen Sie die heruntergeladene Anwendung. Daraufhin wird ein Startbildschirm angezeigt, in dem Sie aufgefordert werden, sich anzumelden oder ein Postman-Konto zu erstellen. Die Kontoerstellung ist optional und kann durch Klicken auf den Link „Skip and go to app“ (Überspringen und weiter zur App) übersprungen werden. Wenn Sie ein Konto erstellen, werden Ihre API-Anforderungseinstellungen in Postman gespeichert, sodass Sie Ihre Anforderungen auf anderen Computern wiederverwenden können.

Startbildschirm von Postman, auf dem Sie ein Konto erstellen oder die App ohne Kontoerstellung öffnen können

Nachdem Sie ein Konto erstellt oder die Kontoerstellung übersprungen haben, wird das Hauptfenster von Postman angezeigt.

Erstellen und Konfigurieren einer Postman-Sammlung

Anforderungen können von Postman auf verschiedene Arten strukturiert werden. Im Rahmen dieses Tutorials wird eine Postman-Sammlung erstellt. Wählen Sie hierzu auf der linken Seite der Anwendung die Schaltfläche „Collections“ (Sammlungen) aus:

Hauptbildschirm von Postman mit hervorgehobener Registerkarte „Collections“ (Sammlungen)

Klicken Sie anschließend auf „Create new Collection“ (Neue Sammlung erstellen), um den Erstellungsprozess zu starten. Im mittleren Bereich von Postman wird eine neue Registerkarte geöffnet. Geben Sie der Sammlung einen Namen Ihrer Wahl. Hier heißt die Sammlung „Azure Communication Services“:

Postman mit geöffneter Communication Services-Sammlung und hervorgehobenem Namen der Sammlung.

Nachdem Sie Ihre Sammlung erstellt und benannt haben, können Sie sie konfigurieren.

Hinzufügen von Sammlungsvariablen

Für die Authentifizierung sowie zur Vereinfachung von Anforderungen geben wir in der neu erstellten Communication Services-Sammlung zwei Sammlungsvariablen an. Diese Variablen sind für alle Anforderungen in Ihrer Communication Services-Sammlung verfügbar. Öffnen Sie die Registerkarte „Variables“ (Variablen) der Sammlung, um mit der Erstellung von Variablen zu beginnen.

Postman mit der Registerkarte „Variablen“ einer Communication Services-Sammlung.

Erstellen Sie auf der Registerkarte der Sammlung zwei Variablen:

„key“ (Schlüssel): Bei dieser Variablen handelt es sich um einen Ihrer Schlüssel auf der Schlüsselseite von Azure Communication Services im Azure-Portal. Beispiel: oW...A==.
„endpoint“ (Endpunkt): Bei dieser Variablen handelt es sich um Ihren Azure Communication Services-Endpunkt von der Schlüsselseite. Wichtig: Entfernen Sie den nachgestellten Schrägstrich. Beispiel: https://contoso.communication.azure.com.

Geben Sie diese Werte in die Spalte „Initial Value“ (Anfangswert) des Variablenbildschirms ein. Klicken Sie nach der Eingabe auf die Schaltfläche „Persist All“ (Alle speichern), die sich auf der rechten Seite direkt über der Tabelle befindet. Nach ordnungsgemäßer Konfiguration sollte der Postman-Bildschirm in etwa wie folgt aussehen:

Postman mit den ordnungsgemäß festgelegten Variablen einer Communication Services-Sammlung.

Weitere Informationen zu Variablen finden Sie in der entsprechenden Postman-Dokumentation.

Erstellen eines Voranforderungsskripts

Als Nächstes erstellen wir in Postman ein Voranforderungsskript. Ein Voranforderungsskript ist ein Skript, das vor jeder Anforderung in Postman ausgeführt wird, um Anforderungsparameter für Sie zu ändern oder anzupassen. Wir verwenden dieses Skript, um die HTTP-Anforderungen zu signieren, damit sie von Azure Communication Services autorisiert werden können. Weitere Informationen zu den Signaturanforderungen finden Sie in unserem Leitfaden zur Authentifizierung.

Dieses Skript wird innerhalb der Sammlung erstellt, sodass es für jede Anforderung in der Sammlung ausgeführt wird. Klicken Sie hierzu auf der Registerkarte „Collection“ (Sammlung) auf die Unterregisterkarte „Pre-request Script“ (Voranforderungsskript).

Postman mit Auswahl der Unterregisterkarte „Voranforderungsskript“ einer Communication Services-Sammlung.

Auf dieser Unterregisterkarte können Sie ein Voranforderungsskript erstellen, indem Sie es im Textbereich darunter eingeben. Es ist unter Umständen einfacher, das Skript zunächst in einem vollwertigen Code-Editor wie Visual Studio Code zu schreiben und es anschließend einzufügen. In diesem Tutorial werden die einzelnen Komponenten des Skripts näher erläutert. Falls Sie das Skript einfach nur in Postman kopieren und loslegen möchten, überspringen Sie diesen Abschnitt. Beginnen wir nun damit, das Skript zu schreiben.

Schreiben des Voranforderungsskripts

Als Erstes erstellen wir eine UTC-Zeichenfolge (koordinierte Weltzeit) und fügen sie dem HTTP-Header „Date“ (Datum) hinzu. Außerdem speichern wir diese Zeichenfolge in einer Variablen, um sie später beim Signieren zu verwenden:

// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});

Als Nächstes hashen wir den Anforderungstext mit SHA256 und platzieren ihn im Header x-ms-content-sha256. Da Postman einige Standardbibliotheken zum globalen Hashen und Signieren enthält, müssen wir sie nicht installieren oder voraussetzen:

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

Nun verwenden wir unsere zuvor angegebene Endpunktvariable, um den Wert für den HTTP-Hostheader zu ermitteln. Dies ist erforderlich, da der Hostheader erst nach der Verarbeitung des Skripts festgelegt wird:

// 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://','');

Nach Erstellung dieser Information können wir die Zeichenfolge erstellen, die für die HTTP-Anforderung signiert wird. Sie besteht aus mehreren zuvor erstellten Werten:

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

Zum Schluss müssen wir diese Zeichenfolge noch mit unserem Communication Services-Schlüssel signieren und der Anforderung im Header Authorization hinzufügen:

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

Das fertige Voranforderungsskript

Das fertige Voranforderungsskript sollte in etwa wie folgt aussehen:

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

Geben oder fügen Sie dieses fertige Skript in den Textbereich auf der Registerkarte „Pre-request Script“ (Voranforderungsskript) ein:

Postman mit eingegebenen Voranforderungsskript der Azure Communication Services-Sammlung.

Drücken Sie nach der Eingabe STRG+S, oder klicken Sie auf die Schaltfläche „Save“ (Speichern), um das Skript in der Sammlung zu speichern.

Schaltfläche zum Speichern des Voranforderungsskripts in Postman

Erstellen einer Anforderung in Postman

Nachdem nun alles eingerichtet ist, können wir in Postman eine Communication Services-Anforderung erstellen. Klicken Sie zunächst auf das Plussymbol (+) neben der Communication Services-Sammlung:

Plusschaltfläche in Postman

Dadurch wird in Postman eine neue Registerkarte für die Anforderung erstellt. Als Nächstes müssen wir uns um die Konfiguration kümmern. Wir senden eine Anforderung an die API zum Senden von SMS. Hilfreiche Informationen zu dieser API finden Sie in dieser Dokumentation. Gehen Sie zum Konfigurieren der Anforderung von Postman wie folgt vor:

Legen Sie zunächst den Anforderungstyp auf POST fest, und geben Sie {{endpoint}}/sms?api-version=2021-03-07 in das Feld für die Anforderungs-URL ein. Diese URL enthält die zuvor von uns erstellte Variable endpoint, um sie automatisch an Ihre Communication Services-Ressource zu senden.

Postman-Anforderung mit dem Typ „POST“ und korrekt festgelegter URL

Wählen Sie als Nächstes die Registerkarte „Body“ (Text) der Anforderung aus, und legen Sie das Optionsfeld darunter auf „raw“ (Unformatiert) fest. Legen Sie auf der rechten Seite das Dropdownfeld „Text“ auf „JSON“ fest:

Festlegen des Anforderungstexts auf „raw“ (Unformatiert) und „JSON“

Dadurch wird die Anforderung zum Senden und Empfangen von Informationen in einem JSON-Format konfiguriert.

Geben Sie im Textbereich darunter einen Anforderungstext im folgenden Format ein:

{
    "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 den Wert „from“ (Von) müssen Sie wie bereits erwähnt über das Azure Communication Services-Portal eine Telefonnummer beschaffen. Geben Sie sie ohne Leerzeichen und mit vorangestellter Landeskennzahl ein. Beispiel: +15555551234. Unter „message“ (Nachricht) können Sie eine beliebige Nachricht eingeben, die Sie senden möchten (beispielsweise Hello from Azure Communication Services). Der Wert „to“ (An) muss ein Telefon sein, auf das Sie Zugriff haben und das SMS-Nachrichten empfangen kann. Verwenden Sie beispielsweise Ihr eigenes Mobiltelefon.

Nach Abschluss der Eingabe muss die Anforderung in der zuvor erstellten Communication Services-Sammlung gespeichert werden. Dadurch wird sichergestellt, dass die zuvor erstellten Variablen und das zuvor erstellte Voranforderungsskript angewendet werden. Klicken Sie hierzu in der rechten oberen Ecke des Anforderungsbereichs auf die Schaltfläche „Save“ (Speichern).

Schaltfläche „Save“ (Speichern) für eine Postman-Anforderung

Daraufhin wird ein Dialogfenster angezeigt, in dem Sie zur Angabe des Namens und des Speicherorts der Anforderung aufgefordert werden. Sie können einen beliebigen Namen verwenden. Wichtig ist jedoch, dass Sie in der unteren Hälfte des Dialogfelds Ihre Communication Services-Sammlung auswählen:

Das Postman-Dialogfeld „Anforderung speichern“ mit ausgewählter Communication Services Sammlung.

Senden einer Anforderung

Nachdem nun alles eingerichtet ist, sollten Sie die Anforderung senden können und auf Ihrem Telefon eine SMS erhalten. Vergewissern Sie sich hierzu, dass die erstellte Anforderung ausgewählt ist, und klicken Sie dann auf der rechten Seite auf die Schaltfläche „Send“ (Senden):

Postman-Anforderung mit hervorgehobener Schaltfläche „Send“ (Senden)

Wenn alles funktioniert, sollte nun die Antwort von Communication Services (Statuscode 202) angezeigt werden:

Erfolgreich gesendete Postman-Anforderung mit Statuscode 202

Bei dem Mobiltelefon, zu dem die Nummer gehört, die Sie im Wert „to“ (An) angegeben haben, sollte außerdem eine SMS eingegangen sein. Sie verfügen nun über eine funktionsfähige Postman-Konfiguration, die mit Azure Communication Services kommunizieren und SMS-Nachrichten senden kann.

Nächste Schritte

Erkunden von Azure Communication Services-APIs Weitere Informationen zur Authentifizierung Weitere Informationen zu Postman

Weitere Möglichkeiten: