Socket.IO azure-funktionsutlösare och bindning (förhandsversion)

Den här artikeln beskriver hur du använder Socket.IO serverlös integrering med Azure Functions.

Åtgärd	Bindningstyp
Get client negotiate result including url and access token	Indatabindning
Utlöses av meddelanden från tjänsten	Utlösarbindning
Anropa tjänsten för att skicka meddelanden eller hantera klienter	Utdatabindning

Referensdokumentation | för källkodspaketets | API-referens Produktdokumentation | – exempel |

Viktigt!

Azure-funktionsbindningar kan bara integreras med Web PubSub för Socket.IO i serverlöst läge.

Autentisera och anslutningssträng

För att tillägget ska fungera med Web PubSub för Socket.IO måste du ange antingen åtkomstnycklar eller identitetsbaserad konfiguration för att autentisera med tjänsten.

Åtkomstnyckelbaserad konfiguration

Konfigurationsnamn	beskrivning
WebPubSubForSocketIOConnectionString	Obligatoriskt. Nyckelbaserad anslutningssträng till tjänsten

Du hittar anslutningssträng i bladet Nycklar i webbpubenSub för Socket.IO i Azure Portal.

För den lokala utvecklingen använder du local.settings.json filen för att lagra anslutningssträng. Ange WebPubSubForSocketIOConnectionString till den anslutningssträng kopierade från föregående steg:

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

När du distribuerar använder du programinställningarna för att ange anslutningssträng.

Identitetsbaserad konfiguration

Konfigurationsnamn	beskrivning
WebPubSubForSocketIOConnectionString__endpoint	Obligatoriskt. Tjänstens slutpunkt. Till exempel: https://mysocketio.webpubsub.azure.com
WebPubSubForSocketIOConnectionString__credential	Definierar hur en token ska hämtas för anslutningen. Den här inställningen ska anges till managedidentity om din distribuerade Azure-funktion avser att använda hanterad identitetsautentisering. Det här värdet är endast giltigt när en hanterad identitet är tillgänglig i värdmiljön.
WebPubSubForSocketIOConnectionString__clientId	När credential är inställt på managedidentitykan den här egenskapen anges för att ange den användartilldelade identitet som ska användas när du hämtar en token. Egenskapen accepterar ett klient-ID som motsvarar en användartilldelad identitet som tilldelats programmet. Om det inte anges används den systemtilldelade identiteten.

Funktionsbindningen följer de vanliga egenskaperna för identitetsbaserad konfiguration. Mer obemärkta egenskaper finns i Vanliga egenskaper för identitetsbaserade anslutningar.

För den lokala utvecklingen använder du local.settings.json filen för att lagra anslutningssträng. Ange WebPubSubForSocketIOConnectionString till den anslutningssträng kopierade från föregående steg:

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

Om du vill använda identitetsbaserad konfiguration och köra online AzureWebJobsStorage bör du läsa Ansluta till värdlagring med en identitet.

Indatabindning

Socket.IO Indatabindning genererar en SocketIONegotiationResult till klientförhandlingsbegäran. När en Socket.IO-klient försöker ansluta till tjänsten måste den endpointkänna till , pathoch access token för autentisering. Det är vanligt att ha en server för att generera dessa data, vilket kallas förhandling.

C#

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

Attribut

Attributet för indatabindning är [SocketIONegotiation].

Attributegenskap	beskrivning
Hubb	Hubbnamnet som en klient behöver ansluta till.
Connection	Namnet på appinställningen som innehåller Socket.IO anslutningssträng (standardvärdet är WebPubSubForSocketIOConnectionString).
AnvändarID	UserId för anslutningen. Det gäller för alla socketar i anslutningen. Det blir anspråket sub i den genererade 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

Property	Beskrivning
type	Måste vara socketionegotiation
riktning	Måste vara in
name	Variabelnamn som används i funktionskoden för indataanslutningsbindningsobjekt
nav	Hubbnamnet som en klient behöver ansluta till.
anslutning	Namnet på appinställningen som innehåller Socket.IO anslutningssträng (standardvärdet är WebPubSubForSocketIOConnectionString).
Användar-ID	UserId för anslutningen. Det gäller för alla socketar i anslutningen. Det blir anspråket sub i den genererade token.

