Trigger di Azure Web PubSub e binding per Funzioni di Azure

Articolo
07/31/2024

Questo riferimento illustra come gestire gli eventi Web PubSub in Funzioni di Azure.

Web PubSub è un servizio gestito di Azure che consente agli sviluppatori di creare facilmente applicazioni Web con funzionalità in tempo reale e criteri di tipo pubblicazione-sottoscrizione.

Azione	Type
Eseguire una funzione quando i messaggi provengono dal servizio	Associazione di trigger
Associare la richiesta all'oggetto di destinazione in Trigger HTTP per le richieste di negoziazione e upstream	Associazione di input
Richiamare le azioni del servizio	Associazione di output

Codice sorgente | Pacchetto | Documentazione di riferimento dell'API | Documentazione del prodotto | Esempi

Aggiungere all'app Funzioni

Per usare i trigger e le associazioni è necessario fare riferimento al pacchetto appropriato. Il pacchetto NuGet viene usato per le librerie di classi .NET mentre il bundle di estensione viene usato per tutti gli altri tipi di applicazione.

Lingua	Aggiungi da...	Osservazioni:
C#	Installazione del pacchetto NuGet, versione non definitiva
Script C#, JavaScript, Python, PowerShell	Installare in modo esplicito le estensioni, Usare bundle di estensioni	È consigliabile usare l’estensione Strumenti di Azure con Visual Studio Code.
Script C# (solo online nel portale di Azure)	Aggiunta di un'associazione	Per aggiornare le estensioni delle associazioni esistenti senza dover ripubblicare l'app per le funzioni, vedere Aggiornare le estensioni.

Concetti chiave

Diagramma che mostra il flusso di lavoro del servizio Web PubSub di Azure che usa le app per le funzioni.

(1)-(2) associazione di input WebPubSubConnection con HttpTrigger per generare la connessione client.

(3)-(4) associazione di trigger WebPubSubTrigger oWebPubSubContext associazione di input con HttpTrigger per gestire la richiesta di servizio.

(5)-(6) associazione di output WebPubSub per richiedere il servizio eseguire un'operazione.

Associazione di trigger

Usare il trigger di funzione per gestire le richieste dal servizio Web PubSub di Azure.

WebPubSubTrigger viene usato quando è necessario gestire le richieste dal lato servizio. Il modello di endpoint trigger sarà simile al seguente, che deve essere impostato sul lato servizio Web PubSub (Portale: impostazioni -> gestore eventi -> Modello URL). Nel modello di endpoint, la parte code=<API_KEY> di query è OBBLIGATORIA quando si usa l'app per le funzioni di Azure per motivi di sicurezza. La chiave è disponibile nel portale di Azure. Trovare la risorsa dell'app per le funzioni e passare a Funzioni ->Chiavi app ->Chiavi di sistema ->webpubsub_extension dopo aver distribuito l'app per le funzioni in Azure. Tuttavia, questa chiave non è necessaria quando si lavora con le funzioni locali.

<Function_App_Url>/runtime/webhooks/webpubsub?code=<API_KEY>

Screenshot delle chiavi di sistema get function.

Esempio

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

L'associazione WebPubSubTrigger supporta anche il valore restituito negli scenari di sincronizzazione, ad esempio eventi Connect di sistema e utente, quando il server può controllare e negare la richiesta client o inviare messaggi direttamente al chiamante. L'evento Connect rispetta ConnectEventResponse e EventErrorResponse, e l’evento utente rispetta UserEventResponse e EventErrorResponse, i tipi rest che non corrispondono a uno scenario corrente vengono ignorati. Se viene restituito EventErrorResponse, il servizio elimina la connessione client.

[FunctionName("WebPubSubTriggerReturnValueFunction")]
public static UserEventResponse Run(
    [WebPubSubTrigger("hub", WebPubSubEventType.User, "message")] UserEventRequest request)
{
    return request.CreateResponse(BinaryData.FromString("ack"), WebPubSubDataType.Text);
}

L'esempio seguente mostra una funzione JavaScript trigger Web PubSub.

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

