Ligação de gatilho do Serviço SignalR para o Azure Functions

Use a associação de gatilho do SignalR para responder a mensagens enviadas do Serviço Azure SignalR. Quando a função é acionada, as mensagens passadas para a função são analisadas como um objeto json.

No modo sem servidor do Serviço SignalR, o Serviço SignalR usa o recurso Upstream para enviar mensagens do cliente para o Function App. E o Function App usa a ligação de gatilho do Serviço SignalR para lidar com essas mensagens. A arquitetura geral é mostrada abaixo:

Para obter informações sobre detalhes de instalação e configuração, consulte a visão geral.

Exemplo

Uma função C# pode ser criada usando um dos seguintes modos C#:

• Modelo de trabalho isolado: função C# compilada que é executada em um processo de trabalho isolado do tempo de execução. O processo de trabalho isolado é necessário para suportar funções C# em execução nas versões LTS e não-LTS .NET e .NET Framework.
• Modelo em processo: função C# compilada que é executada no mesmo processo que o tempo de execução do Functions.
• Script C#: usado principalmente quando você cria funções C# no portal do Azure.

Importante

O suporte para o modelo em processo terminará em 10 de novembro de 2026. É altamente recomendável que você migre seus aplicativos para o modelo de trabalho isolado para obter suporte total.

Modelo de trabalhador isolado

O exemplo a seguir mostra uma função C# que recebe um evento de mensagem de clientes e registra o conteúdo da mensagem.

[Function(nameof(OnClientMessage))]
public static void OnClientMessage(
    [SignalRTrigger("Hub", "messages", "sendMessage", "content", ConnectionStringSetting = "SignalRConnection")]
        SignalRInvocationContext invocationContext, string content, FunctionContext functionContext)
{
    var logger = functionContext.GetLogger(nameof(OnClientMessage));
    logger.LogInformation("Connection {connectionId} sent a message. Message content: {content}", invocationContext.ConnectionId, content);
}

Importante

Modelo baseado em classe de ligações de serviço SignalR em C# trabalhador isolado não otimiza como você escreve gatilhos SignalR devido à limitação do modelo de trabalho C#. Para obter mais informações sobre o modelo baseado em classe, consulte Modelo baseado em classe.

Modelo em processo

A ligação de gatilho do Serviço SignalR para o modelo em processo C# tem dois modelos de programação. Modelo baseado em classe e modelo tradicional. O modelo baseado em classe fornece uma experiência consistente de programação do lado do servidor SignalR. O modelo tradicional oferece mais flexibilidade e é semelhante a outras ligações de funções.

Com modelo baseado em classe

Consulte Modelo baseado em classe para obter detalhes.

public class HubName1 : ServerlessHub
{
    [FunctionName("SignalRTest")]
    public Task SendMessage([SignalRTrigger]InvocationContext invocationContext, string message, ILogger logger)
    {
        logger.LogInformation($"Receive {message} from {invocationContext.ConnectionId}.");
    }
}

Com um modelo tradicional

O modelo tradicional obedece à convenção do Azure Function desenvolvido pelo C#. Se você não estiver familiarizado com ele, você pode aprender com documentos.

[FunctionName("SignalRTest")]
public static Task Run([SignalRTrigger("SignalRTest", "messages", "SendMessage", parameterNames: new string[] {"message"})]InvocationContext invocationContext, string message, ILogger logger)
{
    logger.LogInformation($"Receive {message} from {invocationContext.ConnectionId}.");
}

Como pode ser difícil de usar ParameterNames no gatilho, o exemplo a seguir mostra como usar o SignalRParameter atributo para definir o message atributo.

[FunctionName("SignalRTest")]
public static Task Run([SignalRTrigger("SignalRTest", "messages", "SendMessage")]InvocationContext invocationContext, [SignalRParameter]string message, ILogger logger)
{
    logger.LogInformation($"Receive {message} from {invocationContext.ConnectionId}.");
}

O gatilho SignalR não é suportado atualmente para Java.

Aqui estão os dados de vinculação no arquivo function.json :

{
    "type": "signalRTrigger",
    "name": "invocation",
    "hubName": "hubName1",
    "category": "messages",
    "event": "SendMessage",
    "parameterNames": [
        "message"
    ],
    "direction": "in"
}

Modelo v4

