Liaisons de service SignalR pour Azure FunctionsSignalR Service bindings for Azure Functions

Cet article explique comment authentifier et envoyer des messages en temps réel aux clients connectés à Service SignalR Azure à l’aide de liaisons de service SignalR dans Azure Functions.This article explains how to authenticate and send real-time messages to clients connected to Azure SignalR Service by using SignalR Service bindings in Azure Functions. Azure Functions prend en charge des liaisons d’entrée et de sortie pour le service SignalR.Azure Functions supports input and output bindings for SignalR Service.

Il s’agit des informations de référence pour les développeurs Azure Functions.This is reference information for Azure Functions developers. Si vous ne connaissez pas bien Azure Functions, commencez par consulter les ressources suivantes :If you're new to Azure Functions, start with the following resources:

Packages – Functions 2.x et versions ultérieuresPackages - Functions 2.x and higher

Les liaisons de service SignalR sont fournies dans le package NuGet Microsoft.Azure.WebJobs.Extensions.SignalRService, version 1.*.The SignalR Service bindings are provided in the Microsoft.Azure.WebJobs.Extensions.SignalRService NuGet package, version 1.*. Le code source pour le package se trouve dans le référentiel GitHub azure-functions-signalrservice-extension.Source code for the package is in the azure-functions-signalrservice-extension GitHub repository.

Le tableau suivant indique comment ajouter la prise en charge de cette liaison dans chaque environnement de développement.The following table tells how to add support for this binding in each development environment.

Environnement de développementDevelopment environment Pour ajouter la prise en chargeTo add support
Développement local - Bibliothèque de classes C#Local development - C# class library Installer le package.Install the package
Développement local - Script C#, JavaScript, F#Local development - C# script, JavaScript, F# Enregistrer l’extensionRegister the extension
Développement sur le portailPortal development Enregistrer l’extensionRegister the extension

Pour apprendre comment mettre à jour les extensions de liaison existantes dans le portail sans avoir à republier votre projet d'application de fonction, voir Mettre à jour vos extensions.To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

Pour plus d’informations sur la configuration et l’utilisation de SignalR Service et Azure Functions ensemble, reportez-vous à Développement et configuration Azure Functions avec Azure SignalR Service.For details on how to configure and use SignalR Service and Azure Functions together, refer to Azure Functions development and configuration with Azure SignalR Service.

Bibliothèque d’annotations (Java uniquement)Annotations library (Java only)

Pour utiliser les annotations SignalR Service dans les fonctions Java, vous devez ajouter une dépendance à l’artefact azure-fonctions-java-bibliothèque-signalr (version 1.0 ou version ultérieure) à votre fichier pom.xml.To use the SignalR Service annotations in Java functions, you need to add a dependency to the azure-functions-java-library-signalr artifact (version 1.0 or higher) to your pom.xml.

<dependency>
    <groupId>com.microsoft.azure.functions</groupId>
    <artifactId>azure-functions-java-library-signalr</artifactId>
    <version>1.0.0</version>
</dependency>

EntréeInput

Avant qu’un client puisse se connecter au service SignalR Azure, il doit récupérer l’URL du point de terminaison du service et un jeton d’accès valide.Before a client can connect to Azure SignalR Service, it must retrieve the service endpoint URL and a valid access token. La liaison d’entrée SignalRConnectionInfo génère l’URL du point de terminaison du service SignalR et un jeton valide qui sont utilisés pour se connecter au service.The SignalRConnectionInfo input binding produces the SignalR Service endpoint URL and a valid token that are used to connect to the service. Le jeton étant limité dans le temps et pouvant être utilisé pour authentifier un utilisateur spécifique sur une connexion, vous ne devez pas mettre le jeton en cache ou le partager entre plusieurs clients.Because the token is time-limited and can be used to authenticate a specific user to a connection, you should not cache the token or share it between clients. Un déclencheur HTTP utilisant cette liaison peut être utilisé par les clients pour récupérer les informations de connexion.An HTTP trigger using this binding can be used by clients to retrieve the connection information.

