Sdílet prostřednictvím

Vstupní vazby Azure Web PubSub pro Azure Functions

Naše rozšíření poskytuje dvě vstupní vazby, které cílí na různé potřeby.

  • WebPubSubConnection

    Aby se klient připojil ke službě Azure Web PubSub Service, musí znát adresu URL koncového bodu služby a platný přístupový token. Vstupní WebPubSubConnection vazba vytváří požadované informace, takže klient nemusí zpracovávat samotné generování tokenů. Token je časově omezený a může ověřit konkrétního uživatele pro připojení. Proto token neuchovávejte do mezipaměti ani ho nesdílejte mezi klienty. Trigger HTTP, který pracuje s touto vstupní vazbou, se dá použít pro klienty k načtení informací o připojení.

  • WebPubSubContext

    Pokud používáte Static Web Apps, HttpTrigger je jediným podporovaným triggerem. Ve scénářích WebPubSubContext Web PubSub pomáhá vstupní vazba uživatelům deserializovat upstreamové požadavky HTTP ze služby v rámci protokolů Web PubSub. Zákazníci tak můžou získat podobné výsledky v porovnání s WebPubSubTrigger možnostmi snadného zpracování ve funkcích. Při použití se HttpTriggerzákazníkem vyžaduje, aby v obslužné rutině události odpovídajícím způsobem nakonfigurovali adresu URL vystavenou protokolem HttpTrigger.

WebPubSubConnection

Příklad

Následující příklad ukazuje funkci triggeru HTTP, která získává informace o připojení Web PubSub pomocí vstupní vazby a vrací ji přes HTTP. V následujícím příkladu se UserId předává prostřednictvím části dotazu na požadavek klienta, například ?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')) };
    },
});

Vytvořte složku negotiate a aktualizujte negotiate/function.json a zkopírujte následující kódy JSON.

{
  "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"
    }
  ]
}

Definujte funkci v negotiate/init.py.

import logging

import azure.functions as func

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

Poznámka:

Dokončení ukázek pro tento jazyk čeká na vyřízení

Poznámka:

Rozšíření Web PubSub pro Javu se zatím nepodporují.

Získání ověřeného ID uživatele

Pokud funkci aktivuje ověřený klient, můžete do vygenerovaného tokenu přidat deklaraci ID uživatele. Ověřování můžete snadno přidat do aplikace funkcí pomocí ověřování pomocí služby App Service.

Ověřování služby App Service nastaví hlavičky HTTP pojmenované x-ms-client-principal-id a x-ms-client-principal-name obsahují ID a název instančního objektu ověřeného uživatele.

Vlastnost vazby na hodnotu můžete nastavit UserId z hlavičky pomocí vazbového výrazu: {headers.x-ms-client-principal-id} nebo {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')) };
    },
});

Vytvořte složku negotiate a aktualizujte negotiate/function.json a zkopírujte následující kódy JSON.

{
  "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"
    }
  ]
}

Definujte funkci v negotiate/init.py.

import logging

import azure.functions as func

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

Poznámka:

Dokončení ukázek pro tento jazyk čeká na vyřízení

Poznámka:

Rozšíření Web PubSub pro Javu se zatím nepodporují.

Konfigurace

Následující tabulka vysvětluje vlastnosti konfigurace vazby, které jste nastavili v souboru function.json a atributu WebPubSubConnection .

vlastnost function.json Vlastnost atributu Popis
typ Není k dispozici Musí být nastaveno na webPubSubConnection
směr Není k dispozici Musí být nastaveno na in
Jméno Není k dispozici Název proměnné použitý v kódu funkce pro vstupní objekt vazby připojení.
rozbočovač Centrum Povinné – Hodnota musí být nastavena na název centra Web PubSub, aby se funkce aktivovala. Podporujeme nastavení hodnoty v atributu jako vyšší prioritu nebo ji lze nastavit v nastavení aplikace jako globální hodnotu.
userId ID uživatele Volitelné – hodnota deklarace identity identifikátoru uživatele, která se má nastavit v tokenu přístupového klíče.
clientProtocol ClientProtocol Volitelné – typ klientského protokolu. Platné hodnoty zahrnují default a mqtt.
Pro klienty MQTT je nutné jej nastavit na mqtt.
U jiných klientů můžete vlastnost vynechat nebo ji nastavit na defaulthodnotu .
připojení Připojení Povinné – název nastavení aplikace, které obsahuje službu Web PubSub Service připojovací řetězec (výchozí hodnota je "WebPubSubConnectionString").

Využití

WebPubSubConnection poskytuje následující vlastnosti.

Název vazby Typ vazby Popis
BaseUri Identifikátor URI Identifikátor URI připojení klienta Web PubSub
Identifikátor URI Identifikátor URI Absolutní identifikátor URI připojení Web PubSub obsahuje AccessToken vygenerovaný základ požadavku.
AccessToken řetězec Vygenerováno AccessToken na základě id uživatele požadavku a informací o službě.

WebPubSubConnection poskytuje následující vlastnosti.

