Freigeben über

Azure Web PubSub-Triggerbindung für Azure-Funktionen

Verwenden Sie den Azure Web PubSub-Trigger, um Clientereignisse vom Azure Web PubSub-Dienst zu behandeln.

Das Triggerendpunktmuster lautet wie folgt, das im Web PubSub-Dienst (Portal: Einstellungen -> Ereignishandler -> URL-Vorlage) festgelegt werden sollte. Im Endpunktmuster ist der Abfrageteil code=<API_KEY> aus SicherheitsgründenERFORDERLICH, wenn Sie eine Azure-Funktions-App verwenden. Den Schlüssel finden Sie im Azure-Portal. Suchen Sie nach dem Bereitstellen der Funktions-App in Azure nach Ihrer Funktions-App-Ressource, und navigieren Sie zu Functions ->App-Schlüssel ->Systemschlüssel ->webpubsub_extension. Wenn Sie mit lokalen Funktionen arbeiten, wird dieser Schlüssel jedoch nicht benötigt.

<Function_App_Url>/runtime/webhooks/webpubsub?code=<API_KEY>

Screenshot des Abrufens der Systemschlüssel der Funktion.

Beispiel

Das folgende Beispiel zeigt, wie Benutzerereignisse von Clients behandelt werden.

[Function("Broadcast")]
public static void Run(
[WebPubSubTrigger("<hub>", WebPubSubEventType.User, "message")] UserEventRequest request, ILogger log)
{
    log.LogInformation($"Request from: {request.ConnectionContext.UserId}");
    log.LogInformation($"Request message data: {request.Data}");
    log.LogInformation($"Request message dataType: {request.DataType}");
}

Die WebPubSubTrigger-Bindung unterstützt in Synchronisierungsszenarien auch Rückgabewerte, z. B. bei Connect-Ereignissen vom System oder von Benutzer*innen, bei denen der Server die Clientanforderung überprüfen und ablehnen oder Nachrichten direkt an den Aufrufer senden kann. Das Connect-Ereignis berücksichtigt ConnectEventResponse und EventErrorResponse, das Benutzerereignis berücksichtigt UserEventResponse und EventErrorResponse. Die REST-Typen, die nicht zum aktuellen Szenario passen, werden ignoriert.

[Function("Broadcast")]
public static UserEventResponse Run(
[WebPubSubTrigger("<hub>", WebPubSubEventType.User, "message")] UserEventRequest request)
{
    return new UserEventResponse("[SYSTEM ACK] Received.");
}

const { app, trigger } = require('@azure/functions');

const wpsTrigger = trigger.generic({
    type: 'webPubSubTrigger',
    name: 'request',
    hub: '<hub>',
    eventName: 'message',
    eventType: 'user'
});

app.generic('message', {
    trigger: wpsTrigger,
    handler: async (request, context) => {
        context.log('Request from: ', request.connectionContext.userId);
        context.log('Request message data: ', request.data);
        context.log('Request message dataType: ', request.dataType);
    }
});

Die WebPubSubTrigger-Bindung unterstützt in Synchronisierungsszenarien auch Rückgabewerte, z. B. bei Connect-Ereignissen vom System oder von Benutzer*innen, bei denen der Server die Clientanforderung überprüfen und ablehnen oder Nachrichten direkt an den Anforderungsclient senden kann. In der schwach typisierten Sprache JavaScript erfolgt eine Deserialisierung in Bezug auf die Objektschlüssel. Und EventErrorResponse hat die höchste Priorität im Vergleich zu Restobjekten, d. h., wenn code sie sich in der Rückgabe befindet, dann wird sie analysiert EventErrorResponse.

app.generic('message', {
    trigger: wpsTrigger,
    handler: async (request, context) => {
          return {
              "data": "ack",
              "dataType" : "text"
          };
    }
});

Hinweis

Vollständige Beispiele für diese Sprache stehen aus.

Hinweis

Die Web PubSub-Erweiterungen für Java werden noch nicht unterstützt.

Konfiguration

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json festlegen.

Eigenschaft von „function.json“ Attributeigenschaft BESCHREIBUNG
Typ Nicht zutreffend Erforderlich – muss auf webPubSubTrigger festgelegt sein.
Richtung Nicht zutreffend Erforderlich – muss auf in festgelegt sein.
Name Nicht zutreffend Erforderlich – der Variablenname, der im Funktionscode für den Parameter verwendet wird, der die Ereignisdaten empfängt.
Nabe Drehscheibe Dieser Wert ist erforderlich und muss auf den Namen des Web PubSub-Hubs festgelegt werden, damit die Funktion ausgelöst werden kann. Das Festlegen des Werts als einer mit höherer Priorität wird im Attribut unterstützt. Alternativ kann dies in den App-Einstellungen als globaler Wert festgelegt werden.
eventType WebPubSubEventType Dieser Wert ist erforderlich und muss auf den Ereignistyp Nachrichten festgelegt werden, damit die Funktion ausgelöst wird. Der Wert muss user oder system sein.
eventName Ereignisname Dieser Wert ist erforderlich und muss auf das Nachrichtenereignis festgelegt werden, damit die Funktion ausgelöst wird.

Für system den Ereignistyp sollte der Ereignisname in connect, connected, disconnected.

