Azure Web PubSub-Trigger und -Bindungen für Azure Functions

Artikel
07/24/2024

In dieser Referenz wird die Verarbeitung von Web PubSub-Ereignissen in Azure Functions erläutert.

Web PubSub ist ein von Azure verwalteter Dienst, der Entwicklern die einfache Erstellung von Webanwendungen mit Echtzeitfeatures und einem Veröffentlichen-Abonnieren-Muster ermöglicht.

Aktion	type
Ausführen einer Funktion, wenn Nachrichten vom Dienst eingehen	Triggerbindung
Binden der Anforderung an das Zielobjekt unter dem HTTP-Trigger für Aushandlungs- und Upstreamanforderungen	Eingabebindung
Aufrufen von Dienstaktionen	Ausgabebindung

Quellcode | Paket | API-Referenzdokumentation | Produktdokumentation | Beispiele

Hinzufügen zu Ihrer Funktions-App

Für das Arbeiten mit Triggern und Bindungen müssen Sie auf das richtige Paket verweisen. Das NuGet-Paket wird für .NET-Klassenbibliotheken verwendet, während das Erweiterungspaket für alle anderen Anwendungstypen verwendet wird.

Sprache	Hinzufügen nach...	Hinweise
C#	Installieren desNuGet-Pakets, Vorabversion
C#-Skript, JavaScript, Python, PowerShell	Explizites Installieren von Erweiterungen, Verwenden von Erweiterungsbündeln	Die Erweiterung für Azure-Tools wird zur Verwendung mit Visual Studio Code empfohlen.
C#-Skript (nur online im Azure-Portal)	Hinzufügen einer Bindung	Informationen zum Aktualisieren vorhandener Bindungserweiterungen, ohne Ihre Funktions-App erneut veröffentlichen zu müssen, finden Sie unter Aktualisieren Ihrer Erweiterungen.

Wichtige Begriffe

Diagramm: Workflow des Azure Web PubSub-Diensts mit Nutzung von Funktions-Apps.

(1)–(2): WebPubSubConnection-Eingabebindung mit HttpTrigger zum Generieren einer Clientverbindung.

(3)–(4): WebPubSubTrigger-Triggerbindung oder WebPubSubContext-Eingabebindung mit HttpTrigger zum Verarbeiten von Dienstanforderungen.

(5)–(6): WebPubSub-Ausgabebindung zum Anfordern einer Aktion eines Diensts.

Triggerbindung

Verwenden Sie den Funktionstrigger, um Anforderungen vom Azure Web PubSub-Dienst zu verarbeiten.

WebPubSubTrigger wird verwendet, wenn Sie dienstseitige Anforderungen verarbeiten müssen. Das Muster des Triggerendpunkts, das im Web PubSub-Dienst festgelegt werden sollte, würde wie folgt aussehen (Portal: Settings -> Event Handler -> URL Template (Einstellungen -> Ereignishandler -> URL-Vorlage)). Im Endpunktmuster ist der Abfrageteil code=<API_KEY> aus Sicherheitsgründen ERFORDERLICH, 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

[FunctionName("WebPubSubTrigger")]
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. Wenn EventErrorResponse zurückgegeben wird, wird die Clientverbindung vom Dienst getrennt.

[FunctionName("WebPubSubTriggerReturnValueFunction")]
public static UserEventResponse Run(
    [WebPubSubTrigger("hub", WebPubSubEventType.User, "message")] UserEventRequest request)
{
    return request.CreateResponse(BinaryData.FromString("ack"), WebPubSubDataType.Text);
}

Das folgende Beispiel zeigt eine JavaScript-Funktion für einen Web PubSub-Auslöser.

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. Außerdem hat EventErrorResponse die höchste Priorität im Vergleich zu REST-Objekten, sodass bei der Rückgabe von code das Ergebnis der Analyse EventErrorResponse ist und die Clientverbindung getrennt wird.

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

Definieren Sie die Triggerbindung in function.json.

