Socket.IO Azure Function-trigger en -binding (preview)

In dit artikel wordt uitgelegd hoe u Socket.IO serverloze integratie kunt gebruiken met Azure Functions.

Actie	Bindingstype
Resultaat van clientonderhandeling ophalen, inclusief URL en toegangstoken	Invoerbinding
Geactiveerd door berichten van de service	Triggerbinding
Service aanroepen om berichten te verzenden of clients te beheren	Uitvoerbinding

Voorbeelden van productdocumentatie over broncodepakket-API-referentiedocumentatie | | | |

Belangrijk

Azure Function-bindingen kunnen alleen worden geïntegreerd met Web PubSub voor Socket.IO in de serverloze modus.

Verificatie en verbindingsreeks

Als u de extensie wilt laten werken met Web PubSub voor Socket.IO, moet u toegangssleutels of op identiteit gebaseerde configuratie opgeven om te verifiëren met de service.

Configuratie op basis van toegangssleutel

Configuratienaam	Beschrijving
WebPubSubForSocketIOConnectionString	Vereist. Sleutelgebaseerde verbindingsreeks naar de service

U vindt de verbindingsreeks in de blade Sleutels in uw Web PubSub voor Socket.IO in Azure Portal.

Gebruik het local.settings.json bestand voor de lokale ontwikkeling om de verbindingsreeks op te slaan. Ingesteld WebPubSubForSocketIOConnectionString op het verbindingsreeks gekopieerd uit de vorige stap:

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

Wanneer deze is geïmplementeerd, gebruikt u de toepassingsinstellingen om de verbindingsreeks in te stellen.

Configuratie op basis van identiteit

Configuratienaam	Beschrijving
WebPubSubForSocketIOConnectionString__endpoint	Vereist. Het eindpunt van de service. Bijvoorbeeld https://mysocketio.webpubsub.azure.com
WebPubSubForSocketIOConnectionString__credential	Hiermee definieert u hoe een token moet worden verkregen voor de verbinding. Deze instelling moet worden ingesteld managedidentity op als uw geïmplementeerde Azure-functie van plan is om verificatie van beheerde identiteiten te gebruiken. Deze waarde is alleen geldig wanneer een beheerde identiteit beschikbaar is in de hostingomgeving.
WebPubSubForSocketIOConnectionString__clientId	Wanneer credential deze eigenschap is ingesteld managedidentityop, kan deze eigenschap worden ingesteld om de door de gebruiker toegewezen identiteit op te geven die moet worden gebruikt bij het verkrijgen van een token. De eigenschap accepteert een client-id die overeenkomt met een door de gebruiker toegewezen identiteit die aan de toepassing is toegewezen. Als dit niet is opgegeven, wordt de door het systeem toegewezen identiteit gebruikt.

De functiebinding volgt de algemene eigenschappen voor configuratie op basis van identiteiten. Zie Algemene eigenschappen voor op identiteit gebaseerde verbindingen voor meer niet-gementeerde eigenschappen.

Gebruik het local.settings.json bestand voor de lokale ontwikkeling om de verbindingsreeks op te slaan. Ingesteld WebPubSubForSocketIOConnectionString op het verbindingsreeks gekopieerd uit de vorige stap:

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

Als u configuratie op basis van identiteiten wilt gebruiken en online wilt uitvoeren, AzureWebJobsStorage raadpleegt u Verbinding maken met hostopslag met een identiteit.

Invoerbinding

Socket.IO invoerbinding genereert een SocketIONegotiationResult aanvraag voor clientonderhandeling. Wanneer een Socket.IO-client verbinding probeert te maken met de service, moet deze de endpoint, pathen access token voor verificatie weten. Het is gebruikelijk om een server te hebben om deze gegevens te genereren. Dit wordt onderhandeling genoemd.

C#

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

Kenmerk

Het kenmerk voor invoerbinding is [SocketIONegotiation].

Kenmerkeigenschap	Beschrijving
Hub	De hubnaam waarmee een client verbinding moet maken.
Connection	De naam van de app-instelling die de Socket.IO verbindingsreeks bevat (standaard ingesteld opWebPubSubForSocketIOConnectionString).
Gebruikers-id	De gebruikers-id van de verbinding. Dit geldt voor alle sockets in de verbinding. Het wordt de sub claim in het gegenereerde token.

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

Configuratie

Eigenschappen	Beschrijving
type	Moet socketionegotiation zijn
richting	Moet in zijn
naam	Variabelenaam die wordt gebruikt in functiecode voor bindingsobject voor invoerverbinding
naaf	De hubnaam waarmee een client verbinding moet maken.
verbinding	De naam van de app-instelling die de Socket.IO verbindingsreeks bevat (standaard ingesteld opWebPubSubForSocketIOConnectionString).
userId	De gebruikers-id van de verbinding. Dit geldt voor alle sockets in de verbinding. Het wordt de sub claim in het gegenereerde token.

