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.

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.

Concepts clés

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

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

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

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

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

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

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

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.

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.

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.

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

{
  "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"
    }
  ]
}

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

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

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

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

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

{
  "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"
    }
  ]
}

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.

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.

Utilisation

WebPubSubConnection

WebPubSubContext

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

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.

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

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

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.

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.

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 :