L'associazione WebPubSubTrigger supporta anche il valore restituito negli scenari di sincronizzazione, ad esempio eventi Connect di sistema e utente, quando il server può controllare e negare la richiesta client o inviare direttamente il messaggio al client di richiesta. Nel linguaggio tipizzato in JavaScript viene deserializzato in relazione alle chiavi dell'oggetto. E EventErrorResponse ha la priorità più alta rispetto agli oggetti rest, che se code è nel restituito, allora viene analizzata con EventErrorResponse e la connessione client viene eliminata.

app.generic('message', {
    trigger: wpsTrigger,
    handler: async (request, context) => {
          return { 
              "data": "ack",
              "dataType" : "text"
          };
    }
});

Definire l'associazione di trigger in function.json.

{
  "disabled": false,
  "bindings": [
    {
      "type": "webPubSubTrigger",
      "direction": "in",
      "name": "data",
      "hub": "<hub>",
      "eventName": "message",
      "eventType": "user"
    }
  ]
}

Definire la funzione 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);
}

L'associazione WebPubSubTrigger supporta anche il valore restituito negli scenari di sincronizzazione, ad esempio eventi Connect di sistema e utente, quando il server può controllare e negare la richiesta client o inviare direttamente il messaggio al client di richiesta. Nel linguaggio tipizzato in JavaScript viene deserializzato in relazione alle chiavi dell'oggetto. E EventErrorResponse ha la priorità più alta rispetto agli oggetti rest, che se code è nel restituito, allora viene analizzata con EventErrorResponse e la connessione client viene eliminata.

module.exports = async function (context) {
  return { 
    "data": "ack",
    "dataType" : "text"
  };
}

Attributi e annotazioni

Nelle librerie di classi C# usare l'attributo WebPubSubTrigger.

Di seguito è mostrato un attributo WebPubSubTrigger in una firma del metodo:

[FunctionName("WebPubSubTrigger")]
public static void Run([WebPubSubTrigger("<hub>", <WebPubSubEventType>, "<event-name>")] 
    WebPubSubConnectionContext context, ILogger log)
{
    ...
}

Per un esempio completo, vedere l'esempio in C#.

Impostazione

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json.

Proprietà di function.json	Proprietà dell'attributo	Descrizione
type	n/d	Obbligatoria. Deve essere impostata su `webPubSubTrigger`.
direction	n/d	Obbligatoria. Deve essere impostata su `in`.
name	n/d	Obbligatoria: nome della variabile usato nel codice della funzione per il parametro che riceve i dati dell'evento.
hub	Hub	Obbligatorio: il valore deve essere impostato sul nome dell'hub Web PubSub per attivare la funzione. È supportato impostare il valore nell'attributo come priorità più alta oppure può essere impostato nelle impostazioni dell'app come valore globale.
eventType	WebPubSubEventType	Obbligatorio: il valore deve essere impostato come tipo di evento di messaggi per la funzione da attivare. Il valore deve essere `user` o `system`.
eventName	EventName	Obbligatorio: il valore deve essere impostato come evento dei messaggi per l'attivazione della funzione. Per il tipo di evento `system`, il nome dell'evento deve essere in `connect`, `connected`, `disconnected`. Per i sottoprotocoli definiti dall'utente, il nome dell'evento è `message`. Per il sottoprotocollo `json.webpubsub.azure.v1.` supportato dal sistema, il nome dell'evento è il nome dell'evento definito dall'utente.
connection	Connessione	Facoltativo: il nome di una raccolta di impostazioni o impostazioni dell'app che specifica il servizio Web PubSub di Azure upstream. Il valore viene utilizzato per la convalida della firma. Il valore viene risolto automaticamente con le impostazioni dell'app "WebPubSubConnectionString" per impostazione predefinita. E `null` significa che la convalida non è necessaria e ha sempre esito positivo.

Usi

In C#, WebPubSubEventRequest è un parametro di associazione riconosciuto dal tipo, i parametri rest sono associati in base al nome del parametro. Controllare la tabella seguente dei parametri e dei tipi disponibili.

