Delen via

Azure Web PubSub-invoerbindingen voor Azure Functions

Onze extensie biedt twee invoerbindingen die gericht zijn op verschillende behoeften.

  • WebPubSubConnection

    Als u een client verbinding wilt laten maken met Azure Web PubSub Service, moet deze de URL van het service-eindpunt en een geldig toegangstoken weten. De WebPubSubConnection invoerbinding produceert vereiste informatie, zodat de client deze tokengeneratie zelf niet hoeft te verwerken. Het token is tijdslimiet en kan een specifieke gebruiker verifiëren bij een verbinding. Sla het token daarom niet in de cache op of deel het tussen clients. Een HTTP-trigger die met deze invoerbinding werkt, kan worden gebruikt voor clients om de verbindingsgegevens op te halen.

  • WebPubSubContext

    Wanneer u Static Web Apps gebruikt, HttpTrigger is dit de enige ondersteunde trigger. In Web PubSub-scenario's helpt de WebPubSubContext invoerbinding gebruikers bij het deserialiseren van upstream HTTP-aanvragen van de service onder Web PubSub-protocollen. Zo kunnen klanten vergelijkbare resultaten krijgen die worden vergeleken met WebPubSubTrigger eenvoudig te verwerken in functies. Wanneer deze wordt gebruikt met HttpTrigger, moet de klant de httpTrigger-URL configureren in gebeurtenis-handler dienovereenkomstig.

WebPubSubConnection

Opmerking

In het volgende voorbeeld ziet u een HTTP-triggerfunctie die verbindingsgegevens van Web PubSub verkrijgt met behulp van de invoerbinding en deze retourneert via HTTP. In het volgende voorbeeld wordt het doorgegeven via een UserId queryonderdeel voor clientaanvragen, zoals ?userid={User-A}.

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

Maak een maponderhandeling en werk negotiate/function.json bij en kopieer de volgende 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"
    }
  ]
}

Definieer de functie in negotiate/init.py.

import logging

import azure.functions as func

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

Notitie

Volledige voorbeelden voor deze taal zijn in behandeling

Notitie

De Web PubSub-extensies voor Java worden nog niet ondersteund.

Geverifieerde gebruikers-id ophalen

Als de functie wordt geactiveerd door een geverifieerde client, kunt u een gebruikers-id-claim toevoegen aan het gegenereerde token. U kunt eenvoudig verificatie toevoegen aan een functie-app met behulp van App Service-verificatie.

Met App Service-verificatie worden RESPECTIEVELIJK HTTP-headers ingesteld x-ms-client-principal-id die x-ms-client-principal-name de client-principal-id en -naam van de geverifieerde gebruiker bevatten.

U kunt de UserId eigenschap van de binding instellen op de waarde vanuit een header met behulp van een bindingexpressie: {headers.x-ms-client-principal-id} of {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')) };
    },
});

Maak een maponderhandeling en werk negotiate/function.json bij en kopieer de volgende 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"
    }
  ]
}

Definieer de functie in negotiate/init.py.

import logging

import azure.functions as func

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

Notitie

Volledige voorbeelden voor deze taal zijn in behandeling

Notitie

De Web PubSub-extensies voor Java worden nog niet ondersteund.

Configuratie

In de volgende tabel worden de bindingsconfiguratie-eigenschappen uitgelegd die u hebt ingesteld in het function.json-bestand en het WebPubSubConnection kenmerk.

function.json-eigenschap Kenmerkeigenschap Beschrijving
soort n.v.t. Moet worden ingesteld op webPubSubConnection
richting n.v.t. Moet worden ingesteld op in
naam n.v.t. Variabelenaam die wordt gebruikt in functiecode voor het bindingsobject voor invoerverbindingen.
naaf Knooppunt Vereist: de waarde moet worden ingesteld op de naam van de Web PubSub-hub om de functie te activeren. We ondersteunen het instellen van de waarde in kenmerk als hogere prioriteit, of deze kan worden ingesteld in app-instellingen als een globale waarde.
userId Gebruikers-id Optioneel: de waarde van de claim voor de gebruikers-id die moet worden ingesteld in het toegangssleuteltoken.
clientProtocol ClientProtocol Optioneel: het clientprotocoltype. Geldige waarden zijn onder andere default en mqtt.
Voor MQTT-clients moet u deze instellen op mqtt.
Voor andere clients kunt u de eigenschap weglaten of instellen op default.
verbinding Verbinding Vereist: de naam van de app-instelling die de Web PubSub-service bevat verbindingsreeks (standaard ingesteld op 'WebPubSubConnectionString').

Gebruik

WebPubSubConnection biedt de volgende eigenschappen.

Bindingsnaam Bindingstype Beschrijving
BaseUri URI Web PubSub-clientverbindings-URI.
URI URI Absolute URI van de Web PubSub-verbinding, bevat AccessToken gegenereerde basis op de aanvraag.
AccessToken tekenreeks Gegenereerd AccessToken op basis van aanvraag UserId en servicegegevens.

WebPubSubConnection biedt de volgende eigenschappen.

Bindingsnaam Beschrijving
baseUrl Web PubSub-clientverbindings-URI.
URL Absolute URI van de Web PubSub-verbinding, bevat AccessToken gegenereerde basis op de aanvraag.
accessToken Gegenereerd AccessToken op basis van aanvraag UserId en servicegegevens.

