Partager via


Déclencheur et liaisons Azure Web PubSub pour Azure Functions

Cette référence explique comment gérer les événements Web PubSub dans Azure Functions.

Web PubSub est un service managé Azure qui aide les développeurs à créer facilement des applications web avec des fonctionnalités en temps réel et un modèle publication/abonnement.

Action Type
Exécuter une fonction lorsque les messages proviennent du service Liaison de déclencheur
Lier la demande à l’objet cible sous le déclencheur HTTP pour la négociation et les demandes en amont Liaison d’entrée
Appeler le service pour effectuer des actions Liaison de sortie

Code source | Package | Documentation de référence de l’API | Documentation du produit | Exemples

Ajouter à votre application Functions

Pour utiliser le déclencheur et les liaisons, vous devez référencer le package approprié. Le package NuGet est utilisé pour les bibliothèques de classes .NET, tandis que le bundle d’extensions est utilisé pour tous les autres types d’applications.

Langage Ajouter via... Notes
C# Installation du package NuGet, préversion
Script C#, JavaScript, Python, PowerShell Installer des extensions de manière explicite, Utiliser des packs d’extension Il est recommandé d’utiliser l’extension Azure Tools avec Visual Studio Code.
Script C# (en ligne uniquement dans le portail Azure) Ajout d’une liaison Pour mettre à jour des extensions de liaison existantes sans avoir à republier votre application de fonction, consultez Mettre à jour vos extensions.

Concepts clés

Diagramme montrant le workflow du service Azure Web PubSub fonctionnant avec les applications de fonction.

(1)-(2) liaison d’entrée WebPubSubConnection avec HttpTrigger pour générer une connexion cliente.

(3)-(4) liaison de déclencheur WebPubSubTrigger ou liaison d’entrée WebPubSubContext avec HttpTrigger pour gérer la requête de service.

(5)-(6) liaison de sortie WebPubSub pour demander au service d’effectuer une opération.

Liaison de déclencheur

Utilisez le déclencheur de fonction pour gérer les requêtes du service Azure Web PubSub.

WebPubSubTrigger est utilisé lorsque vous devez gérer des requêtes côté service. Le modèle de point de terminaison du déclencheur devrait ressembler à ceci et être défini du côté service Web PubSub (portail : paramètres -> gestionnaire d’événements -> modèle d’URL). Dans le modèle de point de terminaison, la partie requête code=<API_KEY> est OBLIGATOIRE lorsque vous utilisez Azure Function App pour des raisons de sécurité. La clé est accessible dans le portail Azure. Localisez votre ressource d’application de fonction et accédez à Fonctions ->Clés d’application- >Clés système- >webpubsub_extension après avoir déployé l’application de fonction sur Azure. Toutefois, cette clé n’est pas nécessaire lorsque vous utilisez des fonctions locales.

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

Capture d’écran des clés système d’obtention de la clé.

Exemple

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

La liaison WebPubSubTrigger prend également en charge la valeur renvoyée dans les scénarios de synchronisation, par exemple, l’événement utilisateur et Connect système, lorsque le serveur peut vérifier et refuser la requête du client ou envoyer directement les messages à l’appelant. L’événement Connect respecte ConnectEventResponse et EventErrorResponse, l’événement utilisateur respecte UserEventResponse et EventErrorResponse, et les types REST ne correspondant pas au scénario actuel sont ignorés. Et si EventErrorResponse est retourné, le service supprime la connexion client.

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

Attributs et annotations

Dans les bibliothèques de classes C#, utilisez l’attribut WebPubSubTrigger.

Voici un attribut WebPubSubTrigger dans une signature de méthode :

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

Vous trouverez un exemple complet sur la page Exemple C#.

Configuration

Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier function.json.