Python Model v2

En funktion behöver alltid en utlösarbindning. Vi använder HttpTrigger som exempel i koder.

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)

Annotation

Property	beskrivning
arg_name	Variabelnamnet för argumentet i funktionen för att representera indatabindningen.
type	Måste vara socketionegotiation
nav	Hubbnamnet som en klient behöver ansluta till.
anslutning	Namnet på appinställningen som innehåller Socket.IO anslutningssträng (standardvärdet är WebPubSubForSocketIOConnectionString).
Användar-ID	UserId för anslutningen. Det gäller för alla socketar i anslutningen. Det blir anspråket sub i den genererade token.

Utlösarbindning

Azure Function använder utlösarbindning för att utlösa en funktion för att bearbeta händelserna från Web PubSub för Socket.IO.

Utlösarbindning exponerar en specifik sökväg följt av Azure Function-slutpunkten. Url:en ska anges som URL-mall för tjänsten (Portal: inställningar –> händelsehanterare –> URL-mall). I slutpunktsmönstret krävsfrågedelen code=<API_KEY> när du använder Azure-funktionsappen av säkerhetsskäl. Nyckeln finns i Azure Portal. Leta reda på funktionsappens resurs och gå till Functions ->App keys ->System keys ->socketio_extension när du har distribuerat funktionsappen till Azure. Den här nyckeln behövs dock inte när du arbetar med lokala funktioner.

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

C#

Funktionsutlösare för socket connect-händelse.

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

Funktionsutlösare för socketansluten händelse.

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

Funktionsutlösare för socket-frånkopplingshändelse.

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

Funktionsutlösare för normala meddelanden från klienter.

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

Attribut

Attributet för utlösarbindning är [SocketIOTrigger].

Attributegenskap	beskrivning
Hubb	Hubbnamnet som en klient behöver ansluta till.
Namnområde	Socketens namnområde. Standard: "/"
EventName	Händelsenamnet som funktionen utlöser för. Vissa händelsenamn är fördefinierade: connect för socket connect-händelse. connected för socketansluten händelse. disconnected för socket frånkopplad händelse. Och andra händelser definieras av användaren och måste matcha händelsenamnet som skickas av klientsidan.
ParameterNames	Parameternamnets lista över händelsen. Listans längd bör vara konsekvent med händelsen som skickas från klienten. Och namnet använder bindningsuttrycken och åtkomsten av funktionsparametern med samma namn.

Bindningsdata

[SocketIOTrigger] binder vissa variabler till bindningsdata. Du kan lära dig mer om det från mönster för Bindningsuttryck i Azure Functions

SocketIOAttribute

SocketIOAttribute är ett alternativ till ParameterNames, vilket förenklar funktionsdefinitionen. Följande två definitioner har till exempel samma effekt:

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

Observera att ParameterNames och [SocketIOParameter] inte kan användas tillsammans.

JavaScript-modell v4

Funktionsutlösare för socket connect-händelse.

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

Funktionsutlösare för socketansluten händelse.

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

Funktionsutlösare för socket-frånkopplad händelse.

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

Funktionsutlösare för normala meddelanden från klienter.

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

Property	Beskrivning
type	Måste vara socketiotrigger
nav	Hubbnamnet som en klient behöver ansluta till.
namnområde	Socketens namnområde. Standard: "/"
eventName	Händelsenamnet som funktionen utlöser för. Vissa händelsenamn är fördefinierade: connect för socket connect-händelse. connected för socketansluten händelse. disconnected för socket frånkopplad händelse. Och andra händelser definieras av användaren och måste matcha händelsenamnet som skickas av klientsidan.
ParameterNames	Parameternamnets lista över händelsen. Listans längd bör vara konsekvent med händelsen som skickas från klienten. Och namnet använder bindningsuttrycken och åtkomsten av context.bindings.<name>.

