Socket.IO Azure Function-Trigger und -Bindung (Vorschau)

In diesem Artikel wird erläutert, wie Sie die serverlose Integration von Socket.IO in Azure Functions verwenden.

Aktion	Bindungstyp
Abrufen des Client-Aushandlungsergebnisses einschließlich URL und Zugriffstoken	Eingabebindung
Ausgelöst durch Nachrichten vom Dienst	Triggerbindung
Aufrufen des Diensts zum Senden von Nachrichten oder Verwalten von Clients	Ausgabebindung

Quellcode | Paket | API-Referenzdokumentation | Produktdokumentation | Beispiele

Wichtig

Bindungen von Azure Function können nur mit Web PubSub für Socket.IO im serverlosen Modus integriert werden.

Authentifizieren und Verbindungszeichenfolge

Damit die Erweiterung mit Web PubSub für Socket.IO funktioniert, müssen Sie entweder Zugriffsschlüssel oder eine identitätsbasierte Konfiguration für die Authentifizierung beim Dienst bereitstellen.

Auf Zugriffsschlüssel basierte Konfiguration

Konfigurationsname	Beschreibung
WebPubSubForSocketIOConnectionString	Erforderlich. Auf Schlüssel basierte Verbindungszeichenfolge zum Dienst

Sie finden die Verbindungszeichenfolge im Blatt Keys in Web PubSub für Socket.IO im Azure-Portal.

Verwenden Sie für die lokale Entwicklung die Datei local.settings.json, um die Verbindungszeichenfolge zu speichern. Legen Sie WebPubSubForSocketIOConnectionString für die vom vorherigen Schritt kopierte Verbindungszeichenfolge fest:

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

Verwenden Sie bei der Bereitstellung die Anwendungseinstellungen, um die Verbindungszeichenfolge festzulegen.

Auf Identität basierte Konfiguration

Konfigurationsname	Beschreibung
WebPubSubForSocketIOConnectionString__endpoint	Erforderlich. Der Endpunkt des Diensts. Beispiel: https://mysocketio.webpubsub.azure.com
WebPubSubForSocketIOConnectionString__credential	Damit wird festgelegt, wie für die Verbindung ein Token abgerufen werden soll. Diese Einstellung sollte auf managedidentity festgelegt werden, wenn Ihre bereitgestellte Azure-Funktion die Authentifizierung mit verwalteter Identität verwenden soll. Dieser Wert ist nur gültig, wenn eine verwaltete Identität in der Hostingumgebung verfügbar ist.
WebPubSubForSocketIOConnectionString__clientId	Wenn credential auf managedidentity festgelegt ist, kann mit dieser Eigenschaft die benutzerseitig zugewiesene Identität angegeben werden, die beim Abrufen eines Tokens verwendet werden soll. Die Eigenschaft akzeptiert eine Client-ID, die einer vom Benutzer zugewiesenen Identität entspricht, die der Anwendung zugeordnet ist. Wenn nichts angegeben wird, wird die vom System zugewiesene Identität verwendet.

Die Funktionsbindung folgt den allgemeinen Eigenschaften für die identitätsbasierte Konfiguration. Weitere nicht erwähnte Eigenschaften finden Sie unter Allgemeine Eigenschaften für identitätsbasierte Verbindungen.

Verwenden Sie für die lokale Entwicklung die Datei local.settings.json, um die Verbindungszeichenfolge zu speichern. Legen Sie WebPubSubForSocketIOConnectionString für die vom vorherigen Schritt kopierte Verbindungszeichenfolge fest:

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

Wenn Sie die identitätsbasierte Konfiguration verwenden und online ausführen möchten, sollte AzureWebJobsStorage auf Verbinden zum Hostspeicher mit einer Identität verweisen.

Eingabebindung

Die Socket.IO-Eingabebindung generiert SocketIONegotiationResult an die Client-Aushandlungsanforderung. Wenn ein Socket.IO-Client versucht, eine Verbindung mit dem Dienst herzustellen, muss er endpoint, pathund access token für die Authentifizierung kennen. Es ist üblich, einen Server zum Generieren dieser Daten zu verwenden, was als Aushandlung bezeichnet wird.

C#

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

attribute

Das Attribut für die Eingabebindung lautet [SocketIONegotiation].

Attributeigenschaft	Beschreibung
Hub	Der Hubname, mit dem ein Client eine Verbindung herstellen muss.
Verbindung	Der Name der App-Einstellung, die die Socket.IO Verbindungszeichenfolge enthält (Standardwert ist WebPubSubForSocketIOConnectionString).
UserId	Die UserId der Verbindung. Er gilt für alle Sockets in der Verbindung. Er wird zum Anspruch sub im generierten Token.

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

Konfiguration

