Udostępnij przez

Powiązania wejściowe usługi Azure Web PubSub dla usługi Azure Functions

Nasze rozszerzenie udostępnia dwa powiązania wejściowe przeznaczone dla różnych potrzeb.

  • WebPubSubConnection

    Aby umożliwić klientowi nawiązanie połączenia z usługą Azure Web PubSub Service, musi on znać adres URL punktu końcowego usługi i prawidłowy token dostępu. Powiązanie WebPubSubConnection wejściowe generuje wymagane informacje, więc klient nie musi obsługiwać samego generowania tokenu. Token jest ograniczony czasowo i może uwierzytelnić określonego użytkownika w połączeniu. W związku z tym nie buforuj tokenu ani nie udostępniaj go między klientami. Wyzwalacz HTTP pracujący z tym powiązaniem wejściowym może służyć klientom do pobierania informacji o połączeniu.

  • WebPubSubContext

    W przypadku korzystania z usługi Static Web Apps HttpTrigger jest jedynym obsługiwanym wyzwalaczem. W scenariuszach WebPubSubContext Web PubSub powiązanie wejściowe pomaga użytkownikom deserializować nadrzędne żądania HTTP z usługi w ramach protokołów Web PubSub. Dzięki temu klienci mogą uzyskać podobne wyniki w porównaniu do WebPubSubTrigger łatwego obsługi w funkcjach. W przypadku użycia z HttpTriggerprogramem klient musi odpowiednio skonfigurować adres URL uwidoczniony przez narzędzie HttpTrigger w procedurze obsługi zdarzeń.

WebPubSubConnection

Przykład

W poniższym przykładzie przedstawiono funkcję wyzwalacza HTTP, która uzyskuje informacje o połączeniu Web PubSub przy użyciu powiązania wejściowego i zwraca je za pośrednictwem protokołu HTTP. W poniższym przykładzie element UserId jest przekazywany za pośrednictwem części zapytania żądania klienta, takiej jak ?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')) };
    },
});

Utwórz folder negocjując i aktualizuj negocjując/function.json i kopiując następujące kody 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"
    }
  ]
}

Zdefiniuj funkcję w pliku negotiate/init.py.

import logging

import azure.functions as func

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

Uwaga

Kompletne przykłady dla tego języka są oczekujące

Uwaga

Rozszerzenia Web PubSub dla języka Java nie są jeszcze obsługiwane.

Uzyskiwanie uwierzytelnioowanego identyfikatora użytkownika

Jeśli funkcja jest wyzwalana przez uwierzytelnionego klienta, możesz dodać oświadczenie identyfikatora użytkownika do wygenerowanego tokenu. Uwierzytelnianie można łatwo dodać do aplikacji funkcji przy użyciu uwierzytelniania usługi App Service.

Uwierzytelnianie usługi App Service ustawia nagłówki HTTP o nazwie x-ms-client-principal-id i x-ms-client-principal-name zawierają odpowiednio identyfikator jednostki klienta i nazwę uwierzytelnionego użytkownika.

Właściwość powiązania można ustawić UserId na wartość z nagłówka przy użyciu wyrażenia powiązania: {headers.x-ms-client-principal-id} lub {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')) };
    },
});

Utwórz folder negocjując i aktualizuj negocjując/function.json i kopiując następujące kody 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"
    }
  ]
}

Zdefiniuj funkcję w pliku negotiate/init.py.

import logging

import azure.functions as func

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

Uwaga

Kompletne przykłady dla tego języka są oczekujące

Uwaga

Rozszerzenia Web PubSub dla języka Java nie są jeszcze obsługiwane.

Konfigurowanie

W poniższej tabeli opisano właściwości konfiguracji powiązania ustawione w pliku function.json i atrybut.WebPubSubConnection

właściwość function.json Właściwość atrybutu opis
typ nie dotyczy Musi być ustawiona na webPubSubConnection
kierunek nie dotyczy Musi być ustawiona na in
nazwa nie dotyczy Nazwa zmiennej używana w kodzie funkcji dla obiektu powiązania połączenia wejściowego.
koncentrator Piasta Wymagane — wartość musi być ustawiona na nazwę centrum Web PubSub, aby funkcja została wyzwolona. Obsługujemy ustawianie wartości w atrybucie jako wyższy priorytet lub można ją ustawić w ustawieniach aplikacji jako wartość globalną.
userId Identyfikator użytkownika Opcjonalnie — wartość oświadczenia identyfikatora użytkownika, która ma zostać ustawiona w tokenie klucza dostępu.
clientProtocol ClientProtocol Opcjonalnie — typ protokołu klienta. Prawidłowe wartości to default i mqtt.
W przypadku klientów MQTT należy ustawić go na mqtt.
W przypadku innych klientów można pominąć właściwość lub ustawić ją na default.
połączenie Połączenie Wymagane — nazwa ustawienia aplikacji zawierającego usługę Web PubSub Service parametry połączenia (domyślnie to "WebPubSubConnectionString").

Użycie

WebPubSubConnection udostępnia następujące właściwości.

Nazwa powiązania Typ powiązania opis
Identyfikator BaseUri Identyfikator URI Identyfikator URI połączenia klienta web PubSub.
Identyfikator URI Identyfikator URI Bezwzględny identyfikator URI połączenia Web PubSub zawiera AccessToken wygenerowaną bazę na żądanie.
Token dostępu ciąg AccessToken Generowane na podstawie identyfikatora UserId żądania i informacji o usłudze.

WebPubSubConnection udostępnia następujące właściwości.

