Socket.IO Gatilho e vinculação do Azure Function (Visualização)

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

Ação	Tipo de Enlace
Obter resultado de negociação do cliente, incluindo url e token de acesso	Vinculação de entrada
Acionado por mensagens do serviço	Vinculação de gatilho
Invoque o serviço para enviar mensagens ou gerenciar clientes	Vinculação de saída

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

Importante

As associações de Função do Azure só podem ser integradas com o 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 configuração baseada em identidade para autenticar com o serviço.

Configuração baseada em chave de acesso

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

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

Para o desenvolvimento local, use o local.settings.json arquivo para armazenar a cadeia de conexão. Defina WebPubSubForSocketIOConnectionString como 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;"
  }
}

Quando implantado, use as configurações do aplicativo para definir a cadeia de conexão.

Configuração baseada em identidade

Nome da Configuração	Description
WebPubSubForSocketIOConnectionString__endpoint	Obrigatório. 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 sua Função do Azure implantada pretende 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 é definido como managedidentity, essa propriedade pode ser definida para especificar a identidade atribuída pelo usuário a ser usada ao obter um token. A propriedade aceita um ID de cliente correspondente a uma identidade atribuída pelo usuário atribuída ao aplicativo. Se não for especificado, a identidade atribuída ao sistema será usada.

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

Para o desenvolvimento local, use o local.settings.json arquivo para armazenar a cadeia de conexão. Defina WebPubSubForSocketIOConnectionString como 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 você quiser usar a configuração baseada em identidade e executar online, consulte AzureWebJobsStorageConectando-se ao armazenamento do host com uma identidade.

Enlace de Entrada

Socket.IO A vinculação de entrada gera uma SocketIONegotiationResult solicitação de negociação para o cliente. Quando um cliente Socket.IO tenta se conectar ao serviço, ele precisa saber o endpoint, pathe access token para 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 vinculação de entrada é [SocketIONegotiation].

Propriedade Attribute	Description
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 Socket.IO (o padrão é ).WebPubSubForSocketIOConnectionString
UserId	O userId da conexão. Ele se aplica a todos os soquetes na conexão. Torna-se a sub declaração 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

Property	Descrição
tipo	Deve ser socketionegotiation
direção	Deve ser in
nome	Nome da variável usado no código da função para o objeto de ligação de conexão de entrada
hub	O nome do hub ao qual um cliente precisa se conectar.
ligação	O nome da configuração do aplicativo que contém a cadeia de conexão Socket.IO (o padrão é ).WebPubSubForSocketIOConnectionString
ID de Utilizador	O userId da conexão. Ele se aplica a todos os soquetes na conexão. Torna-se a sub declaração no token gerado.

Modelo Python v2

Uma função sempre precisa de uma ligação de gatilho. Usamos HttpTrigger como exemplo em 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

Property	Description
arg_name	O nome da variável do argumento na função para representar a ligação de entrada.
tipo	Deve ser socketionegotiation
hub	O nome do hub ao qual um cliente precisa se conectar.
ligação	O nome da configuração do aplicativo que contém a cadeia de conexão Socket.IO (o padrão é ).WebPubSubForSocketIOConnectionString
ID de Utilizador	O userId da conexão. Ele se aplica a todos os soquetes na conexão. Torna-se a sub declaração no token gerado.

Vinculação de gatilho

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

A associação de gatilho expõe um caminho específico seguido do ponto de extremidade da Função do Azure. O url deve ser definido como o modelo de URL do serviço (Portal: configurações -> manipulador de eventos -> Modelo de URL). No padrão de ponto de extremidade, a parte code=<API_KEY> de consulta é NECESSÁRIA quando você estiver usando o Aplicativo de Função do Azure por motivos de segurança . A chave pode ser encontrada no portal do Azure. Encontre seu recurso de aplicativo de função e navegue até Funções ->Chaves de aplicativo ->Chaves do sistema ->socketio_extension depois de implantar o aplicativo de função no Azure. No entanto, essa chave não é necessária quando você 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 evento conectado ao soquete.

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

Gatilhos de função para o evento de desconexão do 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 ligação de gatilho é [SocketIOTrigger].

Propriedade Attribute	Description
Hub	O nome do hub ao qual um cliente precisa se conectar.
Espaço de Nomes	O namespace do soquete. Padrão: "/"
EventName	O nome do evento para o qual a função é acionada. Alguns nomes de eventos são predefinidos: connect para o evento socket connect. connected para evento conectado ao soquete. disconnected para evento de desconexão de soquete. E outros eventos são definidos pelo usuário e precisam corresponder ao nome do evento enviado pelo lado do cliente.
Nomes de parâmetros	A lista de nomes de parâmetros do evento. O tamanho da lista deve ser consistente com o evento enviado pelo cliente. E o nome usa as expressões Binding e o acesso pelo parâmetro de função do mesmo nome.

