Gatilhos e vinculações do Azure Functions do Socket.IO (versão prévia)

Este artigo explica como usar a integração sem servidor do Socket.IO com o Azure Functions.

Ação	Tipo de associação
Obter o resultado da negociação do cliente, incluindo url e token de acesso	Associação de entrada
Disparado por mensagens do serviço	Associação de gatilho
Invocar o serviço para enviar mensagens ou gerenciar clientes	Associação de saída

Código-fonte | Pacote | Documentação de referência da API | Documentação do produto | Exemplos

Importante

As vinculações do Azure Functions só podem se integrar ao Web PubSub para Socket.IO no Modo Sem Servidor.

Autenticar e Cadeia de Conexão

Para permitir que a extensão funcione com o Web PubSub para Socket.IO, você precisa fornecer chaves de acesso ou uma configuração baseada em identidade para autenticação no serviço.

Acessar configuração baseada em chave

Nome da Configuração	Descrição
WebPubSubForSocketIOConnectionString	Obrigatória. Cadeia de conexão baseada em chave para o serviço

Você pode encontrar a cadeia de conexão na folha Chaves no Web PubSub para Socket.IO no portal do Azure.

Para o desenvolvimento local, use o arquivo local.settings.json para armazenar a cadeia de conexão. Configure WebPubSubForSocketIOConnectionString para a cadeia de conexão copiada da etapa anterior:

{
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    `WebPubSubForSocketIOConnectionString`: "Endpoint=https://<webpubsub-name>.webpubsub.azure.com;AccessKey=<access-key>;Version=1.0;"
  }
}

Após a implantação, use as configurações do aplicativo para configurar a cadeia de conexão.

Configuração baseada em identidade

Nome da Configuração	Descrição
WebPubSubForSocketIOConnectionString__endpoint	Obrigatória. O Ponto de Extremidade do serviço. Por exemplo, https://mysocketio.webpubsub.azure.com
WebPubSubForSocketIOConnectionString__credential	Define como um token deve ser obtido para a conexão. Essa configuração deve ser definida como managedidentity se o Azure Function implantado pretender usar a autenticação de identidade gerenciada. Esse valor só é válido quando uma identidade gerenciada está disponível no ambiente de hospedagem.
WebPubSubForSocketIOConnectionString__clientId	Quando credential estiver definido como managedidentity, essa propriedade poderá ser definida para especificar a identidade atribuída pelo usuário a ser usada ao obter um token. A propriedade aceita uma ID de cliente correspondente a uma identidade atribuída pelo usuário atribuída ao aplicativo. Se não for especificada, a identidade atribuída pelo sistema será usada.

A vinculação de função segue as propriedades comuns para a configuração baseada em identidade. Confira Propriedades comuns para conexões baseadas em identidade para obter mais propriedades não mencionadas.

Para o desenvolvimento local, use o arquivo local.settings.json para armazenar a cadeia de conexão. Configure WebPubSubForSocketIOConnectionString para a cadeia de conexão copiada da etapa anterior:

{
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "WebPubSubForSocketIOConnectionString__endpoint": "https://<webpubsub-name>.webpubsub.azure.com",
    "WebPubSubForSocketIOConnectionString__tenant": "<tenant id you're in>",
  }
}

Se quiser usar a configuração baseada em identidade e executar online, o AzureWebJobsStorage deve se referir à Conexão ao armazenamento de host com uma identidade.

Associação de entrada

A vinculação de entrada do Socket.IO gera um SocketIONegotiationResult para a solicitação de negociação do cliente. Quando tenta se conectar ao serviço, um cliente do Socket.IO precisa saber o endpoint, path e access token para a autenticação. É uma prática comum ter um servidor para gerar esses dados, o que é chamado de negociação.

C#

[FunctionName("SocketIONegotiate")]
public static IActionResult Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req,
    [SocketIONegotiation(Hub = "hub", UserId = "userId")] SocketIONegotiationResult result)
{
    return new OkObjectResult(result);
}

Atributo

O atributo para a vinculação de entrada é [SocketIONegotiation].

Propriedade de atributo	Descrição
Hub	O nome do hub ao qual um cliente precisa se conectar.
Conexão	O nome da configuração do aplicativo que contém a cadeia de conexão do Socket.IO (o padrão é WebPubSubForSocketIOConnectionString).
UserId	A userId da conexão. Aplica-se a todos os soquetes na conexão. E se torna a declaração sub no token gerado.