app.generic("function1",
    {
        trigger: { "type": "signalRTrigger", "name": "invocation", "direction": "in", "hubName": "hubName1", "event": "SendMessage", "category": "messages" },
        handler: (triggerInput, context) => {
            context.log(`Receive ${context.Arguments[0]} from ${triggerInput.ConnectionId}.`)
        }
    })

Modelo v3

Aqui estão os dados de vinculação no arquivo function.json :

{
    "type": "signalRTrigger",
    "name": "invocation",
    "hubName": "hubName1",
    "category": "messages",
    "event": "SendMessage",
    "parameterNames": [
        "message"
    ],
    "direction": "in"
}

Aqui está o código JavaScript:

module.exports = function (context, invocation) {
    context.log(`Receive ${context.bindingData.message} from ${invocation.ConnectionId}.`)
};

Exemplos completos do PowerShell estão pendentes.

Aqui está o código Python:

import logging
import json
import azure.functions as func

def main(invocation) -> None:
    invocation_json = json.loads(invocation)
    logging.info("Receive {0} from {1}".format(invocation_json['Arguments'][0], invocation_json['ConnectionId']))

Atributos

As bibliotecas C# de processo de trabalho em processo e isoladas usam o SignalRTrigger atributo para definir a função. Em vez disso, o script C# usa um arquivo de configuração function.json.

Modelo de trabalhador isolado

A tabela a seguir explica as propriedades do SignalRTrigger atributo.

Propriedade Attribute	Description
Nome do Hub;	Esse valor deve ser definido como o nome do hub SignalR para que a função seja acionada.
Categoria	Esse valor deve ser definido como a categoria de mensagens para a função a ser acionada. A categoria pode ser um dos seguintes valores: conexões: incluindo eventos conectados e desconectados mensagens: incluindo todos os outros eventos, exceto aqueles na categoria de conexões
Evento	Esse valor deve ser definido como o evento de mensagens para que a função seja acionada. Para a categoria de mensagens , evento é o destino na mensagem de invocação que os clientes enviam. Para a categoria conexões , apenas conectado e desconectado é usado.
Nomes de parâmetros	(Opcional) Uma lista de nomes que se liga aos parâmetros.
ConnectionStringSetting	O nome da configuração do aplicativo ou da coleção de configurações que contém a cadeia de conexão do Serviço SignalR, cujo padrão é AzureSignalRConnectionString.

Modelo em processo

A tabela a seguir explica as propriedades do SignalRTrigger atributo.

Propriedade Attribute	Description
Nome do Hub;	Esse valor deve ser definido como o nome do hub SignalR para que a função seja acionada.
Categoria	Esse valor deve ser definido como a categoria de mensagens para a função a ser acionada. A categoria pode ser um dos seguintes valores: conexões: incluindo eventos conectados e desconectados mensagens: incluindo todos os outros eventos, exceto aqueles na categoria de conexões
Evento	Esse valor deve ser definido como o evento de mensagens para que a função seja acionada. Para a categoria de mensagens , evento é o destino na mensagem de invocação que os clientes enviam. Para a categoria conexões , apenas conectado e desconectado é usado.
Nomes de parâmetros	(Opcional) Uma lista de nomes que se liga aos parâmetros.
ConnectionStringSetting	O nome da configuração do aplicativo ou da coleção de configurações que contém a cadeia de conexão do Serviço SignalR, cujo padrão é AzureSignalRConnectionString.

Anotações

Atualmente, não há uma anotação Java suportada para um gatilho SignalR.

Configuração

A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json .

function.json propriedade	Description
type	Deve ser definido como SignalRTrigger.
direção	Deve ser definido como in.
Designação	Nome da variável usada no código da função para o objeto de contexto de invocação de gatilho.
Nome do hub	Esse valor deve ser definido como o nome do hub SignalR para que a função seja acionada.
category	Esse valor deve ser definido como a categoria de mensagens para a função a ser acionada. A categoria pode ser um dos seguintes valores: conexões: incluindo eventos conectados e desconectados mensagens: incluindo todos os outros eventos, exceto aqueles na categoria de conexões
evento	Esse valor deve ser definido como o evento de mensagens para que a função seja acionada. Para a categoria de mensagens , evento é o destino na mensagem de invocação que os clientes enviam. Para a categoria conexões , apenas conectado e desconectado é usado.
nomes_parâmetros;	(Opcional) Uma lista de nomes que se liga aos parâmetros.
connectionStringSetting	O nome da configuração do aplicativo ou da coleção de configurações que contém a cadeia de conexão do Serviço SignalR, cujo padrão é AzureSignalRConnectionString.