Vinculação de dados

[SocketIOTrigger] Vincula algumas variáveis à vinculação de dados. Você pode saber mais sobre isso em Padrões de expressão de vinculação do Azure Functions

SocketIOAttribute

SocketIOAttribute é uma alternativa de , que simplifica a definição da ParameterNamesfunção. Por exemplo, as duas definições seguintes 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 isso ParameterNames e [SocketIOParameter] não pode ser usado em conjunto.

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 evento conectado ao 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 evento de soquete desconectado.

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

Property	Descrição
tipo	Deve ser socketiotrigger
hub	O nome do hub ao qual um cliente precisa se conectar.
espaço de nomes	O namespace do soquete. Padrão: "/"
eventName	O nome do evento para o qual a função é acionada. Alguns nomes de eventos são predefinidos: connect para o evento socket connect. connected para evento conectado ao soquete. disconnected para evento de desconexão de soquete. E outros eventos são definidos pelo usuário e precisam corresponder ao nome do evento enviado pelo lado do cliente.
Nomes de parâmetros	A lista de nomes de parâmetros do evento. O tamanho da lista deve ser consistente com o evento enviado pelo cliente. E o nome usa as expressões Binding e acesso por context.bindings.<name>.

Modelo 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 evento conectado ao 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 evento de soquete desconectado.

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

Property	Description
arg_name	O nome da variável do argumento na função para representar a ligação do gatilho.
tipo	Deve ser socketiotrigger
hub	O nome do hub ao qual um cliente precisa se conectar.
data_type	Deve ser DataType.STRING
espaço de nomes	O namespace do soquete. Padrão: "/"
eventName	O nome do evento para o qual a função é acionada. Alguns nomes de eventos são predefinidos: connect para o evento socket connect. connected para evento conectado ao soquete. disconnected para evento de desconexão de soquete. E outros eventos são definidos pelo usuário e precisam corresponder ao nome do evento enviado pelo lado do cliente.

Pedido de Vinculação de Entrada

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

Ligar

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

Property	Description
espaço de nomes	O namespace do soquete.
socketId	A identidade única do soquete.
afirmações	A reivindicação de JWT da conexão do cliente. Observe que não é o JWT quando o serviço solicita a função, mas o JWT quando o cliente Engine.IO se conecta ao serviço.
query	A consulta da conexão do cliente. Observe que não é a consulta quando o serviço solicita a função, mas a consulta quando o cliente Engine.IO se conecta ao serviço.
cabeçalhos	Os cabeçalhos da conexão do cliente. Observe que não são os cabeçalhos quando o serviço solicita a função, mas os cabeçalhos quando o cliente Engine.IO se conecta ao serviço.
clientCertificados	O certificado do cliente, se estiver habilitado

Ligado

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

Property	Description
espaço de nomes	O namespace do soquete.
socketId	A identidade única do soquete.

Desligado

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

Property	Description
espaço de nomes	O namespace do soquete.
socketId	A identidade única do soquete.
reason	A descrição do motivo de fechamento da conexão.

Acontecimentos normais

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

Property	Description
espaço de nomes	O namespace do soquete.
socketId	A identidade única do soquete.
payload	A carga útil da mensagem no protocolo Engine.IO
eventName	O nome do evento da solicitação.
parâmetros	Lista de parâmetros da mensagem.

Enlace de Saída

A vinculação de saída atualmente suporta a seguinte funcionalidade:

• Adicionar uma tomada à sala
• Remover uma tomada 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 vinculação de entrada é [SocketIO].

Propriedade Attribute	Description
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 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 Attribute	Description
tipo	Deve ser socketio
hub	O nome do hub ao qual um cliente precisa se conectar.
ligação	O nome da configuração do aplicativo que contém a cadeia de conexão Socket.IO (o padrão é ).WebPubSubForSocketIOConnectionString

Modelo Python v2

Uma função sempre precisa de uma ligação de gatilho. Usamos TimerTrigger como exemplo em 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 Attribute	Description
arg_name	O nome da variável do argumento na função para representar a ligação de saída.
tipo	Deve ser socketio
data_type	Utilizar o comando DataType.STRING
hub	O nome do hub ao qual um cliente precisa se conectar.
ligação	O nome da configuração do aplicativo que contém a cadeia de conexão Socket.IO (o padrão é ).WebPubSubForSocketIOConnectionString

Ações

A vinculação de saída usa ações para executar operações. Atualmente, apoiamos as seguintes ações:

AddSocketToRoomAction

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

RemoveSocketFromRoomAction

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

SendToNamespaceAction

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

SendToRoomsAção

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

SendToSocketAction

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

DisconnectSocketsAction

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