Python Model v2

Funktionsutlösare för socket connect-händelse.

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

Funktionsutlösare för socketansluten händelse.

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

Funktionsutlösare för socket-frånkopplad händelse.

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

Funktionsutlösare för normala meddelanden från klienter.

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

Funktionsutlösare för normala meddelanden med återanrop.

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

Annotation

Property	beskrivning
arg_name	Variabelnamnet för argumentet i funktionen för att representera utlösarbindningen.
type	Måste vara socketiotrigger
nav	Hubbnamnet som en klient behöver ansluta till.
data_type	Måste vara DataType.STRING
namnområde	Socketens namnområde. Standard: "/"
eventName	Händelsenamnet som funktionen utlöser för. Vissa händelsenamn är fördefinierade: connect för socket connect-händelse. connected för socketansluten händelse. disconnected för socket frånkopplad händelse. Och andra händelser definieras av användaren och måste matcha händelsenamnet som skickas av klientsidan.

Begäran om indatabindning

Datastrukturen för indatabindningsargument varierar beroende på meddelandetyp.

Anslut

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

Property	beskrivning
namnområde	Socketens namnområde.
socketId	Socketens unika identitet.
anspråk	Anspråket för JWT för klientanslutningen. Observera att det inte är JWT när tjänsten begär funktionen, utan JWT när Engine.IO-klienten ansluter till tjänsten.
query	Frågan om klientanslutningen. Observera att det inte är frågan när tjänsten begär funktionen, utan frågan när Engine.IO-klienten ansluter till tjänsten.
rubriker	Sidhuvudena för klientanslutningen. Observera att det inte är rubrikerna när tjänsten begär funktionen, utan rubrikerna när Engine.IO-klienten ansluter till tjänsten.
clientCertificates	Klientcertifikatet om det är aktiverat

Connected

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

Property	beskrivning
namnområde	Socketens namnområde.
socketId	Socketens unika identitet.

Frånkopplad

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

Property	beskrivning
namnområde	Socketens namnområde.
socketId	Socketens unika identitet.
orsak	Beskrivning av orsaken till anslutningens stängning.

Normala händelser

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

Property	beskrivning
namnområde	Socketens namnområde.
socketId	Socketens unika identitet.
payload	Meddelandets nyttolast i Engine.IO protokoll
eventName	Begärans händelsenamn.
parametrar	Lista över parametrar för meddelandet.

Utdatabindning

Utdatabindningen stöder för närvarande följande funktioner:

• Lägg till en socket i rummet
• Ta bort en socket från rummet
• Skicka meddelanden till en socket
• Skicka meddelanden till ett rum
• Skicka meddelanden till ett namnområde
• Koppla från 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" }));
}

Attribut

Attributet för indatabindning är [SocketIO].

Attributegenskap	beskrivning
Hubb	Hubbnamnet som en klient behöver ansluta till.
Connection	Namnet på appinställningen som innehåller Socket.IO anslutningssträng (standardvärdet är 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

Attributegenskap	beskrivning
type	Måste vara socketio
nav	Hubbnamnet som en klient behöver ansluta till.
anslutning	Namnet på appinställningen som innehåller Socket.IO anslutningssträng (standardvärdet är WebPubSubForSocketIOConnectionString).

Python Model v2

En funktion behöver alltid en utlösarbindning. Vi använder TimerTrigger som exempel i koder.

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

Annotation

Attributegenskap	beskrivning
arg_name	Variabelnamnet för argumentet i funktionen för att representera utdatabindningen.
type	Måste vara socketio
data_type	Använda DataType.STRING
nav	Hubbnamnet som en klient behöver ansluta till.
anslutning	Namnet på appinställningen som innehåller Socket.IO anslutningssträng (standardvärdet är WebPubSubForSocketIOConnectionString).

Åtgärder

Utdatabindning använder åtgärder för att utföra åtgärder. För närvarande stöder vi följande åtgärder:

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
}