Modelo JavaScript v4

import { app, HttpRequest, HttpResponseInit, InvocationContext, input, } from "@azure/functions";

const socketIONegotiate = input.generic({
    type: 'socketionegotiation',
    direction: 'in',
    name: 'result',
    hub: 'hub',
});

export async function negotiate(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    let result = context.extraInputs.get(socketIONegotiate);
    return { jsonBody: result };
};

// Negotiation
app.http('negotiate', {
    methods: ['GET'],
    authLevel: 'anonymous',
    extraInputs: [socketIONegotiate],
    handler: negotiate
});

Configuração

Propriedade	Descrição
tipo	Precisa ser socketionegotiation
direction	Precisa ser in
name	Nome da variável usada no código da função para o objeto de vinculação da conexão de entrada
hub	O nome do hub ao qual um cliente precisa se conectar.
connection	O nome da configuração do aplicativo que contém a cadeia de conexão do Socket.IO (o padrão é WebPubSubForSocketIOConnectionString).
userId	A userId da conexão. Aplica-se a todos os soquetes na conexão. E se torna a declaração sub no token gerado.

Modelo do Python v2

Uma função sempre precisa de uma vinculação de gatilho. Usamos HttpTrigger como um exemplo nos códigos.

import azure.functions as func
app = func.FunctionApp()

@app.function_name(name="negotiate")
@app.route(auth_level=func.AuthLevel.ANONYMOUS)
@app.generic_input_binding(arg_name="negotiate", type="socketionegotiation", hub="hub")
def negotiate(req: func.HttpRequest, negotiate) -> func.HttpResponse:
    return func.HttpResponse(negotiate)

Anotação

Propriedade	Descrição
arg_name	O nome da variável do argumento na função para representar a vinculação de entrada.
tipo	Precisa ser socketionegotiation
hub	O nome do hub ao qual um cliente precisa se conectar.
connection	O nome da configuração do aplicativo que contém a cadeia de conexão do Socket.IO (o padrão é WebPubSubForSocketIOConnectionString).
userId	A userId da conexão. Aplica-se a todos os soquetes na conexão. E se torna a declaração sub no token gerado.

Vinculação de gatilho

O Azure Functions usa a vinculação de gatilho para disparar uma função para processar os eventos do Web PubSub para Socket.IO.

A vinculação de gatilho expõe um caminho específico seguido do ponto de extremidade do Azure Functions. A url deve ser configurada como o Modelo de URL do serviço (Portal: configurações -> manipulador de eventos -> Modelo de URL). No padrão do ponto de extremidade, a parte de consulta code=<API_KEY> é NECESSÁRIA quando você está usando o Aplicativo de Funções do Azure por motivos desegurança. A chave pode ser encontrada no portal do Azure. Encontre o recurso do aplicativo de funções e navegue até Funções ->Chaves do aplicativo ->Chaves do sistema ->socketio_extension após você implantar o aplicativo de funções no Azure. No entanto, essa chave não é necessária quando se está trabalhando com funções locais.

<Function_App_Endpoint>/runtime/webhooks/socketio?code=<API_KEY>

C#

Gatilhos de função para o evento de conexão de soquete.

[FunctionName("SocketIOTriggerConnect")]
public static async Task<SocketIOEventHandlerResponse> Connect(
    [SocketIOTrigger("hub", "connect")] SocketIOConnectRequest request)
{
    return new SocketIOConnectResponse();
}

Gatilhos de função para o evento conectado de soquete.

[FunctionName("SocketIOTriggerConnected")]
public static async Task Connected(
    [SocketIOTrigger("hub", "connected")] SocketIOConnectedRequest request)
{
}

Gatilhos de função para o evento de desconexão de soquete.

[FunctionName("SocketIOTriggerDisconnected")]
public static async Task Disconnected(
    [SocketIOTrigger("hub", "disconnected")] SocketIODisconnectedRequest request)
{
}

Gatilhos de função para mensagens normais de clientes.

[FunctionName("SocketIOTriggerMessage")]
public static async Task NewMessage(
    [SocketIOTrigger("hub", "new message")] SocketIOMessageRequest request,
    [SocketIOParameter] string arg)
{
}

