Associações do Serviço SignalR para o Azure FunctionsSignalR Service bindings for Azure Functions

Este artigo explica como autenticar e enviar mensagens em tempo real para clientes conectados ao Serviço do Azure SignalR usando associações do Serviço SignalR no 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. O Azure Functions dá suporte a associações de entrada e saída para o Serviço SignalR.Azure Functions supports input and output bindings for SignalR Service.

Essas são as informações de referência para desenvolvedores do Azure Functions.This is reference information for Azure Functions developers. Se for novo no Azure Functions, comece com os seguintes recursos:If you're new to Azure Functions, start with the following resources:

Pacotes-funções 2. x e superiorPackages - Functions 2.x and higher

As associações de serviço Signalr são fornecidas no pacote NuGet Microsoft. Azure. webjobs. Extensions. SignalRService , versão 1. *.The SignalR Service bindings are provided in the Microsoft.Azure.WebJobs.Extensions.SignalRService Nuget package, version 1.*. O código-fonte do pacote está no repositório GitHub azure-functions-signalrservice-extension.Source code for the package is in the azure-functions-signalrservice-extension GitHub repository.

A tabela a seguir informa como adicionar suporte para essa associação em cada ambiente de desenvolvimento.The following table tells how to add support for this binding in each development environment.

Ambiente de desenvolvimentoDevelopment environment Para adicionar suporteTo add support
Desenvolvimento local - biblioteca de classes do C#Local development - C# class library Instalar o pacoteInstall the package
Desenvolvimento local - Script do C#, JavaScript, F#Local development - C# script, JavaScript, F# Registrar a extensãoRegister the extension
Desenvolvimento de portalPortal development Registrar a extensãoRegister the extension

Para saber como atualizar as extensões de associação existentes no portal sem precisar republicar o projeto de aplicativo de funções, consulte Atualizar as extensões.To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

Para obter detalhes sobre como configurar e usar o serviço de sinalização e Azure Functions juntos, consulte Azure Functions desenvolvimento e configuração com o serviço de signaler do Azure.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.

Biblioteca de anotações (somente Java)Annotations library (Java only)

Para usar as anotações do serviço Signalr em funções Java, você precisa adicionar uma dependência ao artefato do Azure-Functions-Java-library-signalr (versão 1,0 ou superior) para o 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>

EntradaInput

Antes que um cliente possa se conectar ao serviço do Azure SignalR, ele deve recuperar a URL do ponto de extremidade de serviço e um token de acesso válido.Before a client can connect to Azure SignalR Service, it must retrieve the service endpoint URL and a valid access token. A associação de entrada SignalRConnectionInfo produz a URL do ponto de extremidade de Serviço SignalR e um token válido que são usados para se conectar ao serviço.The SignalRConnectionInfo input binding produces the SignalR Service endpoint URL and a valid token that are used to connect to the service. Como o token é limitada pelo tempo e pode ser usado para autenticar um usuário específico para uma conexão, você não deve armazenar em cache o token nem o compartilhar entre clientes.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. Um gatilho HTTP que use essa associação pode ser usado pelos clientes para recuperar as informações de conexão.An HTTP trigger using this binding can be used by clients to retrieve the connection information.

Para obter mais informações sobre como essa associação é usada para criar uma função "Negotiate" que pode ser consumida por um SDK de cliente do Signalr, consulte o artigo Azure Functions desenvolvimento e configuração na documentação conceitos do serviço signalr.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.

O exemplo a seguir mostra uma função C# que adquire as informações de conexão do SignalR usando a associação de entrada e retorna-a 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;
}

Tokens autenticadosAuthenticated tokens

Se a função for disparada por um cliente autenticado, você poderá adicionar uma declaração de ID de usuário ao token gerado.If the function is triggered by an authenticated client, you can add a user ID claim to the generated token. Você pode adicionar facilmente a autenticação a um aplicativo de funções usando a autenticação do serviço de aplicativo.You can easily add authentication to a function app using App Service Authentication.

Autenticação do Serviço de Aplicativo define os cabeçalhos HTTP denominados x-ms-client-principal-id e x-ms-client-principal-name que contêm a ID e o nome da entidade de segurança do cliente do usuário autenticado, respectivamente.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.

Você pode definir a propriedade UserId da associação como o valor do cabeçalho usando uma expressão de associação: {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;
}

SaídaOutput