Propriété function.json Propriété d’attribut Description
type n/a Obligatoire : doit être défini sur webPubSubTrigger.
direction n/a Obligatoire : doit être défini sur in.
nom n/a Obligatoire : nom de variable utilisé dans le code de fonction pour le paramètre qui reçoit les données de l’événement.
hub Hub Obligatoire : la valeur doit être définie sur le nom du hub Web PubSub pour que la fonction soit déclenchée. Nous pouvons définir la valeur dans l’attribut comme une priorité plus élevée, ou elle peut être définie dans les paramètres de l'application comme une valeur globale.
eventType WebPubSubEventType Obligatoire : la valeur doit être définie comme le type d'événement des messages pour que la fonction soit déclenchée. La valeur doit être user ou system.
eventName EventName Obligatoire : la valeur doit être définie comme l’événement des messages pour que la fonction soit déclenchée.
Pour le type d’événement system, le nom d’événement doit être dans connect, connected, disconnected.
Pour les sous-protocoles définis par l’utilisateur, le nom d’événement est message.
Pour le sous-protocole json.webpubsub.azure.v1. pris en charge par le système, le nom d’événement est défini par l’utilisateur.
connexion Connection Facultatif : Nom d’un regroupement de paramètres d’application ou de paramètres qui spécifie le service Azure Web PubSub en amont. La valeur est utilisée pour la validation de la signature. Et la valeur est automatiquement résolue avec les paramètres d’application « WebPubSubConnectionString » par défaut. La valeur null signifie que la validation n’est pas nécessaire et qu’elle réussit toujours.

Utilisations

En C#, WebPubSubEventRequest est un paramètre de liaison reconnu par type, les paramètres REST sont liés par le nom du paramètre. Vérifiez le tableau ci-dessous répertoriant les paramètres et types disponibles.

Dans un langage faiblement typé comme JavaScript, name dans function.json est utilisé pour lier l’objet déclencheur en fonction de la table de mappage ci-dessous. Et respecte dataType dans function.json pour convertir le message en conséquence lorsque name est défini sur data comme l’objet de liaison pour l’entrée de déclenchement. Tous les paramètres peuvent être lus à partir de context.bindingData.<BindingName> et sont convertis JObject.

Nom de la liaison Type de liaison Description Propriétés
requête WebPubSubEventRequest Décrit la requête en amont La propriété diffère selon les différents types d’événements, notamment les classes dérivées ConnectEventRequest, ConnectedEventRequest, UserEventRequest et DisconnectedEventRequest
connectionContext WebPubSubConnectionContext Informations de requête courantes EventType, EventName, Hub, ConnectionId, UserId, Headers, Origin, Signature, States
données BinaryData,string,Stream,byte[] Demande les données de message au client dans l’événement message utilisateur -
dataType WebPubSubDataType Message de requête dataType, qui prend en charge binary, text, json -
réclamations IDictionary<string, string[]> Revendications de l’utilisateur dans la requête connect système -
query IDictionary<string, string[]> Requête de l’utilisateur dans la requête connect système -
sous-protocoles IList<string> Sous-protocoles disponibles dans la requête connect système -
clientCertificates IList<ClientCertificate> Une liste d’empreintes de certificat provenant des clients dans la requête connect système -
reason string Motif dans la requête disconnected système -

Important

Dans C#, plusieurs types de paramètre pris en charge DOIVENT être placés dans le premier, c’est-à-dire request ou data qui, à part le type BinaryData par défaut, permettent que la liaison de fonction soit correcte.

Réponse de retour

WebPubSubTrigger respecte la réponse renvoyée par le client pour les événements synchrones de connect et l’événement utilisateur. Seule la réponse correspondante est renvoyée au service ; sinon, elle est ignorée. En outre, l’objet renvoyée WebPubSubTrigger prend en charge les utilisateurs dans SetState() et ClearStates() pour gérer les métadonnées de la connexion. Et l’extension fusionne les résultats de la valeur renvoyée avec les résultats d’origine de la requête WebPubSubConnectionContext.States. La valeur dans la clé existante est remplacée et celle dans la nouvelle clé est ajoutée.