Atributos

O atributo para a vinculação de gatilho é [SocketIOTrigger].

Propriedade de atributo	Descrição
Hub	O nome do hub ao qual um cliente precisa se conectar.
Namespace	O namespace do soquete. Padrão: "/"
EventName	O nome do evento para o qual a função dispara. Alguns nomes de evento são predefinidos: connect para o evento de conexão de soquete. connected para o evento conectado de soquete. disconnected para o evento desconectado de soquete. E os outros eventos são definidos pelo usuário e precisam corresponder ao nome do evento enviado pelo lado do cliente.
ParameterNames	A lista de nomes de parâmetros do evento. O comprimento da lista deve ser consistente com o evento enviado do cliente. E o nome usa as Expressões de vinculação e o acesso pelo parâmetro de função de mesmo nome.

Dados de vinculação

[SocketIOTrigger] vincula algumas variáveis aos dados de vinculação. Saiba mais sobre isso nos Padrões de expressão de vinculação do Azure Functions

SocketIOAttribute

SocketIOAttribute é uma alternativa de ParameterNames, o que simplifica a definição da função. Por exemplo, as duas definições a seguir têm o mesmo efeito:

[FunctionName("SocketIOTriggerMessage")]
public static async Task NewMessage(
    [SocketIOTrigger("hub", "new message")] SocketIOMessageRequest request,
    [SocketIOParameter] string arg)
{
}

[FunctionName("SocketIOTriggerMessage")]
public static async Task NewMessage(
    [SocketIOTrigger("hub", "new message", ParameterNames = new[] {"arg"})] SocketIOMessageRequest request,
    string arg)
{
}

Observe que ParameterNames e [SocketIOParameter] não podem ser usados juntos.

Modelo JavaScript v4

Gatilhos de função para o evento de conexão de soquete.

import { app, InvocationContext, input, trigger } from "@azure/functions";


export async function connect(request: any, context: InvocationContext): Promise<any> {
    return {};
}

// Trigger for connect
app.generic('connect', {
  trigger: trigger.generic({
    type: 'socketiotrigger',
    hub: 'hub',
    eventName: 'connect'
  }),
  handler: connect
});

Gatilhos de função para o evento conectado de soquete.

import { app, InvocationContext, trigger } from "@azure/functions";

export async function connected(request: any, context: InvocationContext): Promise<void> {
}

// Trigger for connected
app.generic('connected', {
    trigger: trigger.generic({
        type: 'socketiotrigger',
        hub: 'hub',
        eventName: 'connected'
    }),
    handler: connected
});

Gatilhos de função para o evento desconectado do soquete.

import { app, InvocationContext, trigger } from "@azure/functions";

export async function disconnected(request: any, context: InvocationContext): Promise<void> {
}

// Trigger for connected
app.generic('disconnected', {
    trigger: trigger.generic({
        type: 'socketiotrigger',
        hub: 'hub',
        eventName: 'disconnected'
    }),
    handler: disconnected
});

Gatilhos de função para mensagens normais de clientes.

import { app, InvocationContext, trigger, output } from "@azure/functions";

export async function newMessage(request: any, context: InvocationContext): Promise<void> {
}

// Trigger for new message
app.generic('newMessage', {
    trigger: trigger.generic({
        type: 'socketiotrigger',
        hub: 'hub',
        eventName: 'new message'
    }),
    handler: newMessage
});

Configuração

Propriedade	Descrição
tipo	Precisa ser socketiotrigger
hub	O nome do hub ao qual um cliente precisa se conectar.
namespace	O namespace do soquete. Padrão: "/"
eventName	O nome do evento para o qual a função dispara. Alguns nomes de evento são predefinidos: connect para o evento de conexão de soquete. connected para o evento conectado de soquete. disconnected para o evento desconectado de soquete. E os outros eventos são definidos pelo usuário e precisam corresponder ao nome do evento enviado pelo lado do cliente.
ParameterNames	A lista de nomes de parâmetros do evento. O comprimento da lista deve ser consistente com o evento enviado do cliente. E o nome usa as Expressões de vinculação e o acesso por context.bindings.<name>.

Modelo do Python v2

Gatilhos de função para o evento de conexão de soquete.

import azure.functions as func
from azure.functions.decorators.core import DataType
import json
app = func.FunctionApp()

