Schnellstart: Empfangen und Beantworten von SMS

Artikel
03/09/2023

SMS-Funktionen von Azure Communication Services bieten Entwicklern Optionen zum Verarbeiten empfangener SMS-Ereignisse. Die Ereignisse werden an Azure Event Grid bereitgestellt, das sofort einsatzbereite Integrationen für die Verarbeitung dieser Mithilfe von Webhooks, Azure Functions, Power Automate-/Logik-App-Connectors und mehr bereitstellt.

Nach dem Empfang können SMS-Nachrichten verarbeitet werden, um auf sie zu antworten oder sie einfach in einer Datenbank für den zukünftigen Zugriff zu protokollieren.

In diesem Schnellstart wird die Verarbeitung empfangener SMS-Ereignisse über Azure Functions mithilfe von Event Grid-Triggern und Connectors ohne Code für Power Automate/Logic Apps vorgestellt.

Das Ereignis SMSReceived, das generiert wird, wenn eine SMS an eine Azure Communication Services-Telefonnummer gesendet wird, wird wie folgt formatiert:

[{
  "id": "Incoming_20200918002745d29ebbea-3341-4466-9690-0a03af35228e",
  "topic": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/acse2e/providers/microsoft.communication/communicationservices/{communication-services-resource-name}",
  "subject": "/phonenumber/15555555555",
  "data": {
    "MessageId": "Incoming_20200918002745d29ebbea-3341-4466-9690-0a03af35228e",
    "From": "15555555555",
    "To": "15555555555",
    "Message": "Great to connect with Azure Communication Services events",
    "ReceivedTimestamp": "2020-09-18T00:27:45.32Z"
  },
  "eventType": "Microsoft.Communication.SMSReceived",
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "eventTime": "2020-09-18T00:27:47Z"
}]

Um mit dem Generieren der Ereignisse zu beginnen, müssen wir Azure Event Grid für unsere Azure Communication Services-Ressource konfigurieren.

Hinweis

Die Verwendung von Azure Event Grid verursacht zusätzliche Kosten. Weitere Informationen finden Sie unter Azure Event Grid-Preise.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Eine aktive Communication Services-Ressource und eine Verbindungszeichenfolge. Erstellen Sie eine Communication Services-Ressource.
Eine für SMS-Nachrichten geeignete Telefonnummer. Beziehen Sie eine Telefonnummer.
Aktivieren Sie die Event Grid-Ressource, die für Ihr Abonnement bereitgestellt ist. Weitere Informationen finden Sie in den Anweisungen.

Event Grid bietet sofort einsatzbereite Unterstützung für Azure Functions und erleichtert das Einrichten eines Ereignislisteners, ohne sich mit der Komplexität des Parsens von Headern oder dem Debuggen von Webhooks befassen zu müssen. Mit dem sofort einsatzbereiten Trigger können wir eine Azure-Funktion einrichten, die jedes Mal ausgeführt wird, wenn ein Ereignis erkannt wird, das mit dem Trigger übereinstimmt. In diesem Dokument konzentrieren wir uns auf Trigger für empfangen SMS.

Einrichten unserer lokalen Umgebung

Installieren Sie die Azure Functions-Erweiterung mithilfe von Visual Studio Code.
Erstellen Sie mit der Erweiterung eine Azure-Funktion, indem Sie diese Anweisungen befolgen.

Konfigurieren Sie die Funktion mit den folgenden Anweisungen:
- Sprache: TypeScript
- Vorlage: Azure Event Grid-Trigger
- Funktionsname: Benutzerdefiniert
Nach der Erstellung wird eine in Ihrem Verzeichnis erstellte Funktion wie folgt angezeigt:
```
import { AzureFunction, Context } from "@azure/functions"

const eventGridTrigger: AzureFunction = async function (context: Context, eventGridEvent: any): Promise<void> {
    context.log(eventGridEvent);

};

export default eventGridTrigger;
```

Konfigurieren der Azure-Funktion zum Empfangen eines SMS-Ereignisses

Konfigurieren Sie die Azure-Funktion so, dass Werte aus dem Ereignis geparst werden, z. B. wer es gesendet hat, an welche Nummer und der Inhalt der Nachricht.


import { AzureFunction, Context } from "@azure/functions"

const eventGridTrigger: AzureFunction = async function (context: Context, eventGridEvent: any): Promise<void> {
   context.log(eventGridEvent);
   const to = eventGridEvent['data']['to'];
   const from = eventGridEvent['data']['from'];
   const message = eventGridEvent['data']['message'];

};

export default eventGridTrigger;

An diesem Punkt haben Sie den Empfang einer SMS über Ereignisse erfolgreich behandelt. Nun reichen die Möglichkeiten, was mit diesem Ereignis zu tun ist, von der bloßen Protokollierung bis hin zum Antworten darauf. Im nächsten Abschnitt konzentrieren wir uns auf das Antworten auf die empfangene SMS. Wenn Sie nicht auf die SMS antworten möchten, springen Sie zum nächsten Abschnitt über die lokale Ausführung der Funktion.

Antworten auf die SMS