Type renvoyé Description Propriétés
ConnectEventResponse Réponse pour l’événement connect Groupes, Rôles, UserId, Sous-protocole
UserEventResponse Réponse pour l’événement utilisateur DataType, Data
EventErrorResponse Réponse d’erreur pour l’événement de synchronisation Code, ErrorMessage
*WebPubSubEventResponse Type de réponse de base des éléments pris en charge utilisés pour les cas de retour incertains -

Liaison d’entrée

Notre extension fournit deux liaisons d’entrée ciblant différents besoins.

  • WebPubSubConnection

    Pour qu’un client puisse se connecter au service Azure Web PubSub, il doit connaître l’URL du point de terminaison de service et avoir un jeton d’accès valide. La liaison d’entrée WebPubSubConnection génère les informations requises, le client n’a donc pas besoin de gérer cette génération de jeton lui-même. Étant donné que le jeton est limité dans le temps et peut être utilisé pour authentifier un utilisateur spécifique sur une connexion, ne le mettez pas en cache et ne le partagez pas entre plusieurs clients. Un déclencheur HTTP qui utilise cette liaison d’entrée peut être utilisé pour permettre aux clients de récupérer les informations de connexion.

  • WebPubSubContext

    Lors de l’utilisation de Static Web Apps, HttpTrigger est le seul déclencheur pris en charge et, sous le scénario Web PubSub, nous fournissons la liaison d’entrée WebPubSubContext qui aide les utilisateurs à désérialiser la requête HTTP en amont du côté service sous les protocoles Web PubSub. Les clients peuvent ainsi obtenir des résultats similaires en comparaison à WebPubSubTrigger pour une gestion facile dans les fonctions. Consultez les exemples ci-dessous. Lorsqu’il est utilisé avec HttpTrigger, le client doit configurer l’URL exposée par HttpTrigger dans le gestionnaire d’événements en conséquence.

Exemple : WebPubSubConnection

L’exemple suivant montre une fonction C# qui acquiert des informations de connexion Web PubSub à l’aide de la liaison d’entrée et les renvoie via HTTP. Dans l’exemple ci-dessous, l’élément UserId est transmis par la partie requête de la demande du client, comme ?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;
}

Jetons authentifiés

Si la fonction est déclenchée par un client authentifié, vous pouvez ajouter une revendication d’ID d’utilisateur au jeton généré. Vous pouvez facilement ajouter l’authentification à une application de fonction à l’aide de Authentification App Service.

L’authentification App Service définit les en-têtes HTTP nommés x-ms-client-principal-id et x-ms-client-principal-name qui contiennent l’identité principale du client et le nom de l’utilisateur authentifié, respectivement.

Vous pouvez définir la propriété UserId de la liaison sur la valeur de l’un des en-têtes à l’aide d’une expression de liaison : {headers.x-ms-client-principal-id} ou {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;
}

Remarque

Les types de paramètres limités à la liaison ne prennent pas en charge un moyen de transmettre la liste ni le tableau, la WebPubSubConnection n’est pas entièrement prise en charge avec tous les paramètres du Kit de développement logiciel (SDK) du serveur de paramètres, en particulier roles, et inclut également groups et expiresAfter. Dans le cas où le client doit ajouter des rôles ou retarder la génération du jeton d’accès dans la fonction, il est recommandé d’utiliser le Kit de développement logiciel (SDK) du serveur pour 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);
}

Exemple : WebPubSubContext

L’exemple suivant montre une fonction C# qui acquiert des informations de requête Web PubSub en amont à l’aide de la liaison d’entrée sous le type d’événement connect et les renvoie via 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;
}

Configuration

WebPubSubConnection

Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier function.json et l’attribut WebPubSubConnection.

