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

Artikel
01/12/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	Typ
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

Diagram showing the workflow of Azure Web PubSub service working with Function 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ü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 of get function system keys.

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. ConnectEreignis respektiert und , EventErrorResponseund Benutzerereignis respektiert ConnectEventResponseUserEventResponse und EventErrorResponse, Resttypen, die nicht dem aktuellen Szenario entsprechen, werden ignoriert. Und wenn EventErrorResponse der Dienst zurückgegeben wird, legt der Dienst die Clientverbindung ab.

[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 Web PubSub-Trigger-JavaScript-Funktion.

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 JavaScript schwach typisierte Sprache wird sie in Bezug auf die Objektschlüssel deserialisiert. Und EventErrorResponse hat die höchste Priorität im Vergleich zu Restobjekten, d. h., wenn code sie in der Rückgabe enthalten ist, wird sie analysiert EventErrorResponse und die Clientverbindung gelöscht.

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 JavaScript schwach typisierte Sprache wird sie in Bezug auf die Objektschlüssel deserialisiert. Und EventErrorResponse hat die höchste Priorität im Vergleich zu Restobjekten, d. h., wenn code sie in der Rückgabe enthalten ist, wird sie analysiert EventErrorResponse und die Clientverbindung gelöscht.

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	–	Erforderlich – muss auf `webPubSubTrigger` festgelegt sein.
direction	–	Erforderlich – muss auf `in` festgelegt sein.
name	–	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. Und der Wert wird standardmäßig automatisch mit den App-Einstellungen "WebPubSub Verbinden ionString" aufgelöst. Und `null` bedeutet, dass die Validierung nicht benötigt wird 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.

In schwach typografischer Sprache wie JavaScript wird verwendet, namefunction.json um das Triggerobjekt in Bezug auf die nachstehende Zuordnungstabelle zu binden. Und beachten Sie dataType , function.json dass die Nachricht entsprechend konvertiert wird, wenn name sie als Bindungsobjekt für die Triggereingabe festgelegt data ist. Alle Parameter können gelesen context.bindingData.<BindingName> und konvertiert werden JObject .

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`,,`Streambyte[]`	Anfordern von Nachrichtendaten vom Client im `message`-Benutzerereignis	-
dataType	`WebPubSubDataType`	Request message dataType, which supports `binary`, , `textjson`	-
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 mehrere typen unterstützter Parameter in den ersten eingegeben werden, d. h. requestdata die andere als der StandardtypBinaryData, damit die Funktionsbindung korrekt ist.

Rückgabeantwort

WebPubSubTrigger respektiert die vom Kunden zurückgegebene Antwort für synchrone Ereignisse und connect Benutzerereignisse. Nur übereinstimmende Antwort wird an den Dienst zurückgesendet, andernfalls 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 aus dem Rückgabewert mit den ursprünglichen aus der Anforderung WebPubSubConnectionContext.Stateszusammen. Der Wert im vorhandenen Schlüssel wird überschrieben, und der Wert in einem 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 unterstützen keine Möglichkeit zum Übergeben von Listen oder Arrays, die WebPubSubConnection nicht vollständig mit allen Parametern server SDK unterstützt werden, insbesondere roles, und enthält und enthält groups und expiresAfter. Falls der Kunde Rollen hinzufügen oder das Zugriffstoken in der Funktion verzögern muss, empfiehlt es sich, 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

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

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

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

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

In der folgenden Tabelle werden die Bindungskonfigurationseigenschaften erläutert, die Sie in der Datei function.json und dem WebPubSubConnection Attribut festlegen.

Eigenschaft von „function.json“	Attributeigenschaft	BESCHREIBUNG
type	–	Muss auf `webPubSubConnection` festgelegt werden.
direction	–	Muss auf `in` festgelegt werden.
name	–	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	–	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 die Überprüfung von Missbrauchsschutz und Signatur verwendet. Der Wert wird standardmäßig automatisch mit "WebPubSub Verbinden ionString" aufgelöst. Und `null` bedeutet, dass die Validierung nicht benötigt wird 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 Antwort auf die Rückgabe wird weiterhin von der Dienstseite beachtet, aber Die 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

In der folgenden Tabelle werden die Bindungskonfigurationseigenschaften erläutert, die Sie in der Datei function.json und dem WebPubSub Attribut festlegen.

Eigenschaft von „function.json“	Attributeigenschaft	BESCHREIBUNG
type	–	Muss auf `webPubSub` festgelegt werden.
direction	–	Muss auf `out` festgelegt werden.
name	–	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.