Socket.IO trigger e binding di Funzioni di Azure (anteprima)

Questo articolo illustra come usare Socket.IO'integrazione serverless con Funzioni di Azure.

Azione	Tipo di associazione
Ottenere il risultato della negoziazione client, inclusi l'URL e il token di accesso	Associazione di input
Attivato dai messaggi dal servizio	Associazione di trigger
Richiamare il servizio per inviare messaggi o gestire i client	Associazione di output

Codice sorgente | Pacchetto | Documentazione di riferimento dell'API | Documentazione del prodotto | Esempi

Importante

Le associazioni di funzioni di Azure possono essere integrate solo con Web PubSub per Socket.IO in modalità serverless.

Autenticare e stringa di connessione

Per consentire l'uso dell'estensione con Web PubSub per Socket.IO, è necessario fornire chiavi di accesso o configurazione basata su identità per l'autenticazione con il servizio.

Configurazione basata su chiavi di accesso

Nome della configurazione	Descrizione
WebPubSubForSocketIOConnectionString	Obbligatorio. Stringa di connessione basata su chiave per il servizio

È possibile trovare il stringa di connessione nel pannello Chiavi nel sito Web PubSub per Socket.IO nel portale di Azure.

Per lo sviluppo locale, usare il local.settings.json file per archiviare il stringa di connessione. Impostare WebPubSubForSocketIOConnectionString sul stringa di connessione copiato dal passaggio precedente:

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

Quando viene distribuita, usare le impostazioni dell'applicazione per impostare il stringa di connessione.

Configurazione basata su identità

Nome della configurazione	Descrizione
WebPubSubForSocketIOConnectionString__endpoint	Obbligatorio. Endpoint del servizio. Ad esempio, https://mysocketio.webpubsub.azure.com
WebPubSubForSocketIOConnectionString__credential	Definisce come ottenere un token per la connessione. Questa impostazione deve essere impostata su managedidentity se la funzione di Azure distribuita intende usare l'autenticazione dell'identità gestita. Questo valore è valido solo quando un'identità gestita è disponibile nell'ambiente di hosting.
WebPubSubForSocketIOConnectionString__clientId	Quando credential è impostato su managedidentity, questa proprietà può essere impostata per specificare l'identità assegnata dall'utente da usare per ottenere un token. La proprietà accetta un ID client corrispondente a un'identità assegnata dall'utente assegnata all'applicazione. Se non specificata, viene usata l'identità assegnata dal sistema.

L'associazione di funzioni segue le proprietà comuni per la configurazione basata su identità. Per altre proprietà non autorizzate, vedere Proprietà comuni per le connessioni basate su identità.

Per lo sviluppo locale, usare il local.settings.json file per archiviare il stringa di connessione. Impostare WebPubSubForSocketIOConnectionString sul stringa di connessione copiato dal passaggio precedente:

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

Se si vuole usare la configurazione basata su identità e l'esecuzione online, AzureWebJobsStorage fare riferimento a Connessione all'archiviazione host con un'identità.

Binding di input

Socket.IO binding di input genera un oggetto SocketIONegotiationResult alla richiesta di negoziazione client. Quando un client Socket.IO tenta di connettersi al servizio, deve conoscere endpoint, pathe access token per l'autenticazione. È pratica comune avere un server per generare questi dati, che è detto negoziazione.

C#

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

Attributo

L'attributo per l'associazione di input è [SocketIONegotiation].

Proprietà dell'attributo	Descrizione
Hub	Nome dell'hub a cui deve connettersi un client.
Connessione	Nome dell'impostazione dell'app che contiene il Socket.IO stringa di connessione (per impostazione predefinita è WebPubSubForSocketIOConnectionString).
ID utente	Id utente della connessione. Si applica a tutti i socket nella connessione. Diventa l'attestazione sub nel token generato.

Modello 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
});

Impostazione

Proprietà	Descrizione
type	Deve essere socketionegotiation
direction	Deve essere in
name	Nome della variabile usato nel codice della funzione per l'oggetto di associazione di connessione di input
hub	Nome dell'hub a cui deve connettersi un client.
connection	Nome dell'impostazione dell'app che contiene il Socket.IO stringa di connessione (per impostazione predefinita è WebPubSubForSocketIOConnectionString).
userId	Id utente della connessione. Si applica a tutti i socket nella connessione. Diventa l'attestazione sub nel token generato.