Propriété function.json Propriété d’attribut Description
type n/a Il doit être défini sur webPubSubConnection
direction n/a Il doit être défini sur in
nom n/a Nom de variable utilisé dans le code de fonction pour l’objet de liaison de connexion d’entrée.
hub Hub Obligatoire : La valeur doit être définie sur le nom du hub Web PubSub pour que la fonction soit déclenchée. Nous pouvons définir la valeur dans l’attribut comme une priorité plus élevée, ou elle peut être définie dans les paramètres de l'application comme une valeur globale.
userId ID utilisateur Facultatif : la valeur de la revendication de l’identificateur d’utilisateur à définir dans le jeton de clé d’accès.
connexion Connection Obligatoire : Nom du paramètre d’application contenant la chaîne de connexion du service Web PubSub (« WebPubSubConnectionString » par défaut).

WebPubSubContext

Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier functions.json et l’attribut WebPubSubContext.

Propriété function.json Propriété d’attribut Description
type n/a Cette propriété doit être définie sur webPubSubContext.
direction n/a Cette propriété doit être définie sur in.
name n/a Nom de variable utilisé dans le code de fonction pour la requête Web PubSub d’entrée.
connexion Connection Facultatif : Nom d’un regroupement de paramètres d’application ou de paramètres qui spécifie le service Azure Web PubSub en amont. Cette valeur est utilisée pour la protection contre les abus et la validation de la signature. La valeur est automatiquement résolue avec « WebPubSubConnectionString » par défaut. La valeur null signifie que la validation n’est pas nécessaire et qu’elle réussit toujours.

Utilisation

WebPubSubConnection

WebPubSubConnection fournit les propriétés ci-dessous.

Nom de la liaison Type de liaison Description
BaseUri Uri URI de connexion du client Web PubSub.
Uri Uri URI absolu de la connexion Web PubSub, contenant AccessToken généré en fonction de la requête.
AccessToken string AccessToken généré en fonction des informations de service et d’UserId de la requête.

WebPubSubContext

WebPubSubContext fournit les propriétés ci-dessous.

Nom de la liaison Type de liaison Description Propriétés
requête WebPubSubEventRequest Requête du client, voir le tableau ci-dessous pour plus d’informations. WebPubSubConnectionContext de l’en-tête de demande et les autres propriétés désérialisées du corps de la demande décrivent la requête, par exemple Reason pour DisconnectedEventRequest.
response HttpResponseMessage L’extension crée une réponse essentiellement pour AbuseProtection et les cas d’erreur. -
errorMessage string Décrit les détails de l’erreur lors du traitement de la requête en amont. -
hasError bool Indicateur qui spécifie s’il s’agit d’une requête Web PubSub en amont valide. -
isPreflight bool Indicateur qui spécifie s’il s’agit d’une requête préliminaire de AbuseProtection. -

Pour WebPubSubEventRequest, elle est désérialisée en différentes classes qui fournissent différentes informations sur le scénario de requête. Pour PreflightRequest ou les cas non valides, l’utilisateur peut vérifier les indicateurs IsPreflight et HasError pour savoir. Il est conseillé de renvoyer la réponse générée par le système WebPubSubContext.Response directement, ou le client peut consigner des erreurs à la demande. Dans différents scénarios, le client peut lire les propriétés de la requête comme indiqué ci-dessous.

Classe dérivée Description Propriétés
PreflightRequest Utilisée dans AbuseProtection lorsque IsPreflight est true -
ConnectEventRequest Utilisée dans le type d’événement Connect système Revendications, Requête, Sous-protocoles, ClientCertificates
ConnectedEventRequest Utilisée dans le type d’événement Connected système -
UserEventRequest Utilisée dans le type d’événement utilisateur Data, DataType
DisconnectedEventRequest Utilisée dans le type d’événement Disconnected système Motif

Remarque