Consulte a seção Exemplo para obter exemplos completos.

Utilização

Conexões gerenciadas baseadas em identidade

Para uma segurança ideal, seu aplicativo de função deve usar identidades gerenciadas ao se conectar ao serviço Azure SignalR em vez de usar uma cadeia de conexão, que contém uma chave de segredo compartilhado. Para obter mais informações, consulte Autorizar solicitações para recursos do Serviço Azure SignalR com identidades gerenciadas do Microsoft Entra.

Cargas úteis

O tipo de entrada de gatilho é declarado como um ou InvocationContext um tipo personalizado. Se você escolher InvocationContext, você terá acesso total ao conteúdo da solicitação. Para um tipo personalizado, o tempo de execução tenta analisar o corpo da solicitação JSON para definir as propriedades do objeto.

InvocaçãoContexto

InvocationContext contém todo o conteúdo da mensagem enviada de um serviço SignalR, que inclui as seguintes propriedades:

Property	Description
Argumentos	Disponível para a categoria de mensagens . Contém argumentos na mensagem de invocação
Erro	Disponível para evento desconectado . Ele pode estar vazio se a conexão foi fechada sem erro ou se contiver as mensagens de erro.
Hub	O nome do hub ao qual a mensagem pertence.
Categoria	A categoria da mensagem.
Evento	O evento da mensagem.
ConnectionId	O ID de conexão do cliente que envia a mensagem.
UserId	A identidade do usuário do cliente que envia a mensagem.
Cabeçalhos	Os cabeçalhos da solicitação.
Query	A consulta da solicitação quando os clientes se conectam ao serviço.
Pedidos	As reivindicações do cliente.

Ao utilizar ParameterNames

A propriedade ParameterNames in SignalRTrigger permite vincular argumentos de mensagens de invocação aos parâmetros de funções. Você pode usar o nome definido como parte de expressões de associação em outras associações ou como parâmetros em seu código. Isso lhe dá uma maneira mais conveniente de acessar argumentos de InvocationContext.

Digamos que você tenha um cliente JavaScript SignalR tentando invocar o método broadcast no Azure Function com dois argumentos message1, message2.

await connection.invoke("broadcast", message1, message2);

Depois de definir parameterNames, os nomes definidos correspondem aos argumentos enviados no lado do cliente.

[SignalRTrigger(parameterNames: new string[] {"arg1, arg2"})]

Em seguida, o arg1 contém o conteúdo de message1, e arg2 contém o conteúdo de message2.

ParameterNames Considerações

Para a vinculação de parâmetros, a ordem é importante. Se você estiver usando ParameterNames, a ordem em ParameterNames corresponde à ordem dos argumentos que você invoca no cliente. Se você estiver usando o atributo [SignalRParameter] em C#, a ordem dos argumentos nos métodos da Função do Azure corresponderá à ordem dos argumentos nos clientes.

ParameterNames e atributo [SignalRParameter]não pode ser usado ao mesmo tempo, ou você terá uma exceção.

Integração com o serviço SignalR

O Serviço SignalR precisa de uma URL para acessar o Aplicativo de Função quando você estiver usando a vinculação de gatilho do Serviço SignalR. O URL deve ser configurado em Configurações Upstream no lado do Serviço SignalR.

Ao usar o gatilho do Serviço SignalR, a URL pode ser simples e formatada da seguinte maneira:

<Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>

O Function_App_URL pode ser encontrado na página Visão Geral do Function App e o API_KEY é gerado pelo Azure Function. Você pode obter o API_KEY de na folha Teclas do signalr_extension aplicativo do aplicativo de função.

Se você quiser usar mais de um aplicativo de função junto com um serviço SignalR, o upstream também pode oferecer suporte a regras de roteamento complexas. Encontre mais detalhes em Configurações Upstream.

Amostra passo a passo

Você pode seguir o exemplo no GitHub para implantar uma sala de chat no Function App com vinculação de gatilho do Serviço SignalR e recurso upstream: Exemplo de sala de chat bidirecional

Próximos passos

• Desenvolvimento das Funções do Azure e configuração com o Azure SignalR Service
• Exemplo de vinculação de gatilho de serviço SignalR
• Exemplo de vinculação de gatilho de serviço SignalR em processo de trabalho isolado