In un linguaggio tipizzato debole come JavaScript, name in function.json viene usato per associare l'oggetto trigger relativo alla tabella di mapping seguente. E rispettare dataType in function.json per convertire il messaggio di conseguenza quando name è impostato su data come oggetto di associazione per l'input del trigger. Tutti i parametri possono essere letti da context.bindingData.<BindingName> ed è JObject convertito.

Nome associazione	Tipo di associazione	Descrizione	Proprietà
request	`WebPubSubEventRequest`	Descrive la richiesta upstream	La proprietà è diversa dai diversi tipi di evento, incluse le classi derivate `ConnectEventRequest`, `ConnectedEventRequest`, `UserEventRequest` e `DisconnectedEventRequest`
connectionContext	`WebPubSubConnectionContext`	Informazioni comuni sulle richieste	EventType, EventName, Hub, ConnectionId, UserId, Headers, Origin, Signature, States
data	`BinaryData`,`string`,`Stream`,`byte[]`	Richiedere i dati dei messaggi dal client nell'evento utente `message`	-
dataType	`WebPubSubDataType`	Richiedere dataType del messaggio, che supporta `binary`, `text`, `json`	-
claims	`IDictionary<string, string[]>`	Attestazioni utente nella richiesta di sistema `connect`	-
query	`IDictionary<string, string[]>`	Query utente nella richiesta di sistema `connect`	-
sottoprotocolli	`IList<string>`	Sottoprotocolli disponibili nella richiesta di sistema `connect`	-
clientCertificates	`IList<ClientCertificate>`	Elenco dell'identificazione personale del certificato dai client nella richiesta di sistema `connect`	-
reason	`string`	Motivo nella richiesta di sistema `disconnected`	-

Importante

In C#, il parametro supportato da più tipi DEVE essere inserito nel primo, ovvero request o data diverso dal tipo predefinito BinaryData per rendere corretta l'associazione della funzione.

Restituire la risposta

WebPubSubTrigger rispetta la risposta restituita dal cliente per gli eventi sincroni di connect e l'evento utente. Solo la risposta corrispondente viene inviata al servizio. In caso contrario, viene ignorata. Inoltre, l'oggetto restituito WebPubSubTrigger supporta gli utenti a SetState() e ClearStates() per gestire i metadati per la connessione. L'estensione unisce i risultati del valore restituito con quelli originali dalla richiesta WebPubSubConnectionContext.States. Il valore nella chiave esistente è sovrascritto e viene aggiunto il valore nella nuova chiave.

Tipo restituito	Descrizione	Proprietà
`ConnectEventResponse`	Risposta per l'evento `connect`	Gruppi, Ruoli, UserId, Sottoprotocollo
`UserEventResponse`	Risposta per l'evento utente	DataType, Dati
`EventErrorResponse`	Risposta di errore per l'evento di sincronizzazione	Codice, ErrorMessage
`*WebPubSubEventResponse`	Tipo di risposta di base di quelli supportati usati per i casi di restituzione incerti	-

Associazione di input

L'estensione fornisce due associazioni di input destinate a esigenze diverse.

WebPubSubConnection

Per consentire a un client di connettersi al servizio Web PubSub di Azure, deve conoscere l'URL dell'endpoint del servizio e un token di accesso valido. L'associazione di input WebPubSubConnection produce informazioni necessarie, quindi il client non deve gestire questa generazione di token. Poiché il token è limitato al tempo e può essere usato per autenticare un utente specifico a una connessione, non memorizzare nella cache il token o condividerlo tra i client. Un trigger HTTP che usa questa associazione di input può essere usato per i client per recuperare le informazioni di connessione.
WebPubSubContext