Eigenschaft	Beschreibung des Dataflows
type	Muss gleich socketionegotiation sein.
Richtung	Muss gleich in sein.
Name	Variablenname, der im Funktionscode für das Bindungsobjekt der Eingabeverbindung verwendet wird
hub	Der Hubname, mit dem ein Client eine Verbindung herstellen muss.
Verbindung	Der Name der App-Einstellung, die die Socket.IO Verbindungszeichenfolge enthält (Standardwert ist WebPubSubForSocketIOConnectionString).
userId	Die UserId der Verbindung. Er gilt für alle Sockets in der Verbindung. Er wird zum Anspruch sub im generierten Token.

Python-Modell v2

Eine Funktion benötigt immer eine Triggerbindung. Wir verwenden HttpTrigger als Beispiel in Codes.

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)

Anmerkung

Eigenschaft	Beschreibung
arg_name	Der Variablename des Arguments in der Funktion, das die Eingabebindung darstellt.
type	Muss gleich socketionegotiation sein.
hub	Der Hubname, mit dem ein Client eine Verbindung herstellen muss.
Verbindung	Der Name der App-Einstellung, die die Socket.IO Verbindungszeichenfolge enthält (Standardwert ist WebPubSubForSocketIOConnectionString).
userId	Die UserId der Verbindung. Er gilt für alle Sockets in der Verbindung. Er wird zum Anspruch sub im generierten Token.

Triggerbindung

Azure Function verwendet Triggerbindung, um eine Funktion zum Verarbeiten der Ereignisse von Web PubSub für Socket.IO auszulösen.

Die Triggerbindung macht einen bestimmten Pfad verfügbar, gefolgt vom Azure Functions-Endpunkt. Die URL sollte als URL-Vorlage des Diensts festgelegt werden (Portal: Einstellungen –> Ereignishandler –> URL-Vorlage). Im Endpunktmuster ist der Abfrageteil code=<API_KEY> aus SicherheitsgründenERFORDERLICH, wenn Sie eine Azure-Funktions-App verwenden. Den Schlüssel finden Sie im Azure-Portal. Suchen Sie nach dem Bereitstellen der Funktions-App in Azure nach Ihrer Funktions-App-Ressource, und navigieren Sie zu Funktionen –>App-Schlüssel –>Systemschlüssel –>socketio_extention. Wenn Sie mit lokalen Funktionen arbeiten, wird dieser Schlüssel jedoch nicht benötigt.

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

C#

Funktionstrigger für Socket-Verbindungsereignis.

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

Funktionstrigger für mit Socket verbundenes Ereignis.

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

Funktionstrigger für Socket-Trennungsereignis.

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

Funktionstrigger für normale Nachrichten von Clients.

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

Attribute

Das Attribut für die Triggerbindung lautet [SocketIOTrigger].

Attributeigenschaft	Beschreibung
Hub	Der Hubname, mit dem ein Client eine Verbindung herstellen muss.
Namespace	Der Namespace des Sockets. Standard: „/“
EventName	Der Ereignisname, den die Funktion auslöst. Einige Ereignisnamen sind vordefiniert: connect für Socket-Verbindungsereignis. connected für mit Socket verbundenes Ereignis. disconnected für von Socket getrenntes Ereignis. Andere Ereignisse werden von Benutzer*innen definiert und müssen mit dem vom Client gesendeten Ereignisnamen übereinstimmen.
ParameterNames	Die Parameternamensliste des Ereignisses. Die Länge der Liste sollte mit dem vom Client gesendeten Ereignis konsistent sein. Der Name verwendet die Bindungsausdrücke und den Zugriff durch den Funktionsparameter mit demselben Namen.

Bindungsdaten

[SocketIOTrigger] bindet einige Variablen an Bindungsdaten. Weitere Informationen hierzu finden Sie unter Azure Functions-Muster für Bindungsausdrücke

SocketIOAttribute

SocketIOAttribute ist eine Alternative von ParameterNames, was die Funktionsdefinition vereinfacht. Die folgenden beiden Definitionen haben beispielsweise dieselbe Wirkung:

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

Beachten Sie, dass ParameterNames sie [SocketIOParameter] nicht zusammen verwendet werden können.

JavaScript-Modell v4

Funktionstrigger für Socket-Verbindungsereignis.

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

Funktionstrigger für mit Socket verbundenes Ereignis.

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

Funktionstrigger für von Socket getrenntes Ereignis.

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

Funktionstrigger für normale Nachrichten von Clients.

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

Konfiguration

Eigenschaft	Beschreibung des Dataflows
type	Muss gleich socketiotrigger sein.
hub	Der Hubname, mit dem ein Client eine Verbindung herstellen muss.
Namespace	Der Namespace des Sockets. Standard: „/“
eventName	Der Ereignisname, den die Funktion auslöst. Einige Ereignisnamen sind vordefiniert: connect für Socket-Verbindungsereignis. connected für mit Socket verbundenes Ereignis. disconnected für von Socket getrenntes Ereignis. Andere Ereignisse werden von Benutzer*innen definiert und müssen mit dem vom Client gesendeten Ereignisnamen übereinstimmen.
ParameterNames	Die Parameternamensliste des Ereignisses. Die Länge der Liste sollte mit dem vom Client gesendeten Ereignis konsistent sein. Der Name verwendet die Bindungsausdrücke und den Zugriff von context.bindings.<name>.

