Freigeben über

Azure Web PubSub-Eingabebindungen für Azure-Funktionen

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. Das Token ist zeitlich begrenzt und kann einen bestimmten Benutzer bei einer Verbindung authentifizieren. Speichern Sie daher das Token nicht zwischen, oder teilen Sie es nicht zwischen Clients. 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. Bei Verwendung mit HttpTrigger müssen Kund*innen die an HttpTrigger weitergegebene URL im Ereignishandler entsprechend konfigurieren.

WebPubSubConnection

Beispiel

Das folgende Beispiel zeigt eine HTTP-Triggerfunktion, die Web PubSub-Verbindungsinformationen mithilfe der Eingabebindung erhält und sie über HTTP zurückgibt. Im folgenden Beispiel wird der UserId Abfrageteil der Clientanforderung übergeben, z ?userid={User-A}. B. .

[Function("WebPubSubConnectionInputBinding")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
[WebPubSubConnectionInput(Hub = "<hub>", , UserId = "{query.userid}", Connection = "<web_pubsub_connection_name>")] WebPubSubConnection connectionInfo)
{
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.WriteAsJsonAsync(connectionInfo);
    return response;
}

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')) };
    },
});

Erstellen Sie einen Ordner , der aushandeln und aktualisieren und aushandeln/function.json und kopieren Sie die folgenden JSON-Codes.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{query.userid}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

Definieren Sie die Funktion in negotiate/init.py.

import logging

import azure.functions as func

def main(req: func.HttpRequest, connection) -> func.HttpResponse:
    return func.HttpResponse(connection)

Hinweis

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

Hinweis

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

Authentifizierte Benutzer-ID abrufen

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.

Mit einem Bindungsausdruck können Sie die UserId Eigenschaft der Bindung auf den Wert eines Headers festlegen: {headers.x-ms-client-principal-id} oder {headers.x-ms-client-principal-name}.

[Function("WebPubSubConnectionInputBinding")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
[WebPubSubConnectionInput(Hub = "<hub>", , UserId = "{headers.x-ms-client-principal-id}", Connection = "<web_pubsub_connection_name>")] WebPubSubConnection connectionInfo)
{
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.WriteAsJsonAsync(connectionInfo);
    return response;
}

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

const connection = input.generic({
    type: 'webPubSubConnection',
    name: 'connection',
    userId: '{headers.x-ms-client-principal-id}',
    hub: '<hub>'
});

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

Erstellen Sie einen Ordner , der aushandeln und aktualisieren und aushandeln/function.json und kopieren Sie die folgenden JSON-Codes.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{headers.x-ms-client-principal-id}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

Definieren Sie die Funktion in negotiate/init.py.

import logging

import azure.functions as func

def main(req: func.HttpRequest, connection) -> func.HttpResponse:
    return func.HttpResponse(connection)

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“ und im WebPubSubConnection-Attribut festlegen.

Eigenschaft von „function.json“ Attributeigenschaft BESCHREIBUNG
Typ Nicht zutreffend Muss auf webPubSubConnection festgelegt werden.
Richtung Nicht zutreffend Muss auf in festgelegt werden.
Name Nicht zutreffend Variablenname, der im Funktionscode für das Bindungsobjekt für die Eingabeverbindung verwendet wird
Nabe Drehscheibe 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 Benutzer-ID Der optionale Wert des Benutzer-ID-Anspruchs, der im Zugriffsschlüsseltoken festgelegt wird
clientProtocol ClientProtocol Optional – Der Clientprotokolltyp. Beispielsweise können die folgenden Werte verwendet werden: default und mqtt.
Für MQTT-Clients müssen Sie sie auf mqttfestlegen.
Für andere Clients können Sie die Eigenschaft weglassen oder auf default.
Verbindung Verbindung Erforderlich: Name der App-Einstellung, die die Verbindungszeichenfolge des Web PubSub-Diensts enthält (standardmäßig WebPubSubConnectionString)

Verbrauch

WebPubSubConnection stellt die folgenden Eigenschaften bereit.

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
ZugriffsToken Zeichenfolge Basierend auf der UserId der Anforderung und Dienstinformationen generiertes AccessToken

WebPubSubConnection stellt die folgenden Eigenschaften bereit.

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

Hinweis

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

Weitere Anpassungen des generierten Tokens

Beschränkt auf die Bindungsparametertypen unterstützen keine Möglichkeit zum Übergeben von Listen oder Arrays, die WebPubSubConnection mit allen Parametern server SDK nicht vollständig unterstützt werden, insbesondere roles, und enthält und enthält groups und expiresAfter.

Wenn der Kunde Rollen hinzufügen oder das Erstellen des Zugriffstokens in der Funktion verzögern muss, empfehlen wir Ihnen, mit dem Server-SDK für C# zu arbeiten.

[Function("WebPubSubConnectionCustomRoles")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData 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);
    var url = await serviceClient.GetClientAccessUriAsync(TimeSpan.FromMinutes(5), userId, roles);
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.WriteString(url.ToString());
    return response;
}

Wenn der Kunde Rollen hinzufügen oder das Erstellen des Zugriffstokens in der Funktion verzögern muss, empfehlen wir Ihnen, 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

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

Hinweis

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

WebPubSubContext

Beispiel

// validate method when upstream set as http://<func-host>/api/{event}
[Function("validate")]
public static HttpResponseData Validate(
    [HttpTrigger(AuthorizationLevel.Anonymous, "options")] HttpRequestData req,
    [WebPubSubContextInput] WebPubSubContext wpsReq)
{
    return BuildHttpResponseData(req, wpsReq.Response);
}

// Respond AbuseProtection to put header correctly.
private static HttpResponseData BuildHttpResponseData(HttpRequestData request, SimpleResponse wpsResponse)
{
    var response = request.CreateResponse();
    response.StatusCode = (HttpStatusCode)wpsResponse.Status;
    response.Body = response.Body;
    foreach (var header in wpsResponse.Headers)
    {
        response.Headers.Add(header.Key, header.Value);
    }
    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 };
    }
});

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“ und im Attribut WebPubSubContext festlegen:

Eigenschaft von „function.json“ Attributeigenschaft BESCHREIBUNG
Typ Nicht zutreffend Muss auf webPubSubContext festgelegt sein.
Richtung Nicht zutreffend 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. 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.

Verbrauch

WebPubSubContext stellt die folgenden Eigenschaften bereit.

Bindungsname Bindungstyp BESCHREIBUNG Eigenschaften
Anfrage WebPubSubEventRequest Details finden Sie in der folgenden 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. -
Fehlermeldung Zeichenfolge Beschreibt Fehlerdetails beim Verarbeiten der Upstreamanforderung. -
hasError Boolesch Dieses Flag gibt an, ob es sich um eine gültige Web PubSub-Upstreamanforderung handelt. -
isPreflight Boolesch 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. Wir empfehlen Ihnen, die Systembuildantwort WebPubSubContext.Response direkt zurückzugeben, oder Kunden können Fehler bei Bedarf protokollieren. In verschiedenen Szenarien kann der Kunde 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 Daten, Datentyp
DisconnectedEventRequest Wird im Systemereignistyp Disconnected verwendet `Reason`

Hinweis

WebPubSubContext Dies ist zwar eine Eingabebindung, die eine ähnliche Deserialisierungsart im HttpTrigger Vergleich WebPubSubTriggerbietet, es gibt jedoch Einschränkungen, d. h. der Verbindungsstatus nach der Zusammenführung wird nicht 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.