@app.generic_trigger(arg_name="sio", type="socketiotrigger", data_type=DataType.STRING, hub="hub", eventName="connect")
def connect(sio: str) -> str:
    return json.dumps({'statusCode': 200})

Gatilhos de função para o evento conectado de soquete.

import azure.functions as func
from azure.functions.decorators.core import DataType
import json
app = func.FunctionApp()

@app.generic_trigger(arg_name="sio", type="socketiotrigger", data_type=DataType.STRING, hub="hub", eventName="connected")
def connected(sio: str) -> None:
    print("connected")

Gatilhos de função para o evento desconectado do soquete.

import azure.functions as func
from azure.functions.decorators.core import DataType
import json
app = func.FunctionApp()

@app.generic_trigger(arg_name="sio", type="socketiotrigger", data_type=DataType.STRING, hub="hub", eventName="disconnected")
def connected(sio: str) -> None:
    print("disconnected")

Gatilhos de função para mensagens normais de clientes.

import azure.functions as func
from azure.functions.decorators.core import DataType
import json
app = func.FunctionApp()

@app.generic_trigger(arg_name="sio", type="socketiotrigger", data_type=DataType.STRING, hub="hub", eventName="chat")
def chat(sio: str) -> None:
    # do something else

Gatilho de função para mensagens normais com retorno de chamada.

import azure.functions as func
from azure.functions.decorators.core import DataType
import json
app = func.FunctionApp()

@app.generic_trigger(arg_name="sio", type="socketiotrigger", data_type=DataType.STRING, hub="hub", eventName="chat")
def chat(sio: str) -> str:
    return json.dumps({'ack': ["param1"]})

Anotação

Propriedade	Descrição
arg_name	O nome da variável do argumento na função para representar a vinculação de gatilho.
tipo	Precisa ser socketiotrigger
hub	O nome do hub ao qual um cliente precisa se conectar.
data_type	Precisa ser DataType.STRING
namespace	O namespace do soquete. Padrão: "/"
eventName	O nome do evento para o qual a função dispara. Alguns nomes de evento são predefinidos: connect para o evento de conexão de soquete. connected para o evento conectado de soquete. disconnected para o evento desconectado de soquete. E os outros eventos são definidos pelo usuário e precisam corresponder ao nome do evento enviado pelo lado do cliente.

Solicitação de Vinculação de Entrada

A estrutura de dados dos argumentos de vinculação de entrada varia dependendo do tipo de mensagem.

Conectar

{
    "namespace": "",
    "socketId": "",
    "claims": {
        "<claim-type>": [ "<claim-value>" ]
    },
    "query": {
        "<query-key>": [ "<query-value>" ]
    },
    "headers":{
        "<header-name>": [ "<header-value>" ]
    },
    "clientCertificates":{
        {
            "thumbprint": "",
            "content": ""
        }
    }
}

Propriedade	Descrição
namespace	O namespace do soquete.
socketId	A identidade exclusiva do soquete.
declarações	A declaração do JWT da conexão do cliente. Observe que não é o JWT de quando o serviço solicita a função, mas o JWT de quando o cliente Engine.IO se conecta ao serviço.
consulta	A consulta da conexão do cliente. Observe que não é a consulta de quando o serviço solicita a função, mas a consulta de quando o cliente Engine.IO se conecta ao serviço.
headers	Os cabeçalhos da conexão do cliente. Observe que não são os cabeçalhos de quando o serviço solicita a função, mas os cabeçalhos de quando o cliente Engine.IO se conecta ao serviço.
clientCertificates	O certificado do cliente, se estiver habilitado

Conectado

{
    "namespace": "",
    "socketId": "",
}

Propriedade	Descrição
namespace	O namespace do soquete.
socketId	A identidade exclusiva do soquete.

Desconectado

{
    "namespace": "",
    "socketId": "",
    "reason": ""
}

Propriedade	Descrição
namespace	O namespace do soquete.
socketId	A identidade exclusiva do soquete.
reason	A descrição do motivo do encerramento da conexão.

Eventos normais

{
    "namespace": "",
    "socketId": "",
    "payload": "",
    "eventName": "",
    "parameters": []
}

Propriedade	Descrição
namespace	O namespace do soquete.
socketId	A identidade exclusiva do soquete.
payload	O conteúdo da mensagem no protocolo Engine.IO
eventName	O nome do evento da solicitação.
parâmetros	Lista de parâmetros da mensagem.