Název vazby Popis
základní URL Identifikátor URI připojení klienta Web PubSub
adresa URL Absolutní identifikátor URI připojení Web PubSub obsahuje AccessToken vygenerovaný základ požadavku.
accessToken Vygenerováno AccessToken na základě id uživatele požadavku a informací o službě.

Poznámka:

Rozšíření Web PubSub pro Javu se zatím nepodporují.

Další přizpůsobení vygenerovaného tokenu

Omezené na typy parametrů vazby nepodporují způsob předání seznamu ani pole, WebPubSubConnection není plně podporováno se všemi sadami SDK serveru parametrů, zejména rolesa zahrnuje groups a expiresAfter.

Pokud zákazník potřebuje přidat role nebo zpozdit sestavení přístupového tokenu ve funkci, doporučujeme vám pracovat se serverovou sadou SDK pro jazyk 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;
}

Pokud zákazník potřebuje přidat role nebo zpozdit sestavení přístupového tokenu ve funkci, doporučujeme vám pracovat se serverovou sadou SDK pro 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 };
    },
});

Poznámka:

Dokončení ukázek pro tento jazyk čeká na vyřízení

Poznámka:

Rozšíření Web PubSub pro Javu se zatím nepodporují.

WebPubSubContext

Příklad

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

Poznámka:

Dokončení ukázek pro tento jazyk čeká na vyřízení

Poznámka:

Rozšíření Web PubSub pro Javu se zatím nepodporují.

Konfigurace

Následující tabulka vysvětluje vlastnosti konfigurace vazby, které jste nastavili v souboru functions.json a atributu WebPubSubContext .

vlastnost function.json Vlastnost atributu Popis
typ Není k dispozici Musí být nastavena na webPubSubContexthodnotu .
směr Není k dispozici Musí být nastavena na inhodnotu .
Jméno Není k dispozici Název proměnné použitý v kódu funkce pro vstupní požadavek Web PubSub.
připojení Připojení Volitelné – název nastavení aplikace nebo nastavení kolekce, která určuje nadřazenou službu Azure Web PubSub. Hodnota se používá pro ochranu před zneužitím a ověřování podpisu. Ve výchozím nastavení se hodnota automaticky přeloží na WebPubSubConnectionString. A null znamená, že ověření není potřeba a vždy proběhne úspěšně.

Důležité

Pro zajištění optimálního zabezpečení by vaše aplikace funkcí měla používat spravované identity při připojování ke službě Web PubSub místo připojovacího řetězce, který obsahuje sdílený tajný klíč. Další informace naleznete v tématu Autorizace žádosti o spravovanou identitu pomocí Microsoft Entra ID.

Využití

WebPubSubContext poskytuje následující vlastnosti.

Název vazby Typ vazby Popis Vlastnosti
žádost WebPubSubEventRequest Žádost od klienta najdete v následující tabulce s podrobnostmi. WebPubSubConnectionContextz hlavičky požadavku a dalších vlastností deserializovaných z textu požadavku popisují požadavek, Reason například .DisconnectedEventRequest
odpověď HttpResponseMessage Rozšíření sestavuje odpověď hlavně pro AbuseProtection případy chyb a chyby. -
chybová zpráva řetězec Popište podrobnosti o chybě při zpracování upstreamového požadavku. -
hasError Booleova hodnota Příznak označující, jestli se jedná o platný upstreamový požadavek Web PubSub. -
isPreflight Booleova hodnota Příznak označující, jestli se jedná o předběžný požadavek AbuseProtection. -

V WebPubSubEventRequestpřípadě , je deserializována na různé třídy, které poskytují různé informace o scénáři žádosti. V PreflightRequest případě platných případů může uživatel zkontrolovat příznaky IsPreflight a HasError zjistit je. Doporučujeme vrátit odpověď WebPubSubContext.Response na sestavení systému přímo nebo zákazník může protokolovat chyby na vyžádání. V různých scénářích si zákazník může vlastnosti požadavku přečíst následujícím způsobem.

Odvozená třída Popis Vlastnosti
PreflightRequest Používá se v AbuseProtection případech, kdy IsPreflight je true -
ConnectEventRequest Používá se v Connect systémovém typu události. Deklarace identity, dotaz, subprotocols, ClientCertificates
ConnectedEventRequest Používá se v Connected systémovém typu události. -
UserEventRequest Používá se v typu události uživatele. Data, datový typ
DisconnectedEventRequest Používá se v Disconnected systémovém typu události. Důvod

Poznámka:

WebPubSubContext I když vstupní vazba poskytuje podobný způsob deserializace požadavků v porovnání HttpTriggerWebPubSubTriggers , existují omezení, tj. stav připojení po sloučení se nepodporuje. Odpověď na vrácení je stále respektována na straně služby, ale uživatelé vyžadují, aby sami vytvořili odpověď. Pokud uživatelé potřebují nastavit odpověď na událost, měli byste vrátit HttpResponseMessage obsah ConnectEventResponse nebo zprávy pro událost uživatele jako text odpovědi a vložit stav připojení s klíčem ce-connectionstate v hlavičce odpovědi.

  • Last updated on