Use a associação de saída do SignalR para enviar uma ou mais mensagens usando o Serviço Azure SignalR.Use the SignalR output binding to send one or more messages using Azure SignalR Service. Você pode difundir uma mensagem a todos os clientes conectados, ou pode difundi-la somente para clientes conectados que foram autenticados em um determinado usuário.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.

Você também pode usá-lo para gerenciar os grupos aos quais um usuário pertence.You can also use it to manage the groups that a user belongs to.

Difundir para todos os clientesBroadcast to all clients

O exemplo a seguir mostra uma função que envia uma mensagem usando a associação de saída para todos os clientes conectados.The following example shows a function that sends a message using the output binding to all connected clients. O destino é o nome do método a ser invocado em cada cliente.The target is the name of the method to be invoked on each client. Argumentos é uma matriz de zero ou mais objetos a serem passados para o método de cliente.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 } 
        });
}

Enviar para um usuárioSend to a user

Você pode enviar uma mensagem somente para conexões que foram autenticadas para um usuário, definindo a ID de usuário na mensagem do 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 }
        });
}

Enviar para um grupoSend to a group

Você pode enviar uma mensagem somente para conexões que foram adicionadas a um grupo definindo o nome do grupo na mensagem do 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 }
        });
}

Gerenciamento de gruposGroup management

O serviço signalr permite que os usuários sejam adicionados a grupos.SignalR Service allows users to be added to groups. As mensagens podem ser enviadas a um grupo.Messages can then be sent to a group. Você pode usar a associação de saída SignalR para gerenciar a associação de grupo de um usuário.You can use the SignalR output binding to manage a user's group membership.

Adicionar usuário a um grupoAdd user to a group

O exemplo a seguir adiciona um usuário a um grupo.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
        });
}

Remover usuário de um grupoRemove user from a group

O exemplo a seguir remove um usuário de um grupo.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
        });
}

Observação

Para obter o ClaimsPrincipal corretamente associado, você deve ter definido as configurações de autenticação no Azure Functions.In order to get the ClaimsPrincipal correctly bound, you must have configured the authentication settings in Azure Functions.

ConfiguraçãoConfiguration

SignalRConnectionInfoSignalRConnectionInfo

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json e no SignalRConnectionInfo atributo.The following table explains the binding configuration properties that you set in the function.json file and the SignalRConnectionInfo attribute.

Propriedade function.jsonfunction.json property Propriedade de atributoAttribute property DescriçãoDescription
tipotype Deve ser definido como signalRConnectionInfo.Must be set to signalRConnectionInfo.
directiondirection Deve ser definido como in.Must be set to in.
namename Nome da variável usada no código de função para o objeto de informações de conexão.Variable name used in function code for connection info object.
hubNamehubName HubNameHubName Esse valor deve ser definido como o nome do hub SignalR para o qual as informações de conexão são geradas.This value must be set to the name of the SignalR hub for which the connection information is generated.
userIduserId UserIdUserId Opcional: o valor da declaração do identificador de usuário a ser definida no token de chave de acesso.Optional: The value of the user identifier claim to be set in the access key token.
connectionStringSettingconnectionStringSetting ConnectionStringSettingConnectionStringSetting O nome da configuração do aplicativo que contém a cadeia de conexão do SignalR Service (o padrão é "AzureSignalRConnectionString")The name of the app setting that contains the SignalR Service connection string (defaults to "AzureSignalRConnectionString")

SignalRSignalR

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json e no SignalR atributo.The following table explains the binding configuration properties that you set in the function.json file and the SignalR attribute.

Propriedade function.jsonfunction.json property Propriedade de atributoAttribute property DescriçãoDescription
tipotype Deve ser definido como signalR.Must be set to signalR.
directiondirection Deve ser definido como out.Must be set to out.
namename Nome da variável usada no código de função para o objeto de informações de conexão.Variable name used in function code for connection info object.
hubNamehubName HubNameHubName Esse valor deve ser definido como o nome do hub SignalR para o qual as informações de conexão são geradas.This value must be set to the name of the SignalR hub for which the connection information is generated.
connectionStringSettingconnectionStringSetting ConnectionStringSettingConnectionStringSetting O nome da configuração do aplicativo que contém a cadeia de conexão do SignalR Service (o padrão é "AzureSignalRConnectionString")The name of the app setting that contains the SignalR Service connection string (defaults to "AzureSignalRConnectionString")

Quando você estiver desenvolvendo localmente, as configurações de aplicativo serão adicionadas ao arquivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Próximos passosNext steps