Quando si usa app Web statiche, HttpTrigger è l'unico trigger supportato e, in uno scenario Web PubSub, viene fornita l'associazione di input WebPubSubContext che consente agli utenti di deserializzare la richiesta HTTP upstream dal lato servizio nei protocolli Web PubSub. I clienti possono quindi ottenere risultati simili rispetto a WebPubSubTrigger per gestire facilmente le funzioni. Vedere gli esempi riportati di seguito. Se usato con HttpTrigger, il cliente deve configurare di conseguenza l'URL esposto httpTrigger nel gestore eventi.

Esempio - `WebPubSubConnection`

L'esempio seguente illustra una funzione C# che acquisisce le informazioni di connessione Web PubSub usando l'associazione di input e la restituisce su HTTP. Nell'esempio seguente, il UserId viene passato tramite la parte di query della richiesta client, ad esempio ?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')) };
    },
});

Definire le associazioni di input 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"
    }
  ]
}

Definire la funzione in index.js.

module.exports = function (context, req, connection) {
  context.res = { body: connection };
  context.done();
};

Token autenticati

Se la funzione viene attivata da un client autenticato, è possibile aggiungere un'attestazione ID utente al token generato. È possibile aggiungere facilmente l'autenticazione a un'app per le funzioni usando l'autenticazione del servizio app.

Autenticazione servizio App imposta le intestazioni HTTP denominate x-ms-client-principal-id e x-ms-client-principal-name contenenti rispettivamente l'ID e il nome dell'entità client dell'utente autenticato.

È possibile impostare la proprietà UserId dell'associazione sul valore da un'intestazione usando un'espressione di associazione: {headers.x-ms-client-principal-id} o {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;
}

Nota

Limitato ai tipi di parametri di associazione non supportano un modo per passare l'elenco né la matrice, il WebPubSubConnection non è completamente supportato con tutti i parametri SDK del server, in particolare roles, e include anche groups e expiresAfter. Nel caso in cui il cliente debba aggiungere ruoli o ritardare la compilazione del token di accesso nella funzione, è consigliabile usare server SDK per C#.

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

Nota

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

Nota

Definire le associazioni di input in function.json.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ]
}

Definire la funzione 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();
};

Esempio - `WebPubSubContext`

L'esempio seguente illustra una funzione C# che acquisisce informazioni sulla richiesta upstream Web PubSub usando l'associazione di input nel tipo di evento connect e la restituisce su HTTP.

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

Definire le associazioni di input 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"
    }
  ]
}

Definire la funzione 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} };
};

Impostazione

WebPubSubConnection

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json e nell'attributo WebPubSubConnection.

Proprietà di function.json	Proprietà dell'attributo	Descrizione
type	n/d	Deve essere impostato su `webPubSubConnection`
direction	n/d	Deve essere impostato su `in`
name	n/d	Nome della variabile usato nel codice della funzione per l'oggetto di associazione di connessione di input.
hub	Hub	Obbligatorio: il valore deve essere impostato sul nome dell'hub Web PubSub per attivare la funzione. È supportato impostare il valore nell'attributo come priorità più alta oppure può essere impostato nelle impostazioni dell'app come valore globale.
userId	ID utente	Facoltativo: valore dell'attestazione dell'identificatore utente da impostare nel token della chiave di accesso.
connection	Connessione	Obbligatorio: nome dell'impostazione dell'app che contiene la stringa di connessione del servizio Web PubSub (il valore predefinito è "WebPubSubConnectionString").

WebPubSubContext

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json e nell'attributo WebPubSubContext.

Proprietà di function.json	Proprietà dell'attributo	Descrizione
type	n/d	Deve essere impostato su `webPubSubContext`.
direction	n/d	Deve essere impostato su `in`.
name	n/d	Nome della variabile usato nel codice della funzione per la richiesta Web PubSub di input.
connection	Connessione	Facoltativo: il nome di una raccolta di impostazioni o impostazioni dell'app che specifica il servizio Web PubSub di Azure upstream. Il valore viene usato per la convalida della protezione da abusi e della firma. Il valore viene risolto automaticamente con "WebPubSubConnectionString" per impostazione predefinita. E `null` significa che la convalida non è necessaria e ha sempre esito positivo.

Utilizzo

WebPubSubConnection