{
  "disabled": false,
  "bindings": [
    {
      "type": "webPubSubTrigger",
      "direction": "in",
      "name": "data",
      "hub": "<hub>",
      "eventName": "message",
      "eventType": "user"
    }
  ]
}

Definieren Sie die Funktion in index.js.

module.exports = function (context, data) {
  context.log('Request from: ', context.bindingData.request.connectionContext.userId);
  context.log('Request message data: ', data);
  context.log('Request message dataType: ', context.bindingData.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. Außerdem hat EventErrorResponse die höchste Priorität im Vergleich zu REST-Objekten, sodass bei der Rückgabe von code das Ergebnis der Analyse EventErrorResponse ist und die Clientverbindung getrennt wird.

module.exports = async function (context) {
  return { 
    "data": "ack",
    "dataType" : "text"
  };
}

Attribute und Anmerkungen

Verwenden Sie in C#-Klassenbibliotheken das Attribut WebPubSubTrigger.

Dies ist ein WebPubSubTrigger-Attribut in einer Methodensignatur:

[FunctionName("WebPubSubTrigger")]
public static void Run([WebPubSubTrigger("<hub>", <WebPubSubEventType>, "<event-name>")] 
    WebPubSubConnectionContext context, ILogger log)
{
    ...
}

Ein vollständiges Beispiel finden Sie unter C#-Beispiel.

Konfiguration

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

Eigenschaft von „function.json“	Attributeigenschaft	BESCHREIBUNG
type	Nicht zutreffend	Erforderlich – muss auf `webPubSubTrigger` festgelegt sein.
direction	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.
hub	Hub	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	EventName	Dieser Wert ist erforderlich und muss auf das Nachrichtenereignis festgelegt werden, damit die Funktion ausgelöst wird. Für den Ereignistyp `system` muss der Ereignisname in `connect`, `connected` oder `disconnected` festgelegt werden. Bei benutzerdefinierten Unterprotokollen ist der Ereignisname `message`. Bei dem vom System unterstützten Unterprotokoll `json.webpubsub.azure.v1.` ist der Ereignisname benutzerdefiniert.
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. Außerdem wird der Wert standardmäßig automatisch mit den App-Einstellungen von „WebPubSubConnectionString“ aufgelöst. `null` bedeutet, dass die Überprüfung nicht erforderlich und immer erfolgreich ist.

Verwendungen

In C# ist WebPubSubEventRequest ein vom Typ erkannter Bindungsparameter, und Restparameter sind an den Parameternamen gebunden. Sehen Sie sich die folgende Tabelle mit den verfügbaren Parametern und Typen an.

Bei schwach typisierten Programmiersprachen wie JavaScript wird name in function.json verwendet, um das Auslöserobjekt 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
request	`WebPubSubEventRequest`	Beschreibt die Upstreamanforderung	Die Eigenschaft unterscheidet sich durch verschiedene Ereignistypen, einschließlich der abgeleiteten Klassen `ConnectEventRequest`, `ConnectedEventRequest`, `UserEventRequest` und `DisconnectedEventRequest`.
connectionContext	`WebPubSubConnectionContext`	Allgemeine Anforderungsinformationen	EventType, EventName, Hub, ConnectionId, UserId, Headers, Origin, Signature, States
data	`BinaryData`,`string`,`Stream`,`byte[]`	Anfordern von Nachrichtendaten vom Client im `message`-Benutzerereignis	-
dataType	`WebPubSubDataType`	Der Datentyp für Anforderungsnachrichten, der `binary`, `text` und `json` unterstützt	-
claims	`IDictionary<string, string[]>`	Benutzeransprüche in der `connect`-Systemanforderung	-
query	`IDictionary<string, string[]>`	Benutzerabfrage in der `connect`-Systemanforderung	-
subprotocols	`IList<string>`	Verfügbare Unterprotokolle in einer `connect`-Systemanforderung	-
clientCertificates	`IList<ClientCertificate>`	Eine Liste der Zertifikatfingerabdrücke von Clients in der `connect`-Systemanforderung	-
reason	`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	Groups, Roles, UserId, Subprotocol
`UserEventResponse`	Antwort auf ein Benutzerereignis	DataType, Data
`EventErrorResponse`	Fehlerantwort für das Synchronisierungsereignis	Code, ErrorMessage
`*WebPubSubEventResponse`	Basisantworttyp der unterstützten Typen, der bei unsicheren Rückgaben verwendet wird	-

Eingabebindung

Unsere Erweiterung bietet zwei Eingabebindungen für unterschiedliche Anforderungen.

WebPubSubConnection

Damit ein Client eine Verbindung mit dem Azure Web PubSub-Dienst herstellen kann, muss er über die Endpunkt-URL des Diensts und ein gültiges Zugriffstoken verfügen. Die WebPubSubConnection-Eingabebindung erstellt die erforderlichen Informationen, sodass der Client diese Tokengenerierung nicht selbst übernehmen muss. Da das Token nur für einen bestimmten Zeitraum gültig ist und nur für die Authentifizierung eines bestimmten Benutzers bzw. einer bestimmten Benutzerin für eine Verbindung verwendet werden kann, sollten Sie das Token nicht zwischenspeichern oder für mehrere Clients verwenden. Ein HTTP-Trigger, der diese Eingabebindung nutzt, kann für Clients verwendet werden, um die Verbindungsinformationen abzurufen.
WebPubSubContext

Wenn Sie Static Web Apps verwenden, ist HttpTrigger der einzige unterstützte Trigger. Im Web PubSub-Szenario wird die WebPubSubContext-Eingabebindung zur Verfügung gestellt, die Benutzer*innen dabei hilft, dienstseitige Upstream-HTTP-Anforderungen unter Web PubSub-Protokollen zu deserialisieren. So können Kund*innen für eine einfache Verarbeitung in Funktionen ähnliche Ergebnisse wie mit WebPubSubTrigger erzielen. Sehen Sie sich hierzu die Beispiele unten an. Bei Verwendung mit HttpTrigger müssen Kund*innen die an HttpTrigger weitergegebene URL im Ereignishandler entsprechend konfigurieren.

Beispiel: `WebPubSubConnection`

Das folgende Beispiel zeigt eine C#-Funktion, die mithilfe der Eingabebindung Web PubSub-Verbindungsinformationen abruft und über HTTP zurückgibt. Im folgenden Beispiel wird die UserId über den Abfrageteil der Clientanforderung übergeben, z. B. mit ?userid={User-A}.

[FunctionName("WebPubSubConnectionInputBinding")]
public static WebPubSubConnection Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubConnection(Hub = "<hub>", UserId = "{query.userid}")] WebPubSubConnection connection)
{
    return connection;
}

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

const connection = input.generic({
    type: 'webPubSubConnection',
    name: 'connection',
    userId: '{query.userId}',
    hub: '<hub>'
});

app.http('negotiate', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [connection],
    handler: async (request, context) => {
        return { body: JSON.stringify(context.extraInputs.get('connection')) };
    },
});

Definieren Sie Eingabebindungen in function.json.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{query.userid}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

Definieren Sie die Funktion in index.js.

module.exports = function (context, req, connection) {
  context.res = { body: connection };
  context.done();
};

Authentifizierte Token

Wenn die Funktion von einem authentifizierten Client ausgelöst wird, können Sie dem erzeugten Token einen Benutzer-ID-Anspruch hinzufügen. Mithilfe der App Service-Authentifizierung können Sie einer Funktions-App problemlos eine Authentifizierung hinzufügen.

App Service-Authentifizierung legt HTTP-Header mit den Namen x-ms-client-principal-id und x-ms-client-principal-name fest, die die Clientprinzipal-ID bzw. den Namen des authentifizierten Benutzers enthalten.

Sie können die Eigenschaft UserId der Bindung mithilfe eines Bindungsausdrucks auf den Wert eines der beiden Header festlegen: {headers.x-ms-client-principal-id} oder {headers.x-ms-client-principal-name}.

[FunctionName("WebPubSubConnectionInputBinding")]
public static WebPubSubConnection Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubConnection(Hub = "<hub>", UserId = "{headers.x-ms-client-principal-name}")] WebPubSubConnection connection)
{
    return connection;
}

Hinweis

Beschränkt auf die Bindungsparametertypen wird keine Möglichkeit zum Übergeben von Listen oder Arrays unterstützt; WebPubSubConnection wird nicht vollständig unterstützt mit allen Parametern des Server-SDK, insbesondere roles; enthält auch groups und expiresAfter. Falls der Kunde Rollen hinzufügen oder das Erstellen des Zugriffstokens in der Funktion verzögern muss, wird empfohlen, mit dem Server-SDK für C# zu arbeiten.

[FunctionName("WebPubSubConnectionCustomRoles")]
public static async Task<Uri> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req)
{
    var serviceClient = new WebPubSubServiceClient(new Uri(endpoint), "<hub>", "<web-pubsub-connection-string>");
    var userId = req.Query["userid"].FirstOrDefault();
    // your method to get custom roles.
    var roles = GetRoles(userId);
    return await serviceClient.GetClientAccessUriAsync(TimeSpan.FromMinutes(5), userId, roles);
}

Hinweis

const { app } = require('@azure/functions');
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
app.http('negotiate', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        const serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, "<hub>");
        let token = await serviceClient.getAuthenticationToken({ userId: req.query.userid, roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
        return { body: token.url };
    },
});

Hinweis

Definieren Sie Eingabebindungen in function.json.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ]
}

Definieren Sie die Funktion in index.js.

const { WebPubSubServiceClient } = require('@azure/web-pubsub');

module.exports = async function (context, req) {
  const serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, "<hub>");
  let token = await serviceClient.getAuthenticationToken({ userId: req.query.userid, roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
  context.res = { body: token.url };
  context.done();
};

Beispiel: `WebPubSubContext`

Das folgende Beispiel zeigt eine C#-Funktion, die mithilfe der Eingabebindung im Ereignistyp connect Informationen zur Web PubSub-Upstreamanforderung abruft und über HTTP zurückgibt.

[FunctionName("WebPubSubContextInputBinding")]
public static object Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubContext] WebPubSubContext wpsContext)
{
    // in the case request is a preflight or invalid, directly return prebuild response by extension.
    if (wpsContext.IsPreflight || wpsContext.HasError)
    {
        return wpsContext.Response;
    }
    var request = wpsContext.Request as ConnectEventRequest;
    var response = new ConnectEventResponse
    {
        UserId = wpsContext.Request.ConnectionContext.UserId
    };
    return response;
}

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

const wpsContext = input.generic({
    type: 'webPubSubContext',
    name: 'wpsContext'
});

app.http('connect', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [wpsContext],
    handler: async (request, context) => {
        var wpsRequest = context.extraInputs.get('wpsContext');

        return { "userId": wpsRequest.request.connectionContext.userId };
    }
});

Definieren Sie Eingabebindungen in function.json.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["get", "post"]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "webPubSubContext",
      "name": "wpsContext",
      "direction": "in"
    }
  ]
}

Definieren Sie die Funktion in index.js.

module.exports = async function (context, req, wpsContext) {
  // in the case request is a preflight or invalid, directly return prebuild response by extension.
  if (wpsContext.hasError || wpsContext.isPreflight)
  {
    return wpsContext.response;
  }
  // return an http response with connect event response as body.
  return { body: {"userId": wpsContext.connectionContext.userId} };
};

Konfiguration

WebPubSubConnection

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei „function.json“ und im WebPubSubConnection-Attribut festlegen.

Eigenschaft von „function.json“	Attributeigenschaft	BESCHREIBUNG
type	Nicht zutreffend	Muss auf `webPubSubConnection` festgelegt werden.
direction	Nicht zutreffend	Muss auf `in` festgelegt werden.
name	Nicht zutreffend	Variablenname, der im Funktionscode für das Bindungsobjekt für die Eingabeverbindung verwendet wird
hub	Hub	Erforderlich: Dieser Wert 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.
userId	UserId	Der optionale Wert des Benutzer-ID-Anspruchs, der im Zugriffsschlüsseltoken festgelegt wird
Verbindung	Verbindung	Erforderlich: Name der App-Einstellung, die die Verbindungszeichenfolge des Web PubSub-Diensts enthält (standardmäßig WebPubSubConnectionString)

WebPubSubContext

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei „function.json“ und im Attribut WebPubSubContext festlegen:

Eigenschaft von „function.json“	Attributeigenschaft	BESCHREIBUNG
type	–	Muss auf `webPubSubContext` festgelegt sein.
direction	–	Muss auf `in` festgelegt sein.
name	Nicht zutreffend	Variablenname, der im Funktionscode für die Web PubSub-Eingabeanforderung verwendet wird
Verbindung	Verbindung	Optional: Name von App-Einstellungen oder einer Einstellungssammlung, der den Upstream-Azure Web PubSub-Dienst angibt. Der Wert wird für den Schutz vor Missbrauch und die Signaturüberprüfung verwendet. Der Wert wird automatisch mit „WebPubSubConnectionString“ aufgelöst. `null` bedeutet, dass die Überprüfung nicht erforderlich und immer erfolgreich ist.

Verbrauch

WebPubSubConnection

WebPubSubConnection verfügt über die unten aufgeführten Eigenschaften.

Bindungsname	Bindungstyp	Beschreibung
BaseUri	URI	Verbindungs-URI für den Web PubSub-Client
URI	URI	Absoluter URI der Web PubSub-Verbindung, enthält das basierend auf der Anforderung generierte `AccessToken`
AccessToken	Zeichenfolge	Basierend auf der UserId der Anforderung und Dienstinformationen generiertes `AccessToken`

WebPubSubConnection verfügt über die unten aufgeführten Eigenschaften.

Bindungsname	Beschreibung
baseUrl	Verbindungs-URI für den Web PubSub-Client
url	Absoluter URI der Web PubSub-Verbindung, enthält das basierend auf der Anforderung generierte `AccessToken`
accessToken	Basierend auf der UserId der Anforderung und Dienstinformationen generiertes `AccessToken`

WebPubSubConnection verfügt über die unten aufgeführten Eigenschaften.

Bindungsname	Beschreibung
baseUrl	Verbindungs-URI für den Web PubSub-Client
url	Absoluter URI der Web PubSub-Verbindung, enthält das basierend auf der Anforderung generierte `AccessToken`
accessToken	Basierend auf der UserId der Anforderung und Dienstinformationen generiertes `AccessToken`

WebPubSubContext

WebPubSubContext verfügt über die unten aufgeführten Eigenschaften.

Bindungsname	Bindungstyp	Beschreibung	Eigenschaften
request	`WebPubSubEventRequest`	Anforderung vom Client. Weitere Informationen finden Sie in der nachstehenden Tabelle.	`WebPubSubConnectionContext` aus dem Anforderungsheader und weitere Eigenschaften, die aus dem Anforderungstext deserialisiert wurden, zur Beschreibung der Anforderung, z. B. `Reason` für `DisconnectedEventRequest`.
automatisieren	`HttpResponseMessage`	Antwort von Erweiterungsbuilds, die hauptsächlich für `AbuseProtection` und Fehlerfälle verwendet wird.	-
errorMessage	Zeichenfolge	Beschreibt Fehlerdetails beim Verarbeiten der Upstreamanforderung.	-
hasError	bool	Dieses Flag gibt an, ob es sich um eine gültige Web PubSub-Upstreamanforderung handelt.	-
isPreflight	bool	Dieses Flag gibt an, ob es sich um eine Preflightanforderung von `AbuseProtection` handelt.	-

Für WebPubSubEventRequest wird sie in verschiedene Klassen deserialisiert, die unterschiedliche Informationen zum Anforderungsszenario bereitstellen. Für PreflightRequest oder in ungültigen Fällen können die Benutzer*innen dazu die Flags IsPreflight und HasError überprüfen. Es wird empfohlen, die Systembuildantwort WebPubSubContext.Response direkt zurückzugegeben. Alternativ können Kund*innen Fehler bei Bedarf protokollieren. In verschiedenen Szenarios können Kund*innen die Anforderungseigenschaften wie folgt lesen.

Abgeleitete Klasse	Beschreibung	Eigenschaften
`PreflightRequest`	Wird in `AbuseProtection` verwendet, wenn `IsPreflight` den Wert true hat	-
`ConnectEventRequest`	Wird im Systemereignistyp `Connect` verwendet	Claims, Query, Subprotocols, ClientCertificates
`ConnectedEventRequest`	Wird im Systemereignistyp `Connected` verwendet	-
`UserEventRequest`	Wird im Benutzerereignistyp verwendet	Data, DataType
`DisconnectedEventRequest`	Wird im Systemereignistyp `Disconnected` verwendet	`Reason`

Hinweis

Obwohl es sich bei WebPubSubContext um eine Eingabebindung handelt, die eine ähnliche Anforderungsdeserialisierung im HttpTrigger wie WebPubSubTrigger bietet, gibt es Einschränkungen, z. B. wird der Verbindungsstatus nach der Zusammenführung unterstützt. Die Rückgabeantwort wird weiterhin vom Dienst berücksichtigt, aber Benutzer müssen die Antwort selbst erstellen. Wenn Benutzer*innen die Ereignisantwort festlegen müssen, sollten Sie eine HttpResponseMessage mit ConnectEventResponse oder Nachrichten für das Benutzerereignis als Antworttext zurückgeben und den Verbindungszustand mit dem Schlüssel ce-connectionstate in den Antwortheader einfügen.

Ausgabebindung

Verwenden Sie die Web PubSub-Ausgabebindung, um eine Aktion des Azure Web PubSub-Diensts aufzurufen. Sie können eine Nachricht senden an:

Alle verbundenen Clients
Verbundene Clients, die für einen bestimmten Benutzer authentifiziert sind
Verbundene Clients, die in einer bestimmten Gruppe miteinander verknüpft sind
Eine bestimmte Clientverbindung

Mit der Ausgabebindung können Sie außerdem Clients und Gruppen verwalten und Berechtigungen für eine bestimmte connectionId für die Gruppe erteilen oder widerrufen.

Hinzufügen einer Verbindung zu einer Gruppe
Hinzufügen von Benutzern zur Gruppe
Entfernen einer Verbindung aus einer Gruppe
Entfernen eines Benutzers aus einer Gruppe
Entfernen eines Benutzers aus allen Gruppen
Schließen aller Clientverbindungen
Schließen einer bestimmten Clientverbindung
Schließen von Verbindungen in einer Gruppe
Zuweisen der Berechtigung für eine Verbindung
Widerrufen der Berechtigung für eine Verbindung

Informationen zu Setup- und Konfigurationsdetails finden Sie in der Übersicht.

Beispiel

[FunctionName("WebPubSubOutputBinding")]
public static async Task RunAsync(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSub(Hub = "<hub>")] IAsyncCollector<WebPubSubAction> actions)
{
    await actions.AddAsync(WebPubSubAction.CreateSendToAllAction("Hello Web PubSub!", WebPubSubDataType.Text));
}

const { app, output } = require('@azure/functions');
const wpsMsg = output.generic({
    type: 'webPubSub',
    name: 'actions',
    hub: '<hub>',
});

app.http('message', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [wpsMsg],
    handler: async (request, context) => {
        context.extraOutputs.set(wpsMsg, [{
            "actionName": "sendToAll",
            "data": `Hello world`,
            "dataType": `text`
        }]);
    }
});

Definieren Sie Bindungen in functions.json.

{
  "disabled": false,
  "bindings": [
    {
      "type": "webPubSub",
      "name": "actions",
      "hub": "<hub>",
      "direction": "out"
    }
  ]
}

Definieren Sie die Funktion in index.js.

module.exports = async function (context) {
  context.bindings.actions = {
    "actionName": "sendToAll",
    "data": "hello",
    "dataType": "text"
  };
  context.done();
}

WebPubSubAction

WebPubSubAction ist der abstrakte Basistyp von Ausgabebindungen. Die abgeleiteten Typen stellen die Aktion dar, die der Server vom Dienst aufrufen möchte.

In der Programmiersprache C# geben Sie einige statische Methoden unter WebPubSubAction an, um die verfügbaren Aktionen zu ermitteln. Sie können Benutzer*innen beispielsweise die SendToAllAction erstellen, indem sie WebPubSubAction.CreateSendToAllAction() aufrufen.

Abgeleitete Klasse	Eigenschaften
`SendToAllAction`	Data, DataType, Excluded
`SendToGroupAction`	Group, Data, DataType, Excluded
`SendToUserAction`	UserId, Data, DataType
`SendToConnectionAction`	ConnectionId, Data, DataType
`AddUserToGroupAction`	UserId, Group
`RemoveUserFromGroupAction`	UserId, Group
`RemoveUserFromAllGroupsAction`	UserId
`AddConnectionToGroupAction`	ConnectionId, Group
`RemoveConnectionFromGroupAction`	ConnectionId, Group
`CloseAllConnectionsAction`	Excluded, Reason
`CloseClientConnectionAction`	ConnectionId, Reason
`CloseGroupConnectionsAction`	Group, Excluded, Reason
`GrantPermissionAction`	ConnectionId, Permission, TargetName
`RevokePermissionAction`	ConnectionId, Permission, TargetName

In schwach typisierten Programmiersprachen wie javascript ist actionName der Schlüsselparameter zum Auflösen des Typs. Die verfügbaren Aktionen sind unten aufgeführt.

ActionName	Eigenschaften
`sendToAll`	Data, DataType, Excluded
`sendToGroup`	Group, Data, DataType, Excluded
`sendToUser`	UserId, Data, DataType
`sendToConnection`	ConnectionId, Data, DataType
`addUserToGroup`	UserId, Group
`removeUserFromGroup`	UserId, Group
`removeUserFromAllGroups`	UserId
`addConnectionToGroup`	ConnectionId, Group
`removeConnectionFromGroup`	ConnectionId, Group
`closeAllConnections`	Excluded, Reason
`closeClientConnection`	ConnectionId, Reason
`closeGroupConnections`	Group, Excluded, Reason
`grantPermission`	ConnectionId, Permission, TargetName
`revokePermission`	ConnectionId, Permission, TargetName

Wichtig

Die Data-Eigenschaft der Nachricht in den Aktionen zum Senden von Nachrichten muss string sein, wenn der Datentyp auf json oder text festgelegt ist, um Mehrdeutigkeiten bei der Datenkonvertierung zu vermeiden. Verwenden Sie JSON.stringify(), um das benötigte JSON-Objekt zu konvertieren. Dies wird an jeder Stelle mithilfe der Nachrichteneigenschaft angewandt, z. B. durch UserEventResponse.Data bei Verwendung von WebPubSubTrigger.

Wenn der Datentyp auf binary festgelegt wurde, ist es zulässig, einen nativ unterstützten dataType als binary zu binden, wie in function.json konfiguriert. Weitere Informationen finden Sie unter Trigger- und Bindungsdefinitionen.

In schwach typisierten Programmiersprachen wie javascript ist actionName der Schlüsselparameter zum Auflösen des Typs. Die verfügbaren Aktionen sind unten aufgeführt.

ActionName	Eigenschaften
`sendToAll`	Data, DataType, Excluded
`sendToGroup`	Group, Data, DataType, Excluded
`sendToUser`	UserId, Data, DataType
`sendToConnection`	ConnectionId, Data, DataType
`addUserToGroup`	UserId, Group
`removeUserFromGroup`	UserId, Group
`removeUserFromAllGroups`	UserId
`addConnectionToGroup`	ConnectionId, Group
`removeConnectionFromGroup`	ConnectionId, Group
`closeAllConnections`	Excluded, Reason
`closeClientConnection`	ConnectionId, Reason
`closeGroupConnections`	Group, Excluded, Reason
`grantPermission`	ConnectionId, Permission, TargetName
`revokePermission`	ConnectionId, Permission, TargetName

Wichtig

Konfiguration

WebPubSub

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei „function.json“ und im WebPubSub-Attribut festlegen.

Eigenschaft von „function.json“	Attributeigenschaft	BESCHREIBUNG
type	Nicht zutreffend	Muss auf `webPubSub` festgelegt werden.
direction	Nicht zutreffend	Muss auf `out` festgelegt werden.
name	Nicht zutreffend	Variablenname, der im Funktionscode für das Ausgabebindungsobjekt verwendet wird
hub	Hub	Dieser Wert 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.
Verbindung	Verbindung	Der Name der App-Einstellung, die die Verbindungszeichenfolge des Web PubSub-Diensts enthält (standardmäßig WebPubSubConnectionString)

Problembehandlung

Einrichten der Konsolenprotokollierung

Sie können auch einfach die Konsolenprotokollierung aktivieren, wenn Sie ausführliche Informationen zu den von Ihnen an den Dienst gesendeten Anforderungen erhalten möchten.

Nächste Schritte

Erstellen Sie mithilfe dieser Ressourcen Ihre eigene Anwendung:

Tutorial: Veröffentlichen und Abonnieren von Nachrichten in Azure Web PubSub

Tutorial: Erstellen eines einfachen Chatrooms mit Azure Web PubSub

Tutorial: Verwenden eines vom Dienst unterstützten Unterprotokolls für Clientstreaming

Tutorial: Erstellen eines serverlosen Chats mit Azure Functions und Web PubSub

Tutorial: Konfigurieren eines Ereignislisteners

Spielen mit Livedemos

Weitere Beispiele für Azure Web PubSub

Freigeben über

Azure Web PubSub-Trigger und -Bindungen für Azure Functions

Hinzufügen zu Ihrer Funktions-App

Wichtige Begriffe

Triggerbindung

Beispiel

Attribute und Anmerkungen

Konfiguration

Verwendungen

Rückgabeantwort

Eingabebindung

Beispiel: `WebPubSubConnection`

Authentifizierte Token

Beispiel: `WebPubSubContext`

Konfiguration

WebPubSubConnection

WebPubSubContext

Verbrauch

WebPubSubConnection

WebPubSubContext

Ausgabebindung

Beispiel

WebPubSubAction

Konfiguration

WebPubSub

Problembehandlung

Einrichten der Konsolenprotokollierung

Nächste Schritte

Feedback

Zusätzliche Ressourcen

Freigeben über

Azure Web PubSub-Trigger und -Bindungen für Azure Functions

Hinzufügen zu Ihrer Funktions-App

Wichtige Begriffe

Triggerbindung

Beispiel

Attribute und Anmerkungen

Konfiguration

Verwendungen

Rückgabeantwort

Eingabebindung

Beispiel: WebPubSubConnection

Authentifizierte Token

Beispiel: WebPubSubContext

Konfiguration

WebPubSubConnection

WebPubSubContext

Verbrauch

WebPubSubConnection

WebPubSubContext

Ausgabebindung

Beispiel

WebPubSubAction

Konfiguration

WebPubSub

Problembehandlung

Einrichten der Konsolenprotokollierung

Nächste Schritte

Feedback

Zusätzliche Ressourcen

Beispiel: `WebPubSubConnection`

Beispiel: `WebPubSubContext`