Associação de saída

Atualmente, a vinculação de saída dá suporte à seguinte funcionalidade:

• Adicionar um soquete à sala
• Remover um soquete da sala
• Enviar mensagens para um soquete
• Enviar mensagens para uma sala
• Enviar mensagens para um namespace
• Desconectar soquetes

C#

[FunctionName("SocketIOOutput")]
public static async Task<IActionResult> SocketIOOutput(
    [SocketIOTrigger("hub", "new message")] SocketIOMessageRequest request,
    [SocketIO(Hub = "hub")] IAsyncCollector<SocketIOAction> collector)
{
    await collector.AddAsync(SocketIOAction.CreateSendToNamespaceAction("new message", new[] { "arguments" }));
}

Atributo

O atributo para a vinculação de entrada é [SocketIO].

Propriedade de atributo	Descrição
Hub	O nome do hub ao qual um cliente precisa se conectar.
Conexão	O nome da configuração do aplicativo que contém a cadeia de conexão do Socket.IO (o padrão é WebPubSubForSocketIOConnectionString).

Modelo JavaScript v4

import { app, InvocationContext, trigger, output } from "@azure/functions";

const socketio = output.generic({
  type: 'socketio',
  hub: 'hub',
})

export async function newMessage(request: any, context: InvocationContext): Promise<void> {
    context.extraOutputs.set(socketio, {
      actionName: 'sendToNamespace',
      namespace: '/',
      eventName: 'new message',
      parameters: [
        "argument"
      ]
    });
}

// Trigger for new message
app.generic('newMessage', {
    trigger: trigger.generic({
        type: 'socketiotrigger',
        hub: 'hub',
        eventName: 'new message'
    }),
    extraOutputs: [socketio],
    handler: newMessage
});

Configuração

Propriedade de atributo	Descrição
tipo	Precisa ser socketio
hub	O nome do hub ao qual um cliente precisa se conectar.
connection	O nome da configuração do aplicativo que contém a cadeia de conexão do Socket.IO (o padrão é WebPubSubForSocketIOConnectionString).

Modelo do Python v2

Uma função sempre precisa de uma vinculação de gatilho. Usamos o TimerTrigger como um exemplo nos códigos.

import azure.functions as func
from azure.functions.decorators.core import DataType
import json

app = func.FunctionApp()

@app.timer_trigger(schedule="* * * * * *", arg_name="myTimer", run_on_startup=False,
              use_monitor=False)
@app.generic_output_binding(arg_name="sio", type="socketio", data_type=DataType.STRING, hub="hub")
def new_message(myTimer: func.TimerRequest,
                 sio: func.Out[str]) -> None:
    sio.set(json.dumps({
        'actionName': 'sendToNamespace',
        'namespace': '/',
        'eventName': 'update',
        'parameters': [
            "message"
        ]
    }))

Anotação

Propriedade de atributo	Descrição
arg_name	O nome da variável do argumento na função para representar a vinculação de saída.
tipo	Precisa ser socketio
data_type	Use DataType.STRING.
hub	O nome do hub ao qual um cliente precisa se conectar.
connection	O nome da configuração do aplicativo que contém a cadeia de conexão do Socket.IO (o padrão é WebPubSubForSocketIOConnectionString).

Ações

A vinculação de saída usa ações para executar operações. Atualmente, damos suporte às seguintes ações:

AddSocketToRoomAction

{
    "type": "AddSocketToRoom",
    "socketId": "",
    "room": ""
}

RemoveSocketFromRoomAction

{
    "type": "RemoveSocketFromRoom",
    "socketId": "",
    "room": ""
}

SendToNamespaceAction

{
    "type": "SendToNamespace",
    "eventName": "",
    "parameters": [],
    "exceptRooms": []
}

SendToRoomsAction

{
    "type": "SendToRoom",
    "eventName": "",
    "parameters": [],
    "rooms": [],
    "exceptRooms": []
}

SendToSocketAction

{
    "type": "SendToSocket",
    "eventName": "",
    "parameters": [],
    "socketId": ""
}

DisconnectSocketsAction

{
    "type": "DisconnectSockets",
    "rooms": [],
    "closeUnderlyingConnection": false
}