WebPubSubConnection fornisce le proprietà seguenti.

Nome associazione	Tipo di associazione	Descrizione
BaseUri	URI	URI connessione client PubSub Web.
URI	URI	L'URI assoluto della connessione Web PubSub contiene la base generata `AccessToken` sulla richiesta.
AccessToken	string	Generato `AccessToken` in base alle informazioni relative a UserId e al servizio richieste.

WebPubSubConnection fornisce le proprietà seguenti.

Nome associazione	Descrizione
baseUrl	URI connessione client PubSub Web.
URL.	L'URI assoluto della connessione Web PubSub contiene la base generata `AccessToken` sulla richiesta.
accessToken	Generato `AccessToken` in base alle informazioni relative a UserId e al servizio richieste.

WebPubSubConnection fornisce le proprietà seguenti.

Nome associazione	Descrizione
baseUrl	URI connessione client PubSub Web.
URL.	L'URI assoluto della connessione Web PubSub contiene la base generata `AccessToken` sulla richiesta.
accessToken	Generato `AccessToken` in base alle informazioni relative a UserId e al servizio richieste.

WebPubSubContext

WebPubSubContext fornisce le proprietà seguenti.

Nome associazione	Tipo di associazione	Descrizione	Proprietà
request	`WebPubSubEventRequest`	Per informazioni dettagliate, vedere la tabella seguente.	`WebPubSubConnectionContext` dall'intestazione della richiesta e da altre proprietà deserializzate dal corpo della richiesta, ad esempio `Reason` per `DisconnectedEventRequest`.
Risposta	`HttpResponseMessage`	L'estensione compila principalmente la risposta per `AbuseProtection` e i casi di errore.	-
errorMessage	string	Descrivere i dettagli dell'errore durante l'elaborazione della richiesta upstream.	-
hasError	bool	Flag per indicare se si tratta di una richiesta upstream web PubSub valida.	-
isPreflight	bool	Flag per indicare se si tratta di una richiesta preliminare di `AbuseProtection`.	-

Per WebPubSubEventRequest, viene deserializzato in classi diverse che forniscono informazioni diverse sullo scenario di richiesta. Per PreflightRequest o casi non validi, l'utente può controllare i flag IsPreflight e HasError da conoscere. È consigliabile restituire direttamente la risposta alla compilazione del sistema WebPubSubContext.Response oppure il cliente può registrare errori su richiesta. In scenari diversi, il cliente può leggere le proprietà della richiesta come indicato di seguito.

Classe derivata	Descrizione	Proprietà
`PreflightRequest`	Usato in `AbuseProtection` quando `IsPreflight` è true	-
`ConnectEventRequest`	Usato nel tipo di evento di sistema `Connect`	Claims, Query, Subprotocols, ClientCertificates
`ConnectedEventRequest`	Usato nel tipo di evento di sistema `Connected`	-
`UserEventRequest`	Usato nel tipo di evento utente	Data, DataType
`DisconnectedEventRequest`	Usato nel tipo di evento di sistema `Disconnected`	Motivo

Nota

Anche se WebPubSubContext è un'associazione di input fornisce un metodo di deserializzazione di richieste in HttpTriggersimile a WebPubSubTrigger, esistono delle limitazioni, ad esempio lo stato della connessione dopo l'unione non è supportato. La risposta restituita viene comunque rispettata dal lato servizio, ma gli utenti devono compilare autonomamente la risposta. Se gli utenti devono impostare la risposta all'evento, è necessario restituire un oggetto HttpResponseMessage contenente ConnectEventResponse o messaggi per l'evento utente come corpo della risposta e impostare lo stato della connessione con la chiave ce-connectionstate nell'intestazione della risposta.

Associazione di output

Usare l'associazione di output Web PubSub per richiamare il servizio PubSub di Azure per eseguire un'operazione. È possibile trasmettere un messaggio a:

Tutti i client connessi
Client connessi autenticati a un utente specifico
Client connessi aggiunti a un gruppo specifico
Una connessione client specifica