Python-Modell v2

Funktionstrigger für Socket-Verbindungsereignis.

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

Funktionstrigger für mit Socket verbundenes Ereignis.

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

Funktionstrigger für von Socket getrenntes Ereignis.

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

Funktionstrigger für normale Nachrichten von Clients.

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

Funktionstrigger für normale Nachrichten mit Rückruf.

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

Anmerkung

Eigenschaft	Beschreibung
arg_name	Der Variablename des Arguments in der Funktion, um die Triggerbindung darzustellen.
type	Muss gleich socketiotrigger sein.
hub	Der Hubname, mit dem ein Client eine Verbindung herstellen muss.
data_type	Muss gleich DataType.STRING sein.
Namespace	Der Namespace des Sockets. Standard: „/“
eventName	Der Ereignisname, den die Funktion auslöst. Einige Ereignisnamen sind vordefiniert: connect für Socket-Verbindungsereignis. connected für mit Socket verbundenes Ereignis. disconnected für von Socket getrenntes Ereignis. Andere Ereignisse werden von Benutzer*innen definiert und müssen mit dem vom Client gesendeten Ereignisnamen übereinstimmen.

Anforderung der Eingabebindung

Die Datenstruktur der Eingabebindungsargumente variiert je nach Nachrichtentyp.

Verbinden

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

Eigenschaft	Beschreibung
Namespace	Der Namespace des Sockets.
socketId	Die eindeutige Identität des Sockets.
claims	Der Anspruch von JWT der Clientverbindung. Beachten Sie, dass es nicht das JWT ist, wenn der Dienst die Funktion anfordert, sondern das JWT, wenn der Engine.IO-Client eine Verbindung mit dem Dienst herstellt.
Abfrage	Die Abfrage der Clientverbindung. Beachten Sie, dass es nicht die Abfrage ist, wenn der Dienst die Funktion anfordert, sondern die Abfrage, wenn der Engine.IO-Client eine Verbindung mit dem Dienst herstellt.
headers	Die Header der Clientverbindung. Beachten Sie, dass es nicht die Header sind, wenn der Dienst die Funktion anfordert, sondern die Header, wenn der Engine.IO-Client eine Verbindung mit dem Dienst herstellt.
clientCertificates	Das Clientzertifikat, wenn es aktiviert ist

Verbunden

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

Eigenschaft	Beschreibung
Namespace	Der Namespace des Sockets.
socketId	Die eindeutige Identität des Sockets.

Getrennt

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

Eigenschaft	Beschreibung
Namespace	Der Namespace des Sockets.
socketId	Die eindeutige Identität des Sockets.
reason	Die Beschreibung des Grundes für das Schließen der Verbindung.

Normale Ereignisse

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

Eigenschaft	Beschreibung
Namespace	Der Namespace des Sockets.
socketId	Die eindeutige Identität des Sockets.
payload	Die Nachrichtennutzdaten im Engine.IO-Protokoll
eventName	Der Ereignisname der Anforderung.
parameters	Liste der Parameter der Nachricht.

Ausgabebindung

Die Ausgabebindung unterstützt derzeit die folgenden Funktionalitäten:

• Hinzufügen eines Sockets zu einem Raum
• Entfernen eines Sockets von einem Raum
• Senden von Nachrichten an ein Socket
• Senden von Nachrichten an einen Raum
• Senden von Nachrichten an einen Namespace
• Trennen von Sockets

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

attribute

Das Attribut für die Eingabebindung lautet [SocketIO].

Attributeigenschaft	Beschreibung
Hub	Der Hubname, mit dem ein Client eine Verbindung herstellen muss.
Verbindung	Der Name der App-Einstellung, die die Socket.IO Verbindungszeichenfolge enthält (Standardwert ist WebPubSubForSocketIOConnectionString).

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

Konfiguration

Attributeigenschaft	BESCHREIBUNG
type	Muss gleich socketio sein.
hub	Der Hubname, mit dem ein Client eine Verbindung herstellen muss.
Verbindung	Der Name der App-Einstellung, die die Socket.IO Verbindungszeichenfolge enthält (Standardwert ist WebPubSubForSocketIOConnectionString).

Python-Modell v2

Eine Funktion benötigt immer eine Triggerbindung. Der TimerTrigger wird als Beispiel in Codes verwendet.

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

Anmerkung

Attributeigenschaft	Beschreibung
arg_name	Der Variablename des Arguments in der Funktion, das die Ausgabebindung darstellt.
type	Muss gleich socketio sein.
data_type	Verwenden Sie DataType.STRING
hub	Der Hubname, mit dem ein Client eine Verbindung herstellen muss.
Verbindung	Der Name der App-Einstellung, die die Socket.IO Verbindungszeichenfolge enthält (Standardwert ist WebPubSubForSocketIOConnectionString).

Aktionen

Die Ausgabebindung verwendet Aktionen zum Ausführen von Vorgängen. Derzeit werden die folgenden Aktionen unterstützt:

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
}