Trigger di Azure Web PubSub e binding per Funzioni di Azure
Questo riferimento illustra come gestire gli eventi Web PubSub in Funzioni di Azure.
Web PubSub è un servizio gestito da Azure che consente agli sviluppatori di creare facilmente applicazioni Web con funzionalità in tempo reale e modello di 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 |
Documentazione di riferimento dell'API del pacchetto | del codice | sorgente Esempi di documentazione | | del prodotto
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 in portale di Azure) | Aggiunta di un'associazione | Per aggiornare le estensioni di binding esistenti senza dover ripubblicare l'app per le funzioni, vedere Aggiornare le estensioni. |
Concetti chiave
(1)-(2) associazione WebPubSubConnection
di input con HttpTrigger per generare la connessione client.
(3)-(4) associazione WebPubSubTrigger
di trigger o WebPubSubContext
associazione di input con HttpTrigger per gestire la richiesta di servizio.
(5)-(6) WebPubSub
associazione di output 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 in 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>
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}");
}
WebPubSubTrigger
L'associazione supporta anche il valore restituito negli scenari di sincronizzazione, ad esempio eventi di sistema Connect
e utente, quando il server può controllare e negare la richiesta client o inviare messaggi direttamente al chiamante. Connect
l'evento rispetta e e EventErrorResponse
l'evento utente rispetta ConnectEventResponse
UserEventResponse
e EventErrorResponse
, i tipi rest che non corrispondono a uno scenario corrente vengono ignorati. Se viene restituito, il EventErrorResponse
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);
}
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 system il tipo di evento, il nome dell'evento deve essere in connect , connected , disconnected . Per i sottoprotocoli definiti dall'utente, il nome dell'evento è message . Per il sottoprotocolo 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 "WebPubSub Connessione ionString" per impostazione predefinita. Significa null 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
per function.json
convertire il messaggio di conseguenza quando name
è impostato data
su come oggetto di associazione per l'input del trigger. Tutti i parametri possono essere letti da context.bindingData.<BindingName>
e vengono JObject
convertiti.
Nome associazione | Tipo di associazione | Descrizione | Proprietà |
---|---|---|---|
request | WebPubSubEventRequest |
Descrive la richiesta upstream | La proprietà è diversa dai diversi tipi di evento, incluse le classi ConnectEventRequest derivate , ConnectedEventRequest e UserEventRequest DisconnectedEventRequest |
Connectioncontext | WebPubSubConnectionContext |
Informazioni comuni sulle richieste | EventType, EventName, Hub, Connessione ionId, UserId, Headers, Origin, Signature, States |
data | BinaryData ,string ,Stream ,byte[] |
Richiedere i dati dei messaggi dal client nell'evento utente message |
- |
dataType | WebPubSubDataType |
Request message dataType, 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 |
- |
sottoprotocols | IList<string> |
Sottoprotocol 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
che 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 e l'evento connect
utente. Solo la risposta corrispondente viene inviata al servizio. In caso contrario, viene ignorata. Inoltre, WebPubSubTrigger
l'oggetto restituito 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 connect l'evento |
Gruppi, Ruoli, UserId, Subprotocol |
UserEventResponse |
Risposta per l'evento utente | DataType, Data |
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
WebPubSubConnection
di input 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, nello scenario Web PubSub, viene fornita l'associazioneWebPubSubContext
di input 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 aWebPubSubTrigger
quelli che possono essere gestiti facilmente nelle funzioni. Vedere gli esempi riportati di seguito. Se usato conHttpTrigger
, 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, l'oggetto UserId
viene passato tramite la parte di query della richiesta client, ad ?userid={User-A}
esempio .
[FunctionName("WebPubSubConnectionInputBinding")]
public static WebPubSubConnection Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
[WebPubSubConnection(Hub = "<hub>", UserId = "{query.userid}")] WebPubSubConnection connection)
{
return connection;
}
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 servizio app l'autenticazione.
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 un elenco o una matrice, non WebPubSubConnection
è completamente supportato con tutti i parametri sdk del server, in particolare roles
, e include groups
anche 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);
}
Esempio- WebPubSubContext
L'esempio seguente mostra una funzione C# che acquisisce informazioni sulla richiesta upstream Web PubSub usando l'associazione di input nel connect
tipo di evento 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;
}
Impostazione
WebPubSub Connessione ion
La tabella seguente illustra 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: il nome dell'impostazione dell'app che contiene l'stringa di connessione del servizio Web PubSub (per impostazione predefinita è "WebPubSub Connessione ionString"). |
WebPubSubContext
La tabella seguente illustra le proprietà di configurazione dell'associazione impostate nel file functions.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 "WebPubSub Connessione ionString" per impostazione predefinita. Significa null che la convalida non è necessaria e ha sempre esito positivo. |
Utilizzo
WebPubSub Connessione ion
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 AccessToken la base generata sulla richiesta. |
AccessToken | string | 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 descrivono la richiesta, Reason ad esempio per DisconnectedEventRequest . |
risposta | HttpResponseMessage |
L'estensione compila principalmente la risposta per AbuseProtection i casi di errori e . |
- |
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 non validi casi, l'utente può controllare i IsPreflight
flag e HasError
sapere. È consigliabile restituire direttamente la risposta alla compilazione WebPubSubContext.Response
del sistema 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 è un'associazione WebPubSubContext
di input fornisce un metodo HttpTrigger
di deserializzazione di richieste simile rispetto a WebPubSubTrigger
, esistono 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 dell'evento, è necessario restituire un HttpResponseMessage
oggetto 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 Connessione autenticati a un utente specifico
- Connessione client 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 connectionId specifici 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));
}
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 WebPubSubAction
statici per individuare le azioni disponibili. Ad esempio, l'utente può creare l'oggetto SendToAllAction
chiamando WebPubSubAction.CreateSendToAllAction()
.
Classe derivata | Proprietà |
---|---|
SendToAllAction |
Data, DataType, Excluded |
SendToGroupAction |
Group, Data, DataType, Excluded |
SendToUserAction |
UserId, Data, DataType |
SendToConnectionAction |
Connessione ionId, Data, DataType |
AddUserToGroupAction |
UserId, Group |
RemoveUserFromGroupAction |
UserId, Group |
RemoveUserFromAllGroupsAction |
ID utente |
AddConnectionToGroupAction |
Connessione ionId, Gruppo |
RemoveConnectionFromGroupAction |
Connessione ionId, Gruppo |
CloseAllConnectionsAction |
Escluso, Motivo |
CloseClientConnectionAction |
Connessione ionId, Reason |
CloseGroupConnectionsAction |
Gruppo, Escluso, Motivo |
GrantPermissionAction |
Connessione ionId, Permission, TargetName |
RevokePermissionAction |
Connessione ionId, Permission, TargetName |
Impostazione
WebPubSub
La tabella seguente illustra 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 l'stringa di connessione del servizio Web PubSub (il valore predefinito è "WebPubSub Connessione ionString"). |
Risoluzione dei problemi
Configurazione della registrazione della console
È anche possibile abilitare facilmente la registrazione della console se si vuole approfondire le richieste eseguite sul servizio.
Passaggi successivi
Usare queste risorse per iniziare a creare un'applicazione personalizzata:
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per