L'associazione di output consente anche di gestire client e gruppi, nonché di concedere/revocare autorizzazioni destinate a un connectionId specifico con gruppo.

Aggiungere una connessione al gruppo
Aggiungere utenti al gruppo
Rimuovere la connessione da un gruppo
Rimuovere l'utente da un gruppo
Rimuovere l'utente da tutti i gruppi
Chiudere tutte le connessioni client
Chiudere una connessione client specifica
Chiudere le connessioni in un gruppo
Concedere l'autorizzazione di una connessione
Revocare l'autorizzazione di una connessione

Per informazioni sui dettagli di impostazione e configurazione, vedere la panoramica.

Esempio

[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`
        }]);
    }
});

Definire le associazioni in functions.json.

{
  "disabled": false,
  "bindings": [
    {
      "type": "webPubSub",
      "name": "actions",
      "hub": "<hub>",
      "direction": "out"
    }
  ]
}

Definire la funzione in index.js.

module.exports = async function (context) {
  context.bindings.actions = {
    "actionName": "sendToAll",
    "data": "hello",
    "dataType": "text"
  };
  context.done();
}

WebPubSubAction

WebPubSubAction è il tipo astratto di base delle associazioni di output. I tipi derivati rappresentano il server di azione che desidera richiamare il servizio.

Nel linguaggio C# sono disponibili alcuni metodi statici in WebPubSubAction per individuare le azioni disponibili. Ad esempio, l'utente può creare l'oggetto SendToAllAction chiamando WebPubSubAction.CreateSendToAllAction().

Classe derivata	Proprietà
`SendToAllAction`	Dati, DataType, Escluso
`SendToGroupAction`	Gruppo, Dati, DataType, Escluso
`SendToUserAction`	UserId, Dati, DataType
`SendToConnectionAction`	ConnectionId, Dati, DataType
`AddUserToGroupAction`	UserId, Gruppo
`RemoveUserFromGroupAction`	UserId, Gruppo
`RemoveUserFromAllGroupsAction`	ID utente
`AddConnectionToGroupAction`	ConnectionId, Gruppo
`RemoveConnectionFromGroupAction`	ConnectionId, Gruppo
`CloseAllConnectionsAction`	Escluso, Motivo
`CloseClientConnectionAction`	ConnectionId, Motivo
`CloseGroupConnectionsAction`	Gruppo, Escluso, Motivo
`GrantPermissionAction`	ConnectionId, Autorizzazione, TargetName
`RevokePermissionAction`	ConnectionId, Autorizzazione, TargetName

Nel linguaggio tipizzato debole come javascript, actionName è il parametro chiave per risolvere il tipo, le azioni disponibili sono elencate di seguito.

ActionName	Proprietà
`sendToAll`	Dati, DataType, Escluso
`sendToGroup`	Gruppo, Dati, DataType, Escluso
`sendToUser`	UserId, Dati, DataType
`sendToConnection`	ConnectionId, Dati, DataType
`addUserToGroup`	UserId, Gruppo
`removeUserFromGroup`	UserId, Gruppo
`removeUserFromAllGroups`	ID utente
`addConnectionToGroup`	ConnectionId, Gruppo
`removeConnectionFromGroup`	ConnectionId, Gruppo
`closeAllConnections`	Escluso, Motivo
`closeClientConnection`	ConnectionId, Motivo
`closeGroupConnections`	Gruppo, Escluso, Motivo
`grantPermission`	ConnectionId, Autorizzazione, TargetName
`revokePermission`	ConnectionId, Autorizzazione, TargetName

Importante

La proprietà dei dati del messaggio nelle azioni correlate al messaggio di invio deve essere string se il tipo di dati è impostato su json o text per evitare ambiguità di conversione dei dati. Usare JSON.stringify() per convertire l'oggetto json in caso di necessità. Questa operazione viene applicata a qualsiasi posizione usando la proprietà del messaggio, ad esempio UserEventResponse.Data che usa WebPubSubTrigger.

Quando il tipo di dati è impostato su binary, è consentito sfruttare l'associazione supportata naturalmente dataType come binary configurato in function.json, vedere Trigger e definizioni di associazione per informazioni dettagliate.

Nel linguaggio tipizzato debole come javascript, actionName è il parametro chiave per risolvere il tipo, le azioni disponibili sono elencate di seguito.

ActionName	Proprietà
`sendToAll`	Dati, DataType, Escluso
`sendToGroup`	Gruppo, Dati, DataType, Escluso
`sendToUser`	UserId, Dati, DataType
`sendToConnection`	ConnectionId, Dati, DataType
`addUserToGroup`	UserId, Gruppo
`removeUserFromGroup`	UserId, Gruppo
`removeUserFromAllGroups`	ID utente
`addConnectionToGroup`	ConnectionId, Gruppo
`removeConnectionFromGroup`	ConnectionId, Gruppo
`closeAllConnections`	Escluso, Motivo
`closeClientConnection`	ConnectionId, Motivo
`closeGroupConnections`	Gruppo, Escluso, Motivo
`grantPermission`	ConnectionId, Autorizzazione, TargetName
`revokePermission`	ConnectionId, Autorizzazione, TargetName

Importante

Impostazione

WebPubSub

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json e nell'attributo WebPubSub.

Proprietà di function.json	Proprietà dell'attributo	Descrizione
type	n/d	Deve essere impostato su `webPubSub`
direction	n/d	Deve essere impostato su `out`
name	n/d	Nome della variabile usato nel codice della funzione per l'oggetto di associazione di output.
hub	Hub	Il valore deve essere impostato sul nome dell'hub Web PubSub per attivare la funzione. È supportato impostare il valore nell'attributo come priorità più alta oppure può essere impostato nelle impostazioni dell'app come valore globale.
connection	Connessione	Nome dell'impostazione dell'app che contiene la stringa di connessione del servizio Web PubSub (il valore predefinito è "WebPubSubConnectionString").

Risoluzione dei problemi

Configurazione della registrazione della console

È anche possibile abilitare facilmente la registrazione della console se si vuole approfondire le richieste eseguite con il servizio.

Passaggi successivi

Usare queste risorse per iniziare a compilare un'applicazione personalizzata:

Esercitazione: Pubblicare e sottoscrivere messaggi in Azure Web PubSub

Esercitazione: Creare una chatroom semplice con Azure Web PubSub

Esercitazione: Usare un sottoprotocollo supportato dal servizio per lo streaming client

Esercitazione: Compilare una chat serverless con Funzioni di Azure e Web PubSub

Esercitazione: Configurare un listener di eventi

Riprodurre con demo live

Esplorare altri esempi di Azure Web PubSub

Condividi tramite

Trigger di Azure Web PubSub e binding per Funzioni di Azure

Aggiungere all'app Funzioni

Concetti chiave

Associazione di trigger

Esempio

Attributi e annotazioni

Impostazione

Usi

Restituire la risposta

Associazione di input

Esempio - `WebPubSubConnection`

Token autenticati

Esempio - `WebPubSubContext`

Impostazione

WebPubSubConnection

WebPubSubContext

Utilizzo

WebPubSubConnection

WebPubSubContext

Associazione di output

Esempio

WebPubSubAction

Impostazione

WebPubSub

Risoluzione dei problemi

Configurazione della registrazione della console

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Trigger di Azure Web PubSub e binding per Funzioni di Azure

Aggiungere all'app Funzioni

Concetti chiave

Associazione di trigger

Esempio

Attributi e annotazioni

Impostazione

Usi

Restituire la risposta

Associazione di input

Esempio - WebPubSubConnection

Token autenticati

Esempio - WebPubSubContext

Impostazione

WebPubSubConnection

WebPubSubContext

Utilizzo

WebPubSubConnection

WebPubSubContext

Associazione di output

Esempio

WebPubSubAction

Impostazione

WebPubSub

Risoluzione dei problemi

Configurazione della registrazione della console

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Esempio - `WebPubSubConnection`

Esempio - `WebPubSubContext`