Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
In diesem Lernprogramm richten Sie Postman ein, um mithilfe von HTTP eine Anforderung an Azure Communication Services zu senden. Am Ende dieses Lernprogramms senden Sie erfolgreich eine SMS-Nachricht (Short Message Service) mithilfe von Kommunikationsdiensten und Postman. Anschließend können Sie Postman verwenden, um andere APIs in Kommunikationsdiensten zu erkunden.
In diesem Tutorial lernen Sie Folgendes:
- Laden Sie Postman herunter.
- Richten Sie Postman ein, um HTTP-Anforderungen zu signieren.
- Richten Sie eine Anfrage an die Kommunikationsdienste-SMS-API, um eine Nachricht zu übermitteln.
Prerequisites
- Ein Azure-Konto mit einem aktiven Abonnement. Wenn Sie nicht über ein Azure-Abonnement verfügen, können Sie kostenlos ein 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. Wenn Sie nicht über eine Ressource verfügen, sehen Sie unter Erstellen einer Ressource für Kommunikationsdienste nach.
- Eine Kommunikationsdienste-Telefonnummer, die SMS-Nachrichten senden kann. Informationen zum Abrufen einer Telefonnummer finden Sie unter " Abrufen einer Telefonnummer".
Herunterladen und Installieren von Postman
Postman ist eine Desktopanwendung, die API-Anforderungen für jede HTTP-API durchführen kann. Postman wird häufig zum Testen und Untersuchen von APIs verwendet. In diesem Lernprogramm laden Sie die neueste Desktopversion von der Postman-Website herunter. Postman verfügt über Versionen für Windows, Mac und Linux. Laden Sie daher die version herunter, die für Ihr Betriebssystem geeignet ist.
Nachdem der Download abgeschlossen ist, öffnen Sie die Anwendung. Auf dem Startbildschirm werden Sie aufgefordert, sich anzumelden oder ein Postman-Konto zu erstellen. Das Erstellen eines Kontos ist optional, und Sie können es überspringen, indem Sie "Überspringen" auswählen und zur App wechseln. Beim Erstellen eines Kontos werden Ihre API-Anforderungseinstellungen in Postman gespeichert. Anschließend können Sie Ihre Anfragen auf anderen Computern abrufen.
Nachdem Sie ein Konto erstellt oder den Schritt übersprungen haben, wird nun der Hauptbildschirm von Postman angezeigt.
Erstellen und Konfigurieren einer Postman-Sammlung
Postman kann Anfragen auf viele Arten organisieren. Für die Zwecke dieses Lernprogramms erstellen Sie eine Postman-Sammlung. Um diese Aufgabe zu erledigen, wählen Sie auf der linken Seite der Anwendung "Sammlungen" aus.
Wählen Sie "Neue Sammlung erstellen" aus, um den Vorgang zum Erstellen einer Sammlung zu starten. Eine neue Registerkarte wird im mittleren Bereich von Postman geöffnet, in dem Sie die Sammlung benennen. Hier heißt die Sammlung Azure Communication Services.
Nachdem Sie Ihre Sammlung erstellt und benannt haben, können Sie sie konfigurieren.
Hinzufügen von Sammlungsvariablen
Um die Authentifizierung zu verarbeiten und Anforderungen zu vereinfachen, geben Sie zwei Sammlungsvariablen in der neu erstellten Communication Services-Auflistung an. Diese Variablen sind für alle Anforderungen in Ihrer Sammlung verfügbar. Um mit dem Erstellen von Variablen zu beginnen, wählen Sie die Registerkarte "Variablen " aus.
Erstellen Sie auf der Registerkarte "Sammlungen " zwei Variablen:
-
key: Diese Variable sollte einer Ihrer Schlüssel auf ihrer Kommunikationsdienste-Schlüsselseite im Azure-Portal sein. Beispiel ist
oW...A==. -
Endpunkt: Diese Variable sollte Ihre Communication Services Endpunkte auf der Seite Schlüssel sein. Stellen Sie sicher, dass Sie den nachgestellten Schrägstrich entfernen. Beispiel ist
https://contoso.communication.azure.com.
Geben Sie auf der Registerkarte "Variablen " diese Werte in die Spalte "Anfangswert " ein. Wählen Sie Alle beibehalten in der oberen rechten Ecke aus. Wenn sie richtig konfiguriert ist, sollte Ihr Postman-Bereich ungefähr wie die folgende Abbildung aussehen.
Weitere Informationen zu Variablen finden Sie in der Postman-Dokumentation.
Erstellen eines Vorabanforderungsskripts
Der nächste Schritt besteht darin, ein Vorabquest-Skript in Postman zu erstellen. Ein Prerequest-Skript wird vor jeder Anfrage in Postman ausgeführt. Sie kann Anforderungsparameter für Sie modifizieren oder ändern. Sie verwenden dieses Skript, um Ihre HTTP-Anforderungen zu signieren, damit Kommunikationsdienste sie autorisieren können. Weitere Informationen zu Signaturanforderungen finden Sie in unserem Leitfaden zur Authentifizierung.
Sie erstellen dieses Skript in der Sammlung, sodass es für jede Anforderung in der Sammlung ausgeführt wird. Um diesen Schritt auszuführen, wählen Sie auf der Registerkarte "Sammlungen " die Option "Skript vorab anfordern" aus.
Jetzt erstellen Sie ein Voranforderungsskript, indem Sie es in den Textbereich eingeben. Dieser Schritt ist möglicherweise einfacher, wenn Sie ihn in einem vollständigen Code-Editor wie Visual Studio Code schreiben, bevor Sie ihn einfügen. Dieses Lernprogramm führt Sie durch jeden Teil des Skriptprozesses. Springen Sie zum Ende, wenn Sie das Skript in Postman kopieren und dann direkt loslegen möchten. Beginnen wir nun damit, das Skript zu schreiben.
Schreiben Sie das Skript "Prerequest"
Der erste Schritt besteht darin, eine UTC-Zeichenfolge (Coordinated Universal Time) zu erstellen und sie dem Date HTTP-Header hinzuzufügen. Speichern Sie 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 Sie den Anforderungstext mithilfe von SHA 256, und platzieren Sie ihn in der x-ms-content-sha256 Kopfzeile. Postman enthält einige Standardbibliotheken für Hashing und Globales Signieren, sodass Sie sie nicht installieren oder erfordern müssen.
// Hash the request body by 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
});
Verwenden Sie die zuvor angegebene Endpunktvariable, um den Wert für den HTTP-Hostheader zu ermitteln. Der Hostheader wird erst festgelegt, nachdem dieses Skript verarbeitet wurde.
// 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://','');
Mit diesen Informationen können Sie nun die Zeichenfolge erstellen, die Sie für die HTTP-Anforderung signieren. Die Zeichenfolge 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, by using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;
Schließlich signieren Sie diese Zeichenfolge mithilfe Ihres Kommunikationsdiensteschlüssels. Fügen Sie dann diesen Schlüssel zu Ihrer Anforderung im Authorization Header hinzu.
// 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 letzte Skript für die Vorabanforderung
Das endgültige Skript für die Voranforderung sollte etwa wie in diesem Beispiel 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 by 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, by 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 Sie dieses endgültige Skript in den Textbereich auf der Registerkarte "Skript vor Anforderung " ein, oder fügen Sie es ein.
Nachdem Sie sie eingegeben haben, wählen Sie STRG+S aus, oder wählen Sie "Speichern" aus, um das Skript in der Sammlung zu speichern.
Erstellen einer Anforderung in Postman
Nachdem alles eingerichtet ist, können Sie eine Kommunikationsdiensteanfrage in Postman erstellen. Um zu beginnen, wählen Sie das Pluszeichen (+) neben der Communication Services-Auflistung aus.
Sie haben eine neue Registerkarte für Ihre Anforderung in Postman erstellt, und jetzt müssen Sie sie konfigurieren. Sie stellen eine Anforderung an die SMS Send-API vor. Lesen Sie daher unbedingt die Dokumentation für diese API, um Unterstützung zu erhalten. Konfigurieren wir die Postman-Anforderung.
Legen Sie zunächst den Anforderungstyp fest POST , und geben Sie {{endpoint}}/sms?api-version=2021-03-07 ihn in das Anforderungs-URL-Feld ein. Diese URL verwendet die zuvor erstellte endpoint Variable, um sie automatisch an Ihre Kommunikationsdiensteressource zu senden.
Wählen Sie auf der Registerkarte Body der Anforderung raw aus. Wählen Sie in der Dropdownliste auf der rechten Seite JSON aus.
Sie haben die Anforderung zum Senden und Empfangen von Informationen in einem JSON-Format konfiguriert.
Geben Sie im Textbereich einen Anforderungstext in das folgende 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 from Wert müssen Sie eine Telefonnummer im Kommunikationsdiensteportal abrufen, wie bereits erwähnt. Geben Sie ihn ohne Leerzeichen und ein Präfix Ihres Ländercodes ein. Beispiel ist +15555551234. Ihr message kann alles Mögliche sein, was Sie senden möchten, aber Hello from Azure Communication Services ist ein gutes Beispiel. Der to Wert sollte ein Telefon sein, auf das Sie Zugriff haben, damit Sie SMS-Nachrichten empfangen können. Die Verwendung Ihres eigenen Mobiltelefons ist eine gute Idee.
Speichern Sie diese Anforderung in der zuvor erstellten Kommunikationsdienstesammlung. Mit diesem Schritt wird sichergestellt, dass die Zuvor erstellten Variablen und das Vorabanforderungsskript aufgenommen werden. Wählen Sie oben rechts im Anforderungsbereich " Speichern" aus.
Im daraufhin angezeigten Dialogfeld werden Sie gefragt, wie Sie die Anforderung nennen möchten und wo Sie sie speichern möchten. Sie können es beliebig benennen, aber stellen Sie sicher, dass Sie Ihre Kommunikationsdienste-Sammlung in der unteren Hälfte des Dialogfelds auswählen.
Senden einer Anforderung
Nachdem alles eingerichtet ist, können Sie die Anfrage senden und eine SMS-Nachricht auf Ihrem Telefon erhalten. Um diesen Schritt auszuführen, stellen Sie sicher, dass Ihre Anforderung ausgewählt ist, und wählen Sie dann "Senden" aus.
Wenn alles gut gelaufen ist, wird die Antwort von Communication Services angezeigt, bei der es sich um einen Statuscode von 202 handelt.
Das Mobiltelefon, das die im Wert angegebene to Nummer besitzt, hat auch eine SMS-Nachricht erhalten. Sie verfügen jetzt über eine funktionale Postman-Konfiguration, die mit Kommunikationsdiensten sprechen und SMS-Nachrichten senden kann.