Nazwa powiązania opis
podstawowy URL Identyfikator URI połączenia klienta web PubSub.
Adres URL Bezwzględny identyfikator URI połączenia Web PubSub zawiera AccessToken wygenerowaną bazę na żądanie.
accessToken AccessToken Generowane na podstawie identyfikatora UserId żądania i informacji o usłudze.

Uwaga

Rozszerzenia Web PubSub dla języka Java nie są jeszcze obsługiwane.

Więcej dostosowywania wygenerowanego tokenu

Ograniczone do typów parametrów powiązania nie obsługują sposobu przekazywania listy ani tablicy, WebPubSubConnection ale nie jest w pełni obsługiwany ze wszystkimi parametrami zestawu SDK serwera, zwłaszcza roles, a także zawiera groups i expiresAfter.

Gdy klient musi dodać role lub opóźnić tworzenie tokenu dostępu w funkcji, zalecamy pracę z zestawem SDK serwera dla języka 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;
}

Gdy klient musi dodać role lub opóźnić tworzenie tokenu dostępu w funkcji, zalecamy pracę z zestawem SDK serwera dla języka 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 };
    },
});

Uwaga

Kompletne przykłady dla tego języka są oczekujące

Uwaga

Rozszerzenia Web PubSub dla języka Java nie są jeszcze obsługiwane.

WebPubSubContext

Przykład

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

Uwaga

Kompletne przykłady dla tego języka są oczekujące

Uwaga

Rozszerzenia Web PubSub dla języka Java nie są jeszcze obsługiwane.

Konfigurowanie

W poniższej tabeli opisano właściwości konfiguracji powiązania ustawione w pliku functions.json i atrybutu WebPubSubContext .

właściwość function.json Właściwość atrybutu opis
typ nie dotyczy Musi być ustawiona wartość webPubSubContext.
kierunek nie dotyczy Musi być ustawiona wartość in.
nazwa nie dotyczy Nazwa zmiennej używana w kodzie funkcji dla wejściowego żądania Web PubSub.
połączenie Połączenie Opcjonalnie — nazwa ustawień aplikacji lub kolekcji ustawień, która określa nadrzędną usługę Azure Web PubSub. Wartość jest używana na potrzeby ochrony przed nadużyciami i weryfikacji podpisu. Wartość jest automatycznie rozpoznawana za pomocą polecenia "WebPubSubConnectionString" domyślnie. Oznacza to null , że weryfikacja nie jest potrzebna i zawsze kończy się powodzeniem.

Ważne

Aby zapewnić optymalne zabezpieczenia, aplikacja funkcji powinna używać tożsamości zarządzanych podczas nawiązywania połączenia z usługą Web PubSub zamiast używać parametrów połączenia, które zawierają wspólny klucz tajny. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądania tożsamości zarządzanej przy użyciu identyfikatora Entra firmy Microsoft.

Użycie

WebPubSubContext udostępnia następujące właściwości.

Nazwa powiązania Typ powiązania opis Właściwości
żądanie WebPubSubEventRequest Aby uzyskać szczegółowe informacje, zobacz poniższą tabelę. WebPubSubConnectionContext z nagłówka żądania i inne właściwości deserializowane z treści żądania opisują żądanie, na przykład Reason dla DisconnectedEventRequest.
odpowiedź HttpResponseMessage Rozszerzenie tworzy odpowiedź głównie w przypadku AbuseProtection przypadków błędów i . -
komunikat o błędzie ciąg Opisz szczegóły błędu podczas przetwarzania nadrzędnego żądania. -
hasError Bool Flaga wskazująca, czy jest to prawidłowe żądanie nadrzędne Web PubSub. -
isPreflight Bool Flaga wskazująca, czy jest to żądanie wstępne .AbuseProtection -

W przypadku WebPubSubEventRequestprogramu jest deserializowany do różnych klas, które zawierają różne informacje o scenariuszu żądania. W przypadku PreflightRequest nieprawidłowych przypadków użytkownik może sprawdzić flagi IsPreflight i HasError wiedzieć. Zalecamy bezpośrednie zwrócenie odpowiedzi kompilacji WebPubSubContext.Response systemu lub klient może rejestrować błędy na żądanie. W różnych scenariuszach klient może odczytać właściwości żądania w następujący sposób.

Klasa pochodna opis Właściwości
PreflightRequest Używany w AbuseProtection przypadku, gdy IsPreflight ma wartość true -
ConnectEventRequest Używane w typie zdarzeń systemowych Connect Oświadczenia, zapytanie, podprotocols, ClientCertificates
ConnectedEventRequest Używane w typie zdarzeń systemowych Connected -
UserEventRequest Używany w typie zdarzenia użytkownika Dane, Typ danych
DisconnectedEventRequest Używane w typie zdarzeń systemowych Disconnected Przyczyna

Uwaga

WebPubSubContext Chociaż jest to powiązanie wejściowe zapewnia podobny sposób deserializacji żądania w HttpTrigger porównaniu z WebPubSubTrigger, istnieją ograniczenia, tj. stan połączenia po scaleniu nie jest obsługiwany. Odpowiedź zwrotna jest nadal przestrzegana przez usługę, ale użytkownicy muszą sami utworzyć odpowiedź. Jeśli użytkownicy muszą ustawić odpowiedź na zdarzenie, należy zwrócić HttpResponseMessage komunikaty zawierające ConnectEventResponse lub dla zdarzenia użytkownika jako treść odpowiedzi i umieścić stan połączenia z kluczem ce-connectionstate w nagłówku odpowiedzi.

  • Last updated on