Bei benutzerdefinierten Unterprotocols lautet messageder Ereignisname .

Für vom System unterstützte Unterprotocol json.webpubsub.azure.v1.ist der Ereignisname ein benutzerdefinierter Ereignisname.
clientProtocols ClientProtocols Optional – gibt an, welches Clientprotokoll die Web PubSub-Triggerfunktionen auslösen kann.

Die folgenden Werte für die Groß-/Kleinschreibung sind gültig:
allAkzeptiert alle Clientprotokolle. Standardwert.
webPubSub: Akzeptiert nur Web PubSub-Protokolle.
mqtt: Akzeptiert nur MQTT-Protokolle.
Verbindung Verbindung Optional: Name von App-Einstellungen oder einer Einstellungssammlung, der den Upstream-Azure Web PubSub-Dienst angibt. Der Wert wird für die Signaturüberprüfung verwendet. Und der Wert wird standardmäßig automatisch mit App-Einstellungen WebPubSubConnectionString aufgelöst. Und null bedeutet, dass die Validierung nicht benötigt wird und immer erfolgreich ist.

Wichtig

Um optimale Sicherheit zu gewährleisten, sollte Ihre Funktions-App verwaltete Identitäten verwenden, wenn Sie eine Verbindung mit dem Web PubSub-Dienst herstellen, anstatt eine Verbindungszeichenfolge zu verwenden, die einen freigegebenen geheimen Schlüssel enthält. Weitere Informationen finden Sie unter Autorisieren einer verwalteten Identitätsanforderung mithilfe der Microsoft Entra-ID.

Verwendungen

In C# ist WebPubSubEventRequest ein vom Typ erkannter Bindungsparameter, und Restparameter sind an den Parameternamen gebunden. Überprüfen Sie die folgende Tabelle auf verfügbare Parameter und Typen.

In schwach typografischer Sprache wie JavaScript wird verwendet, namefunction.json um das Triggerobjekt in Bezug auf die folgende Zuordnungstabelle zu binden. Hierbei wird dataType in function.json berücksichtigt, damit die Nachricht richtig konvertiert wird, wenn name auf data als Bindungsobjekt für die Auslösereingabe festgelegt ist. Alle Parameter können aus context.bindingData.<BindingName> gelesen werden und werden in JObject konvertiert.

Bindungsname Bindungstyp BESCHREIBUNG Eigenschaften
Anfrage WebPubSubEventRequest Beschreibt die Upstreamanforderung Die Eigenschaft unterscheidet sich von verschiedenen Ereignistypen, einschließlich abgeleiteter Klassen ConnectEventRequest, , MqttConnectEventRequest, ConnectedEventRequest, MqttConnectedEventRequest, UserEventRequest, DisconnectedEventRequestund MqttDisconnectedEventRequest.
connectionContext WebPubSubConnectionContext Allgemeine Anforderungsinformationen EventType, EventName, Hub, ConnectionId, UserId, Headers, Origin, Signature, States
Daten BinaryData,string,,Streambyte[] Anfordern von Nachrichtendaten vom Client im message-Benutzerereignis -
Datentyp WebPubSubDataType Der Datentyp für Anforderungsnachrichten, der binary, text und json unterstützt -
Ansprüche IDictionary<string, string[]> Benutzeransprüche in der connect-Systemanforderung -
Anfrage IDictionary<string, string[]> Benutzerabfrage in der connect-Systemanforderung -
Unterprotocols IList<string> Verfügbare Unterprotokolle in einer connect-Systemanforderung -
Clientzertifikate IList<ClientCertificate> Eine Liste der Zertifikatfingerabdrücke von Clients in der connect-Systemanforderung -
Grund string Grund in der disconnected-Systemanforderung -

Wichtig

In C# MÜSSEN Parameter mit mehreren unterstützten Typen zuerst angegeben werden, z. B. request oder data, anders als der BinaryData-Standardtyp, damit die Funktionsbindung korrekt ist.

Rückgabeantwort

WebPubSubTrigger berücksichtigt die vom Kunden zurückgegebene Antwort für synchrone Ereignisse für connect und das Benutzerereignis. Nur eine passende Antwort wird an den Dienst zurückgesendet, ansonsten wird sie ignoriert. Darüber hinaus unterstützt das Rückgabeobjekt WebPubSubTrigger Benutzer*innen für SetState() und ClearStates(), um die Metadaten für die Verbindung zu verwalten. Und die Erweiterung führt die Ergebnisse des Rückgabewerts mit den ursprünglichen Ergebnissen aus der Anforderung WebPubSubConnectionContext.States zusammen. Der Wert im vorhandenen Schlüssel wird überschrieben, und der Wert im neuen Schlüssel wird hinzugefügt.

Rückgabetyp BESCHREIBUNG Eigenschaften
ConnectEventResponse Antwort auf ein connect-Ereignis Gruppen, Rollen, UserId, Subprotocol
UserEventResponse Antwort auf ein Benutzerereignis Datentyp, Daten
EventErrorResponse Fehlerantwort für das Synchronisierungsereignis Code, Fehlermeldung
*WebPubSubEventResponse Basisantworttyp der unterstützten Typen, der bei unsicheren Rückgaben verwendet wird -