Déclencheur et liaisons Azure Web PubSub pour Azure Functions

Article
01/12/2024

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

Diagram showing the workflow of Azure Web PubSub service working with Function Apps.

(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>

Screenshot of get function system keys.

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. Connect les respects ConnectEventResponse des événements et EventErrorResponse, et les événements utilisateur respectent UserEventResponse et EventErrorResponse, les types rest qui ne correspondent pas au scénario actuel sont ignorés. EventErrorResponse Si elle est retournée, le service supprime la connexion du client.

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

L’exemple suivant montre une fonction JavaScript du déclencheur 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);
    }
});

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 le message au client de la requête. Dans le langage javaScript faiblement typé, il est désérialisé concernant les clés d’objet. Et EventErrorResponse a la priorité la plus élevée comparée aux objets rest, que si code elle est dans le retour, elle est analysée et EventErrorResponse la connexion cliente est supprimée.

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

Définissez la liaison de déclencheur dans function.json.

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

Définissez la fonction dans 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);
}

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 le message au client de la requête. Dans le langage javaScript faiblement typé, il est désérialisé concernant les clés d’objet. Et EventErrorResponse a la priorité la plus élevée comparée aux objets rest, que si code elle est dans le retour, elle est analysée et EventErrorResponse la connexion cliente est supprimée.

module.exports = async function (context) {
  return { 
    "data": "ack",
    "dataType" : "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`.
name	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	Connexion	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 signature. Et la valeur est résolue automatiquement avec les paramètres d’application « WebPubSub Connecter ionString » par défaut. Cela `null` signifie que la validation n’est pas nécessaire et 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 il function.json est utilisé pour lier l’objet déclencheur concernant la table de mappage ci-dessous. Respectez-vous dataType pour function.json convertir le message en conséquence lorsqu’il name est défini data comme objet de liaison pour l’entrée du déclencheur. Tous les paramètres peuvent être lus context.bindingData.<BindingName> et JObject convertis.

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
data	`BinaryData`,`string`,`Stream`,`byte[]`	Demande les données de message au client dans l’événement `message` utilisateur	-
dataType	`WebPubSubDataType`	Request message dataType, qui prend en charge `binary`, , `textjson`	-
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

En C#, plusieurs types pris en chargedoivent être placés dans le premier, c’est-à-dire requestdata que d’autres types que le type par défaut BinaryData pour rendre la liaison de fonction correctement.

Réponse de retour

WebPubSubTrigger respecte la réponse retournée par le client pour les événements synchrones et connect les événements 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 de retour avec les résultats de la requête WebPubSubConnectionContext.Statesd’origine. La valeur de la clé existante est écrasée et la valeur 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;
}

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

Définissez des liaisons d’entrée dans 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"
    }
  ]
}

Définissez la fonction dans index.js.

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

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

Limité aux types de paramètres de liaison ne prennent pas en charge un moyen de transmettre la liste ni le tableau, il WebPubSubConnection n’est pas entièrement pris en charge avec tous les paramètres du KIT de développement logiciel (SDK) du serveur de paramètres, en particulier roles, et inclut groups également 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) 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);
}

Remarque

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

Remarque

Définissez des liaisons d’entrée dans function.json.

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

Définissez la fonction dans 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();
};

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

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

Définissez des liaisons d’entrée dans 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"
    }
  ]
}

Définissez la fonction dans 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} };
};

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`
name	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	UserId	Facultatif : la valeur de la revendication de l’identificateur d’utilisateur à définir dans le jeton de clé d’accès.
connexion	Connexion	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	Connexion	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 d’abus de protection et de signature. La valeur est résolue automatiquement avec « WebPubSub Connecter ionString » par défaut. Cela `null` signifie que la validation n’est pas nécessaire et 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.

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

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

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

Nom de la liaison	Description
baseUrl	URI de connexion du client Web PubSub.
url	URI absolu de la connexion Web PubSub, contenant `AccessToken` généré en fonction de la requête.
accessToken	`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 côté du service, mais les utilisateurs doivent créer 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));
}

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

Définissez des liaisons dans functions.json.

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

Définissez la fonction dans index.js.

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

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`	UserId
`AddConnectionToGroupAction`	ConnectionId, Group
`RemoveConnectionFromGroupAction`	ConnectionId, Group
`CloseAllConnectionsAction`	Excluded, Reason
`CloseClientConnectionAction`	ConnectionId, Reason
`CloseGroupConnectionsAction`	Group, Excluded, Reason
`GrantPermissionAction`	ConnectionId, Permission, TargetName
`RevokePermissionAction`	ConnectionId, Permission, TargetName

Dans un langage faiblement typé comme javascript, actionName est le paramètre clé pour résoudre le type ; les actions disponibles sont répertoriées comme ci-dessous.

ActionName	Propriétés
`sendToAll`	Data, DataType, Excluded
`sendToGroup`	Group, Data, DataType, Excluded
`sendToUser`	UserId, Data, DataType
`sendToConnection`	ConnectionId, Data, DataType
`addUserToGroup`	UserId, Group
`removeUserFromGroup`	UserId, Group
`removeUserFromAllGroups`	UserId
`addConnectionToGroup`	ConnectionId, Group
`removeConnectionFromGroup`	ConnectionId, Group
`closeAllConnections`	Excluded, Reason
`closeClientConnection`	ConnectionId, Reason
`closeGroupConnections`	Group, Excluded, Reason
`grantPermission`	ConnectionId, Permission, TargetName
`revokePermission`	ConnectionId, Permission, TargetName

Important

La propriété des données du message dans les actions liées à l’envoi de messages doit être string si le type de données est défini sur json ou text afin d’éviter toute ambiguïté dans la conversion des données. Utilisez JSON.stringify() pour convertir l’objet JSON le cas échéant. Cela s’applique à n’importe quel emplacement à l’aide de la propriété de message, par exemple, UserEventResponse.Data fonctionnant avec WebPubSubTrigger.

Quand le type de données est défini sur binary, il est permis d’exploiter la liaison naturellement prise en charge par dataType en tant que binary, configurée dans le fichier function.json. Consultez Définitions de liaisons et de déclencheurs pour plus d’informations.

Dans un langage faiblement typé comme javascript, actionName est le paramètre clé pour résoudre le type ; les actions disponibles sont répertoriées comme ci-dessous.

ActionName	Propriétés
`sendToAll`	Data, DataType, Excluded
`sendToGroup`	Group, Data, DataType, Excluded
`sendToUser`	UserId, Data, DataType
`sendToConnection`	ConnectionId, Data, DataType
`addUserToGroup`	UserId, Group
`removeUserFromGroup`	UserId, Group
`removeUserFromAllGroups`	UserId
`addConnectionToGroup`	ConnectionId, Group
`removeConnectionFromGroup`	ConnectionId, Group
`closeAllConnections`	Excluded, Reason
`closeClientConnection`	ConnectionId, Reason
`closeGroupConnections`	Group, Excluded, Reason
`grantPermission`	ConnectionId, Permission, TargetName
`revokePermission`	ConnectionId, Permission, TargetName

Important

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`
name	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	Connexion	Nom du paramètre d’application contenant la chaîne de connexion du service Web PubSub (« WebPubSubConnectionString » par défaut).