Pour plus d’informations sur la façon dont cette liaison est utilisée pour créer une fonction « negotiate » qui peut être utilisée par un client SignalR, consultez l’article sur le développement et la configuration d’Azure Functions dans la documentation sur les concepts de SignalR Service.For more information on how this binding is used to create a "negotiate" function that can be consumed by a SignalR client SDK, see the Azure Functions development and configuration article in the SignalR Service concepts documentation.

L’exemple suivant montre une fonction C# qui acquiert des informations de connexion SignalR à l’aide de la liaison d’entrée et les renvoie via HTTP.The following example shows a C# function that acquires SignalR connection information using the input binding and returns it over HTTP.

[FunctionName("negotiate")]
public static SignalRConnectionInfo Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req,
    [SignalRConnectionInfo(HubName = "chat")]SignalRConnectionInfo connectionInfo)
{
    return connectionInfo;
}

Jetons authentifiésAuthenticated tokens

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é.If the function is triggered by an authenticated client, you can add a user ID claim to the generated token. Vous pouvez facilement ajouter l’authentification à une application de fonction à l’aide de Authentification App Service.You can easily add authentication to a function app using App Service Authentication.

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.App Service Authentication sets HTTP headers named x-ms-client-principal-id and x-ms-client-principal-name that contain the authenticated user's client principal ID and name, respectively.

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}.You can set the UserId property of the binding to the value from either header using a binding expression: {headers.x-ms-client-principal-id} or {headers.x-ms-client-principal-name}.

[FunctionName("negotiate")]
public static SignalRConnectionInfo Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req, 
    [SignalRConnectionInfo
        (HubName = "chat", UserId = "{headers.x-ms-client-principal-id}")]
        SignalRConnectionInfo connectionInfo)
{
    // connectionInfo contains an access key token with a name identifier claim set to the authenticated user
    return connectionInfo;
}

OutputOutput

Utilisez la liaison de sortie SignalR pour envoyer un ou plusieurs messages à l’aide du service SignalR Azure.Use the SignalR output binding to send one or more messages using Azure SignalR Service. Vous pouvez diffuser un message à tous les clients connectés, ou vous pouvez le diffuser uniquement aux clients connectés qui ont été authentifiés comme un utilisateur donné.You can broadcast a message to all connected clients, or you can broadcast it only to connected clients that have been authenticated to a given user.

Vous pouvez également l’utiliser pour gérer les groupes auxquels appartient un utilisateur.You can also use it to manage the groups that a user belongs to.

Diffuser à tous les clientsBroadcast to all clients

L’exemple suivant montre une fonction qui envoie un message à l’aide de la liaison de sortie à tous les clients connectés.The following example shows a function that sends a message using the output binding to all connected clients. La cible correspond au nom de la méthode à appeler sur chaque client.The target is the name of the method to be invoked on each client. Arguments est un tableau de zéro objet ou plus à transmettre à la méthode du client.Arguments is an array of zero or more objects to be passed to the client method.

[FunctionName("SendMessage")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]object message, 
    [SignalR(HubName = "chat")]IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage 
        {
            Target = "newMessage", 
            Arguments = new [] { message } 
        });
}

Envoyer à un utilisateurSend to a user

Vous ne pouvez envoyer un message qu’aux connexions qui ont été authentifiées comme un utilisateur en définissant l’ID d’utilisateur du message SignalR.You can send a message only to connections that have been authenticated to a user by setting the user ID in the SignalR message.

[FunctionName("SendMessage")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]object message, 
    [SignalR(HubName = "chat")]IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage 
        {
            // the message will only be sent to this user ID
            UserId = "userId1",
            Target = "newMessage",
            Arguments = new [] { message }
        });
}

Envoyer à un groupeSend to a group

Vous ne pouvez envoyer un message qu’aux connexions qui ont été ajoutées à un groupe en définissant le nom de groupe du message SignalR.You can send a message only to connections that have been added to a group by setting the group name in the SignalR message.

[FunctionName("SendMessage")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]object message,
    [SignalR(HubName = "chat")]IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage
        {
            // the message will be sent to the group with this name
            GroupName = "myGroup",
            Target = "newMessage",
            Arguments = new [] { message }
        });
}

Gestion des groupesGroup management