Notitie

De Web PubSub-extensies voor Java worden nog niet ondersteund.

Meer aanpassing van gegenereerd token

Beperkt tot de bindingparametertypen bieden geen ondersteuning voor het doorgeven van een lijst of matrix. De WebPubSubConnection parameter wordt niet volledig ondersteund met alle parameters die de SERVER-SDK heeft, met name rolesen bevat en bevat groups ook expiresAfter.

Wanneer de klant rollen moet toevoegen of het bouwen van het toegangstoken in de functie moet vertragen, raden we u aan om te werken met de server-SDK voor C#.

[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;
}

Wanneer de klant rollen moet toevoegen of het bouwen van het toegangstoken in de functie moet vertragen, raden we u aan om te werken met de server-SDK voor JavaScript.

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

Notitie

Volledige voorbeelden voor deze taal zijn in behandeling

Notitie

De Web PubSub-extensies voor Java worden nog niet ondersteund.

WebPubSubContext

Opmerking

// 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 };
    }
});

Notitie

Volledige voorbeelden voor deze taal zijn in behandeling

Notitie

De Web PubSub-extensies voor Java worden nog niet ondersteund.

Configuratie

In de volgende tabel worden de bindingsconfiguratie-eigenschappen uitgelegd die u hebt ingesteld in het functions.json-bestand en het WebPubSubContext kenmerk.

function.json-eigenschap Kenmerkeigenschap Beschrijving
soort n.v.t. Moet worden ingesteld op webPubSubContext.
richting n.v.t. Moet worden ingesteld op in.
naam n.v.t. Variabelenaam die wordt gebruikt in functiecode voor invoer web pubsub-aanvraag.
verbinding Verbinding Optioneel: de naam van een app-instellingen of verzameling die de upstream Azure Web PubSub-service aangeeft. De waarde wordt gebruikt voor misbruikbeveiliging en handtekeningvalidatie. De waarde wordt standaard automatisch omgezet met WebPubSubConnectionString. En null betekent dat de validatie niet nodig is en altijd slaagt.

Belangrijk

Voor optimale beveiliging moet uw functie-app beheerde identiteiten gebruiken bij het maken van verbinding met de Web PubSub-service in plaats van een verbindingsreeks, die een gedeelde geheime sleutel bevat. Zie Een beheerde identiteitsaanvraag autoriseren met behulp van Microsoft Entra-id voor meer informatie.

Gebruik

WebPubSubContext biedt de volgende eigenschappen.

Bindingsnaam Bindingstype Beschrijving Eigenschappen
aanvraag WebPubSubEventRequest Aanvraag van client, zie de volgende tabel voor meer informatie. WebPubSubConnectionContext van de aanvraagheader en andere eigenschappen die zijn gedeserialiseerd vanuit de hoofdtekst van de aanvraag, beschrijven de aanvraag, bijvoorbeeld ReasonDisconnectedEventRequest.
antwoord HttpResponseMessage Reactie van extensie-builds voornamelijk voor AbuseProtection en foutencases. -
foutmelding tekenreeks Beschrijf de foutdetails bij het verwerken van de upstream-aanvraag. -
hasError Bool Vlag om aan te geven of het een geldige Web PubSub-upstream-aanvraag is. -
isPreflight Bool Vlag om aan te geven of het een voorbereidende aanvraag van AbuseProtectionis. -

Voor WebPubSubEventRequest, het wordt gedeserialiseerd naar verschillende klassen die verschillende informatie over het aanvraagscenario bieden. Voor PreflightRequest of niet geldige gevallen kan de gebruiker de vlaggen IsPreflight controleren en HasError weten. We raden u aan om rechtstreeks reactie van systeembuilds WebPubSubContext.Response te retourneren, of de klant kan fouten op aanvraag registreren. In verschillende scenario's kan de klant de aanvraageigenschappen als volgt lezen.

Afgeleide klasse Beschrijving Eigenschappen
PreflightRequest Wordt gebruikt in AbuseProtection wanneer IsPreflight waar is -
ConnectEventRequest Wordt gebruikt in het gebeurtenistype van het systeem Connect Claims, Query, Subprotocollen, Clientcertificaten
ConnectedEventRequest Wordt gebruikt in het gebeurtenistype van het systeem Connected -
UserEventRequest Wordt gebruikt in het gebeurtenistype van de gebruiker Gegevens, DataType
DisconnectedEventRequest Wordt gebruikt in het gebeurtenistype van het systeem Disconnected Reden

Notitie

Hoewel het WebPubSubContext een invoerbinding is die vergelijkbaar is met deserialiseren van HttpTrigger aanvragen in vergelijking met WebPubSubTrigger, zijn er beperkingen, dat wil zeggen dat de verbindingsstatus na samenvoegen niet wordt ondersteund. Het retourantwoord wordt nog steeds gerespecteerd door de servicezijde, maar gebruikers moeten het antwoord zelf bouwen. Als gebruikers het antwoord op de gebeurtenis moeten instellen, moet u een HttpResponseMessage bevat ConnectEventResponse of berichten voor de gebruikers gebeurtenis retourneren als hoofdtekst van het antwoord en de verbindingsstatus met de sleutel ce-connectionstate in de antwoordheader plaatsen.

  • Last updated on