Bien que WebPubSubContext soit une liaison d’entrée qui fournit une méthode de désérialisation des requêtes similaire à celle de HttpTrigger par rapport à WebPubSubTrigger, il existe des limites, c’est-à-dire que l’état de connexion après fusion n’est pas pris en charge. La réponse de retour est toujours respectée par le service, mais les utilisateurs doivent construire la réponse eux-mêmes. Si les utilisateurs ont besoin de définir la réponse à l’événement, vous devriez renvoyer un HttpResponseMessage contenant ConnectEventResponse ou des messages pour l’événement utilisateur en tant que corps de la réponse et placer l’état de connexion avec la clé ce-connectionstate dans l’en-tête de réponse.

Liaison de sortie

Utilisez la liaison de sortie Web PubSub pour appeler le service Azure Web PubSub afin d’effectuer une opération. Vous pouvez diffuser un message aux clients suivants :

  • Tous les clients connectés
  • Clients connectés authentifiés auprès d’un utilisateur spécifique
  • Clients connectés joints dans un groupe spécifique
  • Une connexion client spécifique

La liaison de sortie vous permet également de gérer les clients et les groupes, ainsi que d’accorder ou de révoquer des autorisations ciblant une connectionId spécifique avec un groupe.

  • Ajouter une connexion au groupe
  • Ajouter un utilisateur à un groupe
  • Supprimer une connexion d’un groupe
  • Supprimer un utilisateur d’un groupe
  • Supprimer un utilisateur de tous les groupes
  • Fermer toutes les connexions clientes
  • Fermer une connexion cliente spécifique
  • Fermer les connexions d’un groupe
  • Accorder l’autorisation d’une connexion
  • Révoquer l’autorisation d’une connexion

Pour plus d’informations sur les détails d’installation et de configuration, consultez la vue d’ensemble.

Exemple

[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 est le type abstrait de base des liaisons de sortie. Les types dérivés représentent le serveur d’action qui doit être appelé par les services.

En langage C#, nous fournissons quelques méthodes statiques sous WebPubSubAction pour vous aider à découvrir les actions disponibles. Par exemple, l’utilisateur peut créer l’action SendToAllAction en appelant WebPubSubAction.CreateSendToAllAction().

Classe dérivée Propriétés
SendToAllAction Data, DataType, Excluded
SendToGroupAction Group, Data, DataType, Excluded
SendToUserAction UserId, Data, DataType
SendToConnectionAction ConnectionId, Data, DataType
AddUserToGroupAction UserId, Group
RemoveUserFromGroupAction UserId, Group
RemoveUserFromAllGroupsAction ID utilisateur
AddConnectionToGroupAction ConnectionId, Group
RemoveConnectionFromGroupAction ConnectionId, Group
CloseAllConnectionsAction Excluded, Reason
CloseClientConnectionAction ConnectionId, Reason
CloseGroupConnectionsAction Group, Excluded, Reason
GrantPermissionAction ConnectionId, Permission, TargetName
RevokePermissionAction ConnectionId, Permission, TargetName

Configuration

WebPubSub

Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier function.json et l’attribut WebPubSub.

Propriété function.json Propriété d’attribut Description
type n/a Il doit être défini sur webPubSub
direction n/a Il doit être défini sur out
nom n/a Nom de variable utilisé dans le code de fonction pour l’objet liaison de sortie.
hub Hub La valeur doit être définie sur le nom du hub Web PubSub pour que la fonction soit déclenchée. Nous pouvons définir la valeur dans l’attribut comme une priorité plus élevée, ou elle peut être définie dans les paramètres de l'application comme une valeur globale.
connexion Connection Nom du paramètre d’application contenant la chaîne de connexion du service Web PubSub (« WebPubSubConnectionString » par défaut).

Dépannage

Configuration de la journalisation de la console

Vous pouvez également activer la journalisation de la console facilement si vous souhaitez approfondir les requêtes que vous formulez sur le service.

Étapes suivantes

Utilisez ces ressources pour commencer à créer votre propre application :