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:

Arquitetura de gatilho SignalR

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.

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.

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"
}
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}.`)
        }
    })

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.

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

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.

Upstream Portal

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. Chave de API

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