Configurer le gestionnaire d’événements dans le service Azure Web PubSub

Article
09/19/2024

Le gestionnaire d’événements gère les événements clients entrants. Les gestionnaires d’événements sont inscrits et configurés dans le service via le portail Azure ou Azure CLI. Lorsqu’un événement client est déclenché, le service peut envoyer l’événement au gestionnaire d’événements approprié. Le service Web PubSub prend désormais en charge le gestionnaire d’événements côté serveur, qui expose le point de terminaison accessible publiquement pour que le service puisse l’appeler lorsque l’événement est déclenché. En d’autres termes, il agit comme un webhook.

Le service Web PubSub fournit des événements clients au webhook configuré en amont à l’aide du protocole HTTP CloudEvents, avec l’extension CloudEvents pour le gestionnaire d’événements Azure Web PubSub.

Capture d’écran du déclencheur d’événements du service Web PubSub.

Paramètres du gestionnaire d'événements

Un client se connecte toujours à un hub et vous pouvez configurer plusieurs paramètres de gestionnaire d’événements pour le hub. L’ordre des paramètres du gestionnaire d’événements est important et l’ancien a la priorité la plus élevée. Lorsqu’un client se connecte et qu’un événement est déclenché, Web PubSub passe par les gestionnaires d’événements configurés dans l’ordre de priorité et la première correspondance gagne. Définissez les propriétés suivantes lorsque vous configurez le gestionnaire d’événements :

Nom de la propriété	Description
Modèle d’URL	Définit le modèle que Web PubSub utilise pour évaluer votre URL de webhook en amont.
Événements liés aux utilisateurs	Définit les événements utilisateur auxquels le paramètre de gestionnaire d’événements actuel s’intéresse.
Événements système	Définit les événements système auxquels le paramètre de gestionnaire d’événements actuel s’intéresse.
Authentification	Définit la méthode d’authentification entre le service Web PubSub et votre serveur en amont.

Événements

Les événements incluent les événements utilisateur et les événements système. Les événements système sont des événements prédéfinis qui sont déclenchés pendant la durée de vie d’un client. Les événements utilisateur sont déclenchés lorsque le client envoie des données. Le nom de l’événement utilisateur peut être personnalisé à l’aide de protocoles clients. Voici une explication détaillée.

Type d’événement	Valeurs prises en charge
Événements système	`connect`, `connected` et `disconnected`
Événements liés aux utilisateurs	`message`, ou nom d’événement personnalisé suivant les protocoles clients

URL template

Le modèle d’URL prend en charge plusieurs paramètres qui peuvent être évalués pendant l’exécution. Avec cette fonctionnalité, il est facile d’acheminer différents hubs ou événements vers différents serveurs en amont avec un seul paramètre. La syntaxe de référence KeyVault est également prise en charge afin que les données puissent être stockées en toute sécurité dans Azure Key Vault.

Notez que le nom de domaine d’URL ne doit pas contenir de syntaxe de paramètre, par exemple, http://{hub}.com n’est pas un modèle d’URL valide.

Paramètres pris en charge	Syntaxe	Description	Exemples
Paramètre hub	`{hub}`	La valeur est le hub auquel le client se connecte.	Lorsqu’un client se connecte à `client/hubs/chat`, un modèle d’URL `http://host.com/api/{hub}` prend la valeur `http://host.com/api/chat`, car pour ce client, le hub est `chat`.
Paramètre d’événement	`{event}`	Valeur de l’événement déclenché. Les valeurs `event` sont répertoriées ici. La valeur de l’événement pour les demandes de protection contre les abus est `validate`, comme expliqué ici.	S’il existe un modèle d’URL `http://host.com/api/{hub}/{event}` configuré pour l’événement `connect`, lorsqu’un client se connecte à `client/hubs/chat`, Web PubSub lance une requête POST vers l’URL évaluée `http://host.com/api/chat/connect` lorsque le client se connecte, car pour cet événement client, hub est `chat` et l’événement déclenchant ce paramètre de gestionnaire d’événements est `connect`.
Paramètre de référence KeyVault	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	La chaîne SecretUri doit correspondre à l’URI complet du plan de données d’un secret dans le coffre, y compris éventuellement une version, par exemple `https://myvault.vault.azure.net/secrets/mysecret/` ou `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`. Lorsque vous utilisez la référence KeyVault, vous devez également configurer l’authentification entre votre service Web PubSub et votre service KeyVault, consultez ici pour obtenir des étapes détaillées.	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