Modello Python v2

Una funzione richiede sempre un'associazione di trigger. Come esempio nei codici viene usato HttpTrigger.

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)

Annotazione

Proprietà	Descrizione
arg_name	Nome della variabile dell'argomento nella funzione per rappresentare l'associazione di input.
type	Deve essere socketionegotiation
hub	Nome dell'hub a cui deve connettersi un client.
connection	Nome dell'impostazione dell'app che contiene il Socket.IO stringa di connessione (per impostazione predefinita è WebPubSubForSocketIOConnectionString).
userId	Id utente della connessione. Si applica a tutti i socket nella connessione. Diventa l'attestazione sub nel token generato.

Associazione di trigger

La funzione di Azure usa l'associazione di trigger per attivare una funzione per elaborare gli eventi da Web PubSub per Socket.IO.

L'associazione di trigger espone un percorso specifico seguito dall'endpoint della funzione di Azure. L'URL deve essere impostato come modello URL del servizio (portale: impostazioni -> gestore eventi -> Modello URL). Nel modello di endpoint, la parte code=<API_KEY> di query è OBBLIGATORIA quando si usa l'app per le funzioni di Azure per motivi di sicurezza. La chiave è disponibile nel portale di Azure. Trovare la risorsa dell'app per le funzioni e passare a Funzioni ->Chiavi app -Chiavi di sistema ->>socketio_extension dopo aver distribuito l'app per le funzioni in Azure. Tuttavia, questa chiave non è necessaria quando si lavora con le funzioni locali.

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

C#

Trigger di funzione per l'evento di connessione socket.

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

Trigger di funzione per l'evento connesso al socket.

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

Trigger di funzione per l'evento di disconnessione socket.

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

Trigger di funzione per i normali messaggi provenienti dai client.

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

Attributi

L'attributo per l'associazione di trigger è [SocketIOTrigger].

Proprietà dell'attributo	Descrizione
Hub	Nome dell'hub a cui deve connettersi un client.
Spazio dei nomi	Spazio dei nomi del socket. Impostazione predefinita: "/"
EventName	Nome dell'evento per cui viene attivata la funzione. Alcuni nomi di eventi sono predefiniti: connect per l'evento di connessione socket. connected per l'evento connesso al socket. disconnected per l'evento disconnesso del socket. Gli altri eventi vengono definiti dall'utente e devono corrispondere al nome dell'evento inviato dal lato client.
ParameterNames	Elenco dei nomi dei parametri dell'evento. La lunghezza dell'elenco deve essere coerente con l'evento inviato dal client. E il nome usa le espressioni binding e l'accesso tramite il parametro della funzione same-name.

Binding Data

[SocketIOTrigger] associa alcune variabili ai dati di associazione. Per altre informazioni, vedere Funzioni di Azure modelli di espressione di associazione

SocketIOAttribute

SocketIOAttribute è un'alternativa a ParameterNames, che semplifica la definizione della funzione. Ad esempio, le due definizioni seguenti hanno lo stesso effetto:

[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)
{
}

Si noti che ParameterNames e [SocketIOParameter] non possono essere usati insieme.

Modello JavaScript v4

Trigger di funzione per l'evento di connessione socket.

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
});

Trigger di funzione per l'evento connesso al socket.

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
});

Trigger di funzione per l'evento disconnesso socket.

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
});

Trigger di funzione per i normali messaggi provenienti dai client.

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
});

Impostazione

Proprietà	Descrizione
type	Deve essere socketiotrigger
hub	Nome dell'hub a cui deve connettersi un client.
namespace	Spazio dei nomi del socket. Impostazione predefinita: "/"
eventName	Nome dell'evento per cui viene attivata la funzione. Alcuni nomi di eventi sono predefiniti: connect per l'evento di connessione socket. connected per l'evento connesso al socket. disconnected per l'evento disconnesso del socket. Gli altri eventi vengono definiti dall'utente e devono corrispondere al nome dell'evento inviato dal lato client.
ParameterNames	Elenco dei nomi dei parametri dell'evento. La lunghezza dell'elenco deve essere coerente con l'evento inviato dal client. E il nome usa le espressioni di associazione e l'accesso da context.bindings.<name>.

Modello Python v2

Trigger di funzione per l'evento di connessione socket.

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