SignalR Service permet aux utilisateurs d’être ajoutés à des groupes.SignalR Service allows users to be added to groups. Des messages peuvent ensuite être envoyés au groupe.Messages can then be sent to a group. Vous pouvez utiliser la sortie de liaison SignalR pour gérer l’appartenance au groupe d’un utilisateur.You can use the SignalR output binding to manage a user's group membership.

Ajouter un utilisateur à un groupeAdd user to a group

L’exemple suivant ajoute un utilisateur à un groupe.The following example adds a user to a group.

[FunctionName("addToGroup")]
public static Task AddToGroup(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]HttpRequest req,
    ClaimsPrincipal claimsPrincipal,
    [SignalR(HubName = "chat")]
        IAsyncCollector<SignalRGroupAction> signalRGroupActions)
{
    var userIdClaim = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier);
    return signalRGroupActions.AddAsync(
        new SignalRGroupAction
        {
            UserId = userIdClaim.Value,
            GroupName = "myGroup",
            Action = GroupAction.Add
        });
}

Supprimer un utilisateur d’un groupeRemove user from a group

L’exemple suivant supprime un utilisateur d’un groupe.The following example removes a user from a group.

[FunctionName("removeFromGroup")]
public static Task RemoveFromGroup(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]HttpRequest req,
    ClaimsPrincipal claimsPrincipal,
    [SignalR(HubName = "chat")]
        IAsyncCollector<SignalRGroupAction> signalRGroupActions)
{
    var userIdClaim = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier);
    return signalRGroupActions.AddAsync(
        new SignalRGroupAction
        {
            UserId = userIdClaim.Value,
            GroupName = "myGroup",
            Action = GroupAction.Remove
        });
}

Notes

Pour obtenir la liaison correcte de ClaimsPrincipal, vous devez avoir configuré les paramètres d’authentification dans Azure Functions.In order to get the ClaimsPrincipal correctly bound, you must have configured the authentication settings in Azure Functions.

ConfigurationConfiguration

SignalRConnectionInfoSignalRConnectionInfo

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 SignalRConnectionInfo.The following table explains the binding configuration properties that you set in the function.json file and the SignalRConnectionInfo attribute.

Propriété function.jsonfunction.json property Propriété d’attributAttribute property DescriptionDescription
typetype Cette propriété doit être définie sur signalRConnectionInfo.Must be set to signalRConnectionInfo.
directiondirection Cette propriété doit être définie sur in.Must be set to in.
namename Nom de variable utilisé dans le code de fonction pour l’objet d’informations de connexion.Variable name used in function code for connection info object.
hubNamehubName HubNameHubName Cette valeur doit être définie sur le nom du hub SignalR pour lequel les informations de connexion sont générées.This value must be set to the name of the SignalR hub for which the connection information is generated.
userIduserId UserIdUserId Facultatif : valeur de la revendication d’identification d’utilisateur à définir dans le jeton de clé d’accès.Optional: The value of the user identifier claim to be set in the access key token.
connectionStringSettingconnectionStringSetting ConnectionStringSettingConnectionStringSetting Nom du paramètre d’application contenant la chaîne de connexion du service SignalR (« AzureSignalRConnectionString » par défaut)The name of the app setting that contains the SignalR Service connection string (defaults to "AzureSignalRConnectionString")

SignalRSignalR

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 SignalR.The following table explains the binding configuration properties that you set in the function.json file and the SignalR attribute.

Propriété function.jsonfunction.json property Propriété d’attributAttribute property DescriptionDescription
typetype Cette propriété doit être définie sur signalR.Must be set to signalR.
directiondirection Cette propriété doit être définie sur out.Must be set to out.
namename Nom de variable utilisé dans le code de fonction pour l’objet d’informations de connexion.Variable name used in function code for connection info object.
hubNamehubName HubNameHubName Cette valeur doit être définie sur le nom du hub SignalR pour lequel les informations de connexion sont générées.This value must be set to the name of the SignalR hub for which the connection information is generated.
connectionStringSettingconnectionStringSetting ConnectionStringSettingConnectionStringSetting Nom du paramètre d’application contenant la chaîne de connexion du service SignalR (« AzureSignalRConnectionString » par défaut)The name of the app setting that contains the SignalR Service connection string (defaults to "AzureSignalRConnectionString")

Quand vous développez localement, les paramètres d’application vont dans le fichier local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Étapes suivantesNext steps