Um auf die eingehende SMS zu antworten, verwenden wir die Azure Communication Service-SMS-Funktionen zum Senden von SMS. Wir beginnen mit dem Aufrufen des SmsClient und initialisieren ihn mit dem connection string für unsere Ressource. Sie können die Verbindungszeichenfolge entweder direkt in den Code einfügen oder sie in Ihrer Datei local.settings.json in Ihrem Azure-Funktionsverzeichnis unter „Werte“ platzieren.


{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "ACS_CONNECTION_STRING": "<<CONNECTION STRING>>"
  }
}

Anschließend erstellen wir eine SMS, die basierend auf den Werten to und from aus dem empfangenen Ereignis gesendet werden soll.

import { AzureFunction, Context } from "@azure/functions"
import { SmsClient } from "@azure/communication-sms";

const connectionString = process.env.ACS_CONNECTION_STRING; //Replace with your connection string

const eventGridTrigger: AzureFunction = async function (context: Context, eventGridEvent: any): Promise<void> {
    context.log(eventGridEvent);
    const to = eventGridEvent['data']['to'];
    const from = eventGridEvent['data']['from'];
    const message = eventGridEvent['data']['message'];

    const smsClient = new SmsClient(connectionString);

    const sendResults = await smsClient.send({
        from: to,
        to: [from],
        message: "Message received successfully. Will respond shortly."
    });

};

export default eventGridTrigger;

Von hier aus sind die Möglichkeiten endlos. Von der Antwort auf eine Nachricht mit einer vorgefertigten Antwort über das Hinzufügen eines Bots bis hin zum einfachen Speichern von Antworten können Sie den Code im letzten Schritt entsprechend anpassen.

Lokales Ausführen

Um die Funktion lokal auszuführen, drücken Sie F5 in Visual Studio Code. Wir verwenden ngrok, um unsere lokal ausgeführte Azure-Funktion mit Azure Event Grid zu verbinden.

Sobald die Funktion ausgeführt wird, konfigurieren wir ngrok. (Sie müssen für Ihre Umgebung ngrok herunterladen.)
```
ngrok http 7071
```
Kopieren Sie den bereitgestellten ngrok-Link, an dem Ihre Funktion ausgeführt wird.
Konfigurieren Sie SMS-Ereignisse über Event Grid in Ihrer Azure Communication Services-Ressource. Dazu verwenden wir die Azure CLI. Sie benötigen die Ressourcen-ID für Ihre Azure Communication Services Ressource, die Sie im Azure-Portal finden. (Die Ressourcen-ID sieht in etwa wie folgt aus: /subscriptions/<<AZURE SUBSCRIPTION ID>>/resourceGroups/<<RESOURCE GROUP NAME>>/providers/Microsoft.Communication/CommunicationServices/<<RESOURCE NAME>>)
```
az eventgrid event-subscription create --name "<<EVENT_SUBSCRIPTION_NAME>>" --endpoint-type webhook --endpoint "<<NGROK URL>> " --source-resource-id "<<RESOURCE_ID>>"  --included-event-types Microsoft.Communication.SMSReceived 
```
Nachdem alles eingebunden ist, testen Sie den Flow, indem Sie eine SMS an die Telefonnummer senden, die Sie für Ihre Azure Communication Services-Ressource verwenden. Sie sollten die Konsolenprotokolle auf Ihrem Terminal sehen, in dem die Funktion ausgeführt wird. Wenn Sie den Code hinzugefügt haben, um auf die SMS zu antworten, sollten Sie sehen, dass diese SMS an Sie zurückgesendet wird.

In Azure bereitstellen

Um die Azure-Funktion in Azure bereitzustellen, müssen Sie diese Anweisungen befolgen. Nach der Bereitstellung konfigurieren wir Event Grid für die Azure Communication Services-Ressource. Mit der URL für die bereitgestellte Azure-Funktion (URL kann im Azure-Portal unter der Funktion gefunden werden) führen wir den folgenden Befehl aus:


az eventgrid event-subscription update --name "<<EVENT_SUBSCRIPTION_NAME>>" --endpoint-type azurefunction --endpoint "<<AZ FUNCTION URL>> " --source-resource-id "<<RESOURCE_ID>>"

Da wir das Ereignisabonnement aktualisieren, das wir für lokale Tests erstellt haben, müssen wir sicherstellen, dass Sie denselben Ereignisabonnementnamen verwenden wie oben.

Sie können dies testen, indem Sie eine SMS an die Telefonnummer senden, die Sie über die Azure Communication Services-Ressource erworben haben.

Logic Apps und Power Automate stellen sofort einsatzbereite Connectors bereit, um Ereignisse zu verarbeiten, die von Azure Communication Services über Event Grid generiert werden. Logic Apps und Power Automate stellen beide den gleichen Satz von Connectors zur Verfügung. Es liegt an Ihnen, zu entscheiden, was Sie bevorzugen, lesen Sie dazu die Unterschiede zwischen den Diensten, um Ihre Entscheidung zu treffen.

Behandeln von Ereignissen mit dem Event Grid-Connector