Trigger di funzione per l'evento connesso al socket.

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

Trigger di funzione per l'evento disconnesso socket.

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

Trigger di funzione per i normali messaggi provenienti dai client.

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

Trigger di funzione per i normali messaggi con callback.

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"]})

Annotazione

Proprietà	Descrizione
arg_name	Nome della variabile dell'argomento nella funzione per rappresentare l'associazione del trigger.
type	Deve essere socketiotrigger
hub	Nome dell'hub a cui deve connettersi un client.
data_type	Deve essere DataType.STRING
namespace	Spazio dei nomi del socket. Impostazione predefinita: "/"
eventName	Nome dell'evento per cui viene attivata la funzione. Alcuni nomi di eventi sono predefiniti: connect per l'evento di connessione socket. connected per l'evento connesso al socket. disconnected per l'evento disconnesso del socket. Gli altri eventi vengono definiti dall'utente e devono corrispondere al nome dell'evento inviato dal lato client.

Richiesta di associazione di input

La struttura dei dati degli argomenti di associazione di input varia a seconda del tipo di messaggio.

Connessione

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

Proprietà	Descrizione
namespace	Spazio dei nomi del socket.
socketId	Identità univoca del socket.
claims	Attestazione del token JWT della connessione client. Si noti che non è il token JWT quando il servizio richiede la funzione, ma il token JWT quando il client Engine.IO si connette al servizio.
query	Query della connessione client. Si noti che non è la query quando il servizio richiede la funzione, ma la query quando il client Engine.IO si connette al servizio.
headers	Intestazioni della connessione client. Si noti che non si tratta delle intestazioni quando il servizio richiede la funzione, ma le intestazioni quando il client Engine.IO si connette al servizio.
clientCertificates	Certificato client se è abilitato

Connesso

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

Proprietà	Descrizione
namespace	Spazio dei nomi del socket.
socketId	Identità univoca del socket.

Disconnesso

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

Proprietà	Descrizione
namespace	Spazio dei nomi del socket.
socketId	Identità univoca del socket.
reason	Descrizione del motivo di chiusura della connessione.

Eventi normali

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

Proprietà	Descrizione
namespace	Spazio dei nomi del socket.
socketId	Identità univoca del socket.
payload	Payload del messaggio nel protocollo Engine.IO
eventName	Nome dell'evento della richiesta.
parameters	Elenco dei parametri del messaggio.

Binding di output

L'associazione di output supporta attualmente le funzionalità seguenti:

• Aggiungere un socket alla stanza
• Rimuovere un socket dalla stanza
• Inviare messaggi a un socket
• Inviare messaggi a una sala
• Inviare messaggi a uno spazio dei nomi
• Disconnettere i socket

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" }));
}

Attributo

L'attributo per l'associazione di input è [SocketIO].

Proprietà dell'attributo	Descrizione
Hub	Nome dell'hub a cui deve connettersi un client.
Connessione	Nome dell'impostazione dell'app che contiene il Socket.IO stringa di connessione (per impostazione predefinita è WebPubSubForSocketIOConnectionString).

Modello 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
});

Impostazione

Proprietà dell'attributo	Descrizione
type	Deve essere socketio
hub	Nome dell'hub a cui deve connettersi un client.
connection	Nome dell'impostazione dell'app che contiene il Socket.IO stringa di connessione (per impostazione predefinita è WebPubSubForSocketIOConnectionString).

Modello Python v2

Una funzione richiede sempre un'associazione di trigger. Si usa TimerTrigger come esempio nei codici.

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"
        ]
    }))

Annotazione

Proprietà dell'attributo	Descrizione
arg_name	Nome della variabile dell'argomento nella funzione per rappresentare l'associazione di output.
type	Deve essere socketio
data_type	Utilizzare DataType.STRING.
hub	Nome dell'hub a cui deve connettersi un client.
connection	Nome dell'impostazione dell'app che contiene il Socket.IO stringa di connessione (per impostazione predefinita è WebPubSubForSocketIOConnectionString).

Azioni

L'associazione di output usa azioni per eseguire operazioni. Attualmente sono supportate le azioni seguenti:

AddSocketToRoomAction

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

RemoveSocketFromRoomAction

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

SendToNamespaceAction

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

SendToRoomAction

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

SendToSocketAction

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

DisconnectSocketsAction

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