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

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

No modo sem servidor do Serviço do SignalR, o Serviço do SignalR usa o recurso Upstream para enviar mensagens do cliente ao aplicativo de funções. Já o aplicativo de funções usa a associação de gatilho do Serviço do SignalR para lidar com essas mensagens. A arquitetura geral é exibida abaixo:

Arquitetura de gatilho do SignalR

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

Exemplo

A função C# pode ser criada por meio de um dos seguintes modos C#:

  • Modelo de trabalho isolado: função C# compilada executada em um processo de trabalho que está isolado do runtime. É necessário um processo de trabalho isolado para dar suporte às funções C# executadas nas versões LTS e não LTS do .NET e do .NET Framework.
  • Modelo em processo: função C# compilada no mesmo processo que o runtime do Functions.
  • Script C#: usado principalmente ao criar funções C# no portal do Azure.

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

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

Atualmente, não há suporte para o gatilho do SignalR para Java.

Aqui estão os dados de associaçã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# em processo e de processo de trabalho isolado usam o atributo SignalRTrigger 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 atributo SignalRTrigger.

Propriedade de atributo Descrição
HubName Esse valor deve ser definido como o nome do hub do SignalR para que a função seja acionada.
Categoria Esse valor deve ser definido como a categoria de mensagens para que a função seja acionada. A categoria pode ser um dos seguintes valores:
  • connections: que inclui eventos conectados e desconectados
  • messages: que inclui todos os outros eventos, exceto os da categoria connections
Evento Esse valor deve ser definido como o evento das mensagens para que a função seja acionada. Na categoria messages, o evento é o destino da mensagem de invocação que os clientes enviam. Na categoria connections, somente são usados os valores conectado e desconectado.
ParameterNames (Opcional) Uma lista de nomes que se associa aos parâmetros.
ConnectionStringSetting O nome da configuração do aplicativo que contém a cadeia de conexão do Serviço do SignalR (o padrão é AzureSignalRConnectionString).

Anotações

Atualmente, não há uma anotação Java compatível com um gatilho SignalR.

Configuração

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como SignalRTrigger.
direction Deve ser definido como in.
name Nome da variável usada no código da função para o objeto de contexto da invocação do gatilho.
hubName Esse valor deve ser definido como o nome do hub do SignalR para que a função seja acionada.
category Esse valor deve ser definido como a categoria de mensagens para que a função seja acionada. A categoria pode ser um dos seguintes valores:
  • connections: que inclui eventos conectados e desconectados
  • messages: que inclui todos os outros eventos, exceto os da categoria connections
event Esse valor deve ser definido como o evento das mensagens para que a função seja acionada. Na categoria messages, o evento é o destino da mensagem de invocação que os clientes enviam. Na categoria connections, somente são usados os valores conectado e desconectado.
parameterNames (Opcional) Uma lista de nomes que se associa aos parâmetros.
connectionStringSetting O nome da configuração do aplicativo que contém a cadeia de conexão do Serviço do SignalR (o padrão é AzureSignalRConnectionString).

Consulte a Seção de exemplo para obter exemplos completos.

Uso

Payloads

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

InvocationContext

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

Propriedade Descrição
Argumentos Disponível para a categoria messages. Contém argumentos na mensagem de invocação
Erro Disponível para o evento desconectado. Poderá ficar vazio se a conexão for fechada sem erros ou 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 A ID de conexão do cliente que envia a mensagem.
UserId Identidade de usuário do cliente que envia a mensagem.
Cabeçalhos Os cabeçalhos da solicitação.
Consulta A consulta da solicitação quando os clientes se conectam ao serviço.
Declarações As declarações do cliente.

Usando ParameterNames

A propriedade ParameterNames em SignalRTrigger permite que você associe argumentos das mensagens de invocação aos parâmetros das funções. É possível usar o nome que você definiu como parte das expressões de associação de outra associação ou como parâmetros no seu código. Isso oferece a você uma forma mais prática de acessar argumentos de InvocationContext.

Digamos que você tenha um cliente SignalR do JavaScript que está tentando invocar o método broadcast no Azure Functions com os dois argumentos message1 e message2.

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

Depois de definir parameterNames, o nome que você definiu corresponderá 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.

Considerações sobre ParameterNames

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

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

Integração ao Serviço do SignalR

O Serviço do SignalR precisa de uma URL para acessar o aplicativo de funções quando você está usando a associação de gatilho do Serviço do SignalR. É necessário configurar a URL em Configurações de upstream no lado do Serviço do SignalR.

Portal de upstream

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 Aplicativo de Funções e é API_KEY gerado pelo Azure Function. Você pode obter a API_KEY de signalr_extension na folha API_KEY do aplicativo de funções. Chave de API

Se você quiser usar mais de um aplicativo de funções junto com um Serviço do SignalR, o upstream também poderá dar suporte a regras de roteamento complexas. Encontre mais detalhes em Configurações de upstream.

Exemplo passo a passo

Você pode seguir a amostra do GitHub para implantar uma sala de chat no aplicativo de funções com o recurso de upstream e associação de gatilho do Serviço do SignalR: Amostra de sala de chat bidirecional

Próximas etapas