Erstellen Sie zunächst einen neuen Flow in Ihrer bevorzugten Umgebung. Wählen Sie den When a resource event occurs-Trigger für die ersten Schritte aus.
Nun konfigurieren wir diesen. Der Connector erfordert, dass Sie ein Abonnement bereitstellen, das Sie verwenden möchten. (Es sollte dasselbe Abonnement sein, in dem sich Ihre Azure Communication Services-Ressource befindet). Geben Sie den Typ der Ressource an. Wählen Sie in diesem Fall Microsoft.Communication.CommunicationServices aus. Anschließend müssen Sie einen Ressourcennamen für die Azure Communication Services-Ressource angeben, mit der eine Verbindung hergestellt werden soll. Abschließend müssen wir die Ereignistypen auswählen, die wir empfangen möchten, in diesem Fall: Microsoft.Communication.SMSReceived.

Der Connector richtet das Ereignisabonnement automatisch in Ihrem Namen ein und konfiguriert die Ereignisse, die er empfangen möchte.

Um uns das Leben später zu erleichtern, fügen Sie einen Parse JSON connector hinzu, um die Antwort zu verarbeiten, die vom Event Grid-Connector stammt. Konfigurieren Sie den Connector so, dass er das Body-Objekt aus dem Event Grid-Connector übernimmt und mit dem erwarteten Schema für das Ereignis abgleicht:

Beispielschema (öffentlich sichtbar)


    {
        "properties": {
            "data": {
                "properties": {
                    "From": {
                        "type": "string"
                    },
                    "Message": {
                        "type": "string"
                    },
                    "MessageId": {
                        "type": "string"
                    },
                    "ReceivedTimestamp": {
                        "type": "string"
                    },
                    "To": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "dataVersion": {
                "type": "string"
            },
            "eventTime": {
                "type": "string"
            },
            "eventType": {
                "type": "string"
            },
            "id": {
                "type": "string"
            },
            "metadataVersion": {
                "type": "string"
            },
            "subject": {
                "type": "string"
            },
            "topic": {
                "type": "string"
            }
        },
        "type": "object"
    }

Screenshot des JSON-Connectors zum Parsen.

An diesem Punkt haben Sie das SMS-Ereignis erfolgreich verarbeitet. Sie haben dann mehrere Möglichkeiten, was Sie damit tun wollen, von der Protokollierung des Ereignisses bis hin zum Beantworten der SMS. Im Kontext dieses Dokuments zeigen wir, wie darauf geantwortet wird. Lesen Sie weiter, um zu erfahren, wie Sie auf die SMS antworten.

Antworten auf die SMS

Beginnen Sie mit dem Hinzufügen des SMS-Connectors zu unserem Flow, und konfigurieren Sie ihn mit den Informationen für unsere Azure Communication Services-Ressource. Es ermöglicht dem Connector, auf die Ressource zuzugreifen und die SMS in unserem Namen zu senden. Sie benötigen die connection string für Ihre Ressource.
Als Nächstes konfigurieren wir den Connector mit den Informationen für den Absender und den Empfänger. Wir verwenden die Informationen aus dem empfangenen Ereignis, um sie aufzufüllen. Drehen Sie die Nummern to und from um, um eine SMS zurück an den ursprünglichen Absender zu senden. Fügen Sie schließlich eine Nachricht hinzu.

Jetzt können Sie den Flow speichern und testen, indem Sie eine SMS an die Telefonnummer senden, die Ihrer Azure Communication Services-Ressource zugeordnet ist. Sie sollten eine SMS zurück erhalten.

Von hier aus sind die Möglichkeiten endlos. Vom Antworten auf eine Nachricht mit einer vorgefertigten Antwort über das Hinzufügen eines Bots bis hin zum einfachen Speichern von Antworten können Sie dem Flow weitere Logik hinzufügen.

Bereinigen von Ressourcen

Wenn Sie ein Communication Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind. Weitere Informationen zum Bereinigen von Ressourcen finden Sie hier.

Gebührenfreie Überprüfung

Wenn Sie eine neue gebührenfreie Nummer haben und ein hohes Volumen an SMS-Nachrichten senden oder SMS-Nachrichten an kanadische Telefonnummern senden möchten, erfahren Sie hier, wie Sie Ihre gebührenfreie Nummer verifizieren können.

Nächste Schritte

In diesem Schnellstart haben Sie erfahren, wie Sie SMS-Nachrichten mit Azure Communication Services senden.

Senden einer SMS

Telefonnummerntypen

Weitere Informationen zu SMS

Freigeben über

Schnellstart: Empfangen und Beantworten von SMS

Voraussetzungen

Einrichten unserer lokalen Umgebung

Konfigurieren der Azure-Funktion zum Empfangen eines SMS-Ereignisses

Antworten auf die SMS

Lokales Ausführen

In Azure bereitstellen

Behandeln von Ereignissen mit dem Event Grid-Connector

Antworten auf die SMS

Bereinigen von Ressourcen

Gebührenfreie Überprüfung

Nächste Schritte

Feedback

Zusätzliche Ressourcen