Authentification entre le service et le webhook

Vous pouvez utiliser l’une de ces méthodes pour vous authentifier entre le service et le webhook.

Mode anonyme
Authentification simple avec ?code=<code> est fournie par l’URL de webhook configurée comme paramètre de requête.
Autorisation Microsoft Entra. Pour plus d’informations, consultez Utiliser une identité managée dansles événements clients.

Serveur en amont et validation

Lors de la configuration du webhook du gestionnaire d’événements via le portail Azure ou de l’interface CLI, le service suit la Protection contre les abus CloudEvents pour valider le webhook en amont. Ce mécanisme valide chaque URL de webhook inscrite en amont. L’en-tête de demande WebHook-Request-Origin est défini sur le nom de domaine de service xxx.webpubsub.azure.com et il s’attend à ce que la réponse ayant l’en-tête WebHook-Allowed-Origin contienne ce nom de domaine ou *.

Lors de la validation, le paramètre {event} est résolu en validate. Par exemple, en essayant de définir l’URL sur http://host.com/api/{event}, le service essaie de CHOISIR une requête sur http://host.com/api/validate. Et ce n’est que lorsque la réponse est valide que la configuration peut être définie correctement.

À l’heure actuelle, WebHook-Request-Rate et WebHook-Request-Callback ne sont pas pris en charge.

Configurer un gestionnaire d’événements

Configurer via Portail Azure

Vous pouvez ajouter un gestionnaire d’événements à un nouveau hub ou modifier un hub existant.

Pour configurer un gestionnaire d’événements dans un nouveau hub :

Accédez à votre page de service Azure Web PubSub dans le portail Azure.
Sélectionnez Paramètres dans le menu.
Sélectionnez Ajouter pour créer un hub et configurer votre URL de webhook côté serveur. Remarque : Pour ajouter un gestionnaire d’événements à un hub existant, sélectionnez le hub, puis Modifier.
Entrez le nom de votre hub.
Sélectionnez Ajouter sous Configurer des gestionnaires pairs.
Dans la page du gestionnaire d’événements, configurez les champs suivants : 1. Entrez l’URL du webhook du serveur dans le champ modèle d’URL. 1. Sélectionnez les événements système auxquels vous souhaitez vous abonner. 1. Sélectionnez les événements utilisateur auxquels vous souhaitez vous abonner. 1. Sélectionnez la méthode d’authentification pour authentifier les requêtes en amont. 1. Sélectionnez Confirmer.
Sélectionnez Enregistrer en haut de la page Configurer les paramètres du hub.

Configurer via Azure CLI

Utilisez les commandes de groupe az webpubsub hub d’Azure CLI pour configurer les paramètres du gestionnaire d’événements.

Commandes	Description
`create`	Crée les paramètres de hub pour le service WebPubSub.
`delete`	Supprime les paramètres de hub pour le service WebPubSub.
`list`	Répertorie tous les paramètres de hub pour le service WebPubSub.
`show`	Affiche les paramètres de hub pour le service WebPubSub.
`update`	Met à jour les paramètres de hub pour le service WebPubSub.

Voici un exemple de création de deux URL de webhook pour le hub MyHub de la ressource MyWebPubSub :

az webpubsub hub create -n "MyWebPubSub" -g "MyResourceGroup" --hub-name "MyHub" --event-handler url-template="http://host.com" user-event-pattern="*" --event-handler url-template="http://host2.com" system-event="connected" system-event="disconnected" auth-type="ManagedIdentity" auth-resource="uri://myUri"