Python Model v2

Een functie heeft altijd een triggerbinding nodig. We gebruiken HttpTrigger als voorbeeld 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)

Aantekening

Eigenschappen	Beschrijving
arg_name	De variabelenaam van het argument in de functie die de invoerbinding vertegenwoordigt.
type	Moet socketionegotiation zijn
naaf	De hubnaam waarmee een client verbinding moet maken.
verbinding	De naam van de app-instelling die de Socket.IO verbindingsreeks bevat (standaard ingesteld opWebPubSubForSocketIOConnectionString).
userId	De gebruikers-id van de verbinding. Dit geldt voor alle sockets in de verbinding. Het wordt de sub claim in het gegenereerde token.

Triggerbinding

Azure Function maakt gebruik van triggerbinding om een functie te activeren om de gebeurtenissen van de Web PubSub voor Socket.IO te verwerken.

Met triggerbinding wordt een specifiek pad weergegeven, gevolgd door het Azure Function-eindpunt. De URL moet worden ingesteld als de URL-sjabloon van de service (Portal: instellingen -> gebeurtenis-handler -> URL-sjabloon). In het eindpuntpatroon is het queryonderdeel code=<API_KEY> VEREIST wanneer u Azure Function App gebruikt om beveiligingsredenen. De sleutel vindt u in Azure Portal. Zoek uw functie-app-resource en navigeer naar Functions ->App-sleutels ->Systeemsleutels ->socketio_extension nadat u de functie-app in Azure hebt geïmplementeerd. Deze sleutel is echter niet nodig wanneer u met lokale functies werkt.

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

C#

Functietriggers voor de gebeurtenis socketverbinding.

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

Functietriggers voor socket-verbonden gebeurtenis.

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

Functietriggers voor de gebeurtenis socket-verbinding verbreken.

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

Functietriggers voor normale berichten van clients.

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

Kenmerken

Het kenmerk voor triggerbinding is [SocketIOTrigger].

Kenmerkeigenschap	Beschrijving
Hub	De hubnaam waarmee een client verbinding moet maken.
Naamruimte	De naamruimte van de socket. Standaard: "/"
EventName	De gebeurtenisnaam waarvoor de functie wordt geactiveerd. Sommige gebeurtenisnamen zijn vooraf gedefinieerd: connect voor socketverbindingsgebeurtenis. connected voor een verbonden socket-gebeurtenis. disconnected voor de niet-verbonden socketgebeurtenis. Andere gebeurtenissen worden gedefinieerd door de gebruiker en moeten overeenkomen met de gebeurtenisnaam die door de client wordt verzonden.
ParameterNames	De lijst met parameternamen van de gebeurtenis. De lengte van de lijst moet consistent zijn met de gebeurtenis die vanaf de client wordt verzonden. En de naam maakt gebruik van de bindingexpressies en toegang met dezelfde functieparameter.

Bindingsgegevens

[SocketIOTrigger] verbindt enkele variabelen met bindingsgegevens. Meer informatie hierover vindt u in bindingspatronen van Azure Functions

SocketIOAttribute

SocketIOAttribute is een alternatief van ParameterNames, waarmee de functiedefinitie wordt vereenvoudigd. De volgende twee definities hebben bijvoorbeeld hetzelfde effect:

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

Houd er rekening mee dat ParameterNames en [SocketIOParameter] niet samen kan worden gebruikt.

JavaScript Model v4

Functietriggers voor de gebeurtenis socketverbinding.

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

Functietriggers voor socket-verbonden gebeurtenis.

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

Functietriggers voor een niet-verbonden socketgebeurtenis.

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

Functietriggers voor normale berichten van 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
});

Configuratie

Eigenschappen	Beschrijving
type	Moet socketiotrigger zijn
naaf	De hubnaam waarmee een client verbinding moet maken.
naamruimte	De naamruimte van de socket. Standaard: "/"
eventName	De gebeurtenisnaam waarvoor de functie wordt geactiveerd. Sommige gebeurtenisnamen zijn vooraf gedefinieerd: connect voor socketverbindingsgebeurtenis. connected voor een verbonden socket-gebeurtenis. disconnected voor de niet-verbonden socketgebeurtenis. Andere gebeurtenissen worden gedefinieerd door de gebruiker en moeten overeenkomen met de gebeurtenisnaam die door de client wordt verzonden.
ParameterNames	De lijst met parameternamen van de gebeurtenis. De lengte van de lijst moet consistent zijn met de gebeurtenis die vanaf de client wordt verzonden. En de naam maakt gebruik van bindingexpressies en toegang doorcontext.bindings.<name>.

Python Model v2

Functietriggers voor de gebeurtenis socketverbinding.

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

Functietriggers voor socket-verbonden gebeurtenis.

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

Functietriggers voor een niet-verbonden socketgebeurtenis.

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

Functietriggers voor normale berichten van 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

Functietrigger voor normale berichten met 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"]})

Aantekening

Eigenschappen	Beschrijving
arg_name	De variabelenaam van het argument in de functie die de triggerbinding vertegenwoordigt.
type	Moet socketiotrigger zijn
naaf	De hubnaam waarmee een client verbinding moet maken.
data_type	Moet DataType.STRING zijn
naamruimte	De naamruimte van de socket. Standaard: "/"
eventName	De gebeurtenisnaam waarvoor de functie wordt geactiveerd. Sommige gebeurtenisnamen zijn vooraf gedefinieerd: connect voor socketverbindingsgebeurtenis. connected voor een verbonden socket-gebeurtenis. disconnected voor de niet-verbonden socketgebeurtenis. Andere gebeurtenissen worden gedefinieerd door de gebruiker en moeten overeenkomen met de gebeurtenisnaam die door de client wordt verzonden.

Aanvraag van invoerbinding

De gegevensstructuur van invoerbindingargumenten varieert afhankelijk van het berichttype.

Verbinden

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

Eigenschappen	Beschrijving
naamruimte	De naamruimte van de socket.
socketId	De unieke identiteit van de socket.
claims	De claim van JWT van de clientverbinding. Opmerking: dit is niet de JWT wanneer de service de functie aanvraagt, maar de JWT wanneer de Engine.IO-client verbinding maakt met de service.
query	De query van de clientverbinding. Opmerking: dit is niet de query wanneer de service de functie aanvraagt, maar de query wanneer de Engine.IO-client verbinding maakt met de service.
headers	De headers van de clientverbinding. Opmerking: dit zijn niet de headers wanneer de service de functie aanvraagt, maar de headers wanneer de Engine.IO client verbinding maakt met de service.
clientCertificates	Het clientcertificaat als dit is ingeschakeld

Connected

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

Eigenschappen	Beschrijving
naamruimte	De naamruimte van de socket.
socketId	De unieke identiteit van de socket.

Ontkoppeld

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

Eigenschappen	Beschrijving
naamruimte	De naamruimte van de socket.
socketId	De unieke identiteit van de socket.
reason	De beschrijving van de reden van de verbinding sluiten.

Normale gebeurtenissen

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

Eigenschappen	Beschrijving
naamruimte	De naamruimte van de socket.
socketId	De unieke identiteit van de socket.
nettolading	De nettolading van het bericht in Engine.IO protocol
eventName	De gebeurtenisnaam van de aanvraag.
parameters	Lijst met parameters van het bericht.

Uitvoerbinding

De uitvoerbinding ondersteunt momenteel de volgende functionaliteit:

• Een socket toevoegen aan ruimte
• Een socket uit de ruimte verwijderen
• Berichten verzenden naar een socket
• Berichten verzenden naar een ruimte
• Berichten verzenden naar een naamruimte
• Sockets loskoppelen

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

Kenmerk

Het kenmerk voor invoerbinding is [SocketIO].

Kenmerkeigenschap	Beschrijving
Hub	De hubnaam waarmee een client verbinding moet maken.
Connection	De naam van de app-instelling die de Socket.IO verbindingsreeks bevat (standaard ingesteld opWebPubSubForSocketIOConnectionString).

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

Configuratie

Kenmerkeigenschap	Beschrijving
type	Moet socketio zijn
naaf	De hubnaam waarmee een client verbinding moet maken.
verbinding	De naam van de app-instelling die de Socket.IO verbindingsreeks bevat (standaard ingesteld opWebPubSubForSocketIOConnectionString).

Python Model v2

Een functie heeft altijd een triggerbinding nodig. We gebruiken TimerTrigger als voorbeeld in codes.

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

Aantekening

Kenmerkeigenschap	Beschrijving
arg_name	De variabelenaam van het argument in de functie die de uitvoerbinding vertegenwoordigt.
type	Moet socketio zijn
data_type	DataType.STRING gebruiken
naaf	De hubnaam waarmee een client verbinding moet maken.
verbinding	De naam van de app-instelling die de Socket.IO verbindingsreeks bevat (standaard ingesteld opWebPubSubForSocketIOConnectionString).

Acties

Uitvoerbinding maakt gebruik van acties om bewerkingen uit te voeren. Momenteel ondersteunen we de volgende acties:

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
}