Socket.IO wyzwalacz i powiązanie funkcji platformy Azure (wersja zapoznawcza)

W tym artykule wyjaśniono, jak używać Socket.IO integracji bezserwerowej z usługą Azure Functions.

Akcja	Typ powiązania
Uzyskiwanie wyniku negocjowania klienta, w tym adresu URL i tokenu dostępu	Powiązanie wejściowe
Wyzwalane przez komunikaty z usługi	Powiązanie wyzwalacza
Wywoływanie usługi w celu wysyłania komunikatów lub zarządzania klientami	Powiązanie wyjściowe

Dokumentacja interfejsu API | pakietu | źródłowego | — dokumentacja | produktu — przykłady

Ważne

Powiązania funkcji platformy Azure można zintegrować tylko z usługą Web PubSub dla Socket.IO w trybie bezserwerowym.

Uwierzytelnianie i parametry połączenia

Aby umożliwić rozszerzenie pracy z usługą Web PubSub dla Socket.IO, należy podać klucze dostępu lub konfigurację opartą na tożsamości, aby uwierzytelnić się w usłudze.

Konfiguracja oparta na kluczach dostępu

Nazwa konfiguracji	opis
WebPubSubForSocketIOConnectionString	Wymagany. Parametry połączenia oparte na kluczach w usłudze

Parametry połączenia można znaleźć w bloku Klucze w witrynie Web PubSub dla Socket.IO w witrynie Azure Portal.

W przypadku programowania lokalnego local.settings.json użyj pliku do przechowywania parametry połączenia. Ustaw WebPubSubForSocketIOConnectionString wartość parametry połączenia skopiowaną z poprzedniego kroku:

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

Po wdrożeniu użyj ustawień aplikacji, aby ustawić parametry połączenia.

Konfiguracja oparta na tożsamościach

Nazwa konfiguracji	opis
WebPubSubForSocketIOConnectionString__endpoint	Wymagany. Punkt końcowy usługi. Na przykład https://mysocketio.webpubsub.azure.com
WebPubSubForSocketIOConnectionString__credential	Definiuje sposób uzyskiwania tokenu dla połączenia. To ustawienie powinno być ustawione na managedidentity wartość , jeśli wdrożona funkcja platformy Azure zamierza używać uwierzytelniania tożsamości zarządzanej. Ta wartość jest prawidłowa tylko wtedy, gdy tożsamość zarządzana jest dostępna w środowisku hostingu.
WebPubSubForSocketIOConnectionString__clientId	Gdy credential jest ustawiona managedidentitywartość , tę właściwość można ustawić, aby określić tożsamość przypisaną przez użytkownika do użycia podczas uzyskiwania tokenu. Właściwość akceptuje identyfikator klienta odpowiadający tożsamości przypisanej przez użytkownika do aplikacji. Jeśli nie zostanie określona, zostanie użyta tożsamość przypisana przez system.

Powiązanie funkcji jest zgodne z typowymi właściwościami konfiguracji opartej na tożsamościach. Zobacz Typowe właściwości połączeń opartych na tożsamościach, aby uzyskać więcej właściwości, o których mowa.

W przypadku programowania lokalnego local.settings.json użyj pliku do przechowywania parametry połączenia. Ustaw WebPubSubForSocketIOConnectionString wartość parametry połączenia skopiowaną z poprzedniego kroku:

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

Jeśli chcesz używać konfiguracji opartej na tożsamościach i uruchamiać ją w trybie online, AzureWebJobsStorage zapoznaj się z artykułem Łączenie z magazynem hostów z tożsamością.

Powiązanie wejściowe

Socket.IO powiązanie wejściowe generuje SocketIONegotiationResult element do żądania negocjacji klienta. Gdy klient Socket.IO próbuje nawiązać połączenie z usługą, musi znać endpointelement , pathi access token na potrzeby uwierzytelniania. Typowym rozwiązaniem jest utworzenie serwera w celu wygenerowania tych danych, nazywanego negocjacjami.

C#

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

Atrybut

Atrybut powiązania wejściowego to [SocketIONegotiation].

Właściwość atrybutu	opis
Piasta	Nazwa centrum, z którą klient musi nawiązać połączenie.
Connection	Nazwa ustawienia aplikacji, które zawiera Socket.IO parametry połączenia (wartość domyślna to WebPubSubForSocketIOConnectionString).
Identyfikator użytkownika	UserId połączenia. Dotyczy wszystkich gniazd w połączeniu. Staje się oświadczeniem sub w wygenerowanych tokenach.

Model JavaScript w wersji 4

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

Konfigurowanie

Właściwości	Opis
type	Musi być socketionegotiation
kierunek	Musi być in
name	Nazwa zmiennej używana w kodzie funkcji dla obiektu powiązania połączenia wejściowego
koncentrator	Nazwa centrum, z którą klient musi nawiązać połączenie.
połączenie	Nazwa ustawienia aplikacji, które zawiera Socket.IO parametry połączenia (wartość domyślna to WebPubSubForSocketIOConnectionString).
Identyfikator użytkownika	UserId połączenia. Dotyczy wszystkich gniazd w połączeniu. Staje się oświadczeniem sub w wygenerowanych tokenach.

Model języka Python w wersji 2

Funkcja zawsze wymaga powiązania wyzwalacza. Używamy metody HttpTrigger jako przykładu w kodach.

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

Właściwości	opis
arg_name	Nazwa zmiennej argumentu w funkcji reprezentująca powiązanie wejściowe.
type	Musi być socketionegotiation
koncentrator	Nazwa centrum, z którą klient musi nawiązać połączenie.
połączenie	Nazwa ustawienia aplikacji, które zawiera Socket.IO parametry połączenia (wartość domyślna to WebPubSubForSocketIOConnectionString).
Identyfikator użytkownika	UserId połączenia. Dotyczy wszystkich gniazd w połączeniu. Staje się oświadczeniem sub w wygenerowanych tokenach.

Powiązanie wyzwalacza

Funkcja platformy Azure używa powiązania wyzwalacza, aby wyzwolić funkcję w celu przetworzenia zdarzeń z usługi Web PubSub dla Socket.IO.

Powiązanie wyzwalacza uwidacznia określoną ścieżkę po punkcie końcowym funkcji platformy Azure. Adres URL powinien być ustawiony jako szablon adresu URL usługi (portal: ustawienia —> procedura obsługi zdarzeń —> szablon adresu URL). We wzorcu punktu końcowego część code=<API_KEY> zapytania jest wymagana , gdy używasz aplikacji funkcji platformy Azure ze względów bezpieczeństwa . Klucz można znaleźć w witrynie Azure Portal. Znajdź zasób aplikacji funkcji i przejdź do pozycji Funkcje -Klucze aplikacji ->>Klucze systemowe ->socketio_extension po wdrożeniu aplikacji funkcji na platformie Azure. Jednak ten klucz nie jest potrzebny podczas pracy z funkcjami lokalnymi.

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

C#

Wyzwalacze funkcji dla zdarzenia połączenia gniazda.

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

Wyzwalacze funkcji dla zdarzenia połączonego z gniazdem.

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

Wyzwalacze funkcji dla zdarzenia rozłączenia gniazda.

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

Wyzwalacze funkcji dla normalnych komunikatów od klientów.

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

Atrybuty

Atrybut powiązania wyzwalacza to [SocketIOTrigger].

Właściwość atrybutu	opis
Piasta	Nazwa centrum, z którą klient musi nawiązać połączenie.
Przestrzeń nazw	Przestrzeń nazw gniazda. Ustawienie domyślne: "/"
EventName	Nazwa zdarzenia wyzwalana przez funkcję. Niektóre nazwy zdarzeń są wstępnie zdefiniowane: connect dla zdarzenia połączenia gniazda. connected dla zdarzenia połączonego gniazda. disconnected dla zdarzenia odłączonego gniazda. Inne zdarzenia są definiowane przez użytkownika i muszą być zgodne z nazwą zdarzenia wysyłanego przez klienta.
Nazwa parametrów	Lista nazw parametrów zdarzenia. Długość listy powinna być zgodna ze zdarzeniem wysyłanym z klienta. Nazwa używa wyrażeń powiązania i dostępu za pomocą parametru funkcji o tej samej nazwie.

Wiązanie danych

[SocketIOTrigger] wiąże niektóre zmienne z danymi powiązania. Aby dowiedzieć się więcej na ten temat, zobacz Wzorce wyrażeń powiązań usługi Azure Functions

SocketIOAttribute

SocketIOAttribute jest alternatywą funkcji ParameterNames, która upraszcza definicję funkcji. Na przykład następujące dwie definicje mają taki sam efekt:

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

Należy pamiętać, że ParameterNames i [SocketIOParameter] nie można ich używać razem.

Model JavaScript w wersji 4

Wyzwalacze funkcji dla zdarzenia połączenia gniazda.

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

Wyzwalacze funkcji dla zdarzenia połączonego z gniazdem.

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

Wyzwalacze funkcji dla zdarzenia rozłączonego gniazda.

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

Wyzwalacze funkcji dla normalnych komunikatów od klientów.

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

Konfigurowanie

Właściwości	Opis
type	Musi być socketiotrigger
koncentrator	Nazwa centrum, z którą klient musi nawiązać połączenie.
namespace	Przestrzeń nazw gniazda. Ustawienie domyślne: "/"
eventName	Nazwa zdarzenia wyzwalana przez funkcję. Niektóre nazwy zdarzeń są wstępnie zdefiniowane: connect dla zdarzenia połączenia gniazda. connected dla zdarzenia połączonego gniazda. disconnected dla zdarzenia odłączonego gniazda. Inne zdarzenia są definiowane przez użytkownika i muszą być zgodne z nazwą zdarzenia wysyłanego przez klienta.
Nazwa parametrów	Lista nazw parametrów zdarzenia. Długość listy powinna być zgodna ze zdarzeniem wysyłanym z klienta. Nazwa używa wyrażeń powiązania i dostępu za pomocą context.bindings.<name>polecenia .

Model języka Python w wersji 2

Wyzwalacze funkcji dla zdarzenia połączenia gniazda.

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

Wyzwalacze funkcji dla zdarzenia połączonego z gniazdem.

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

Wyzwalacze funkcji dla zdarzenia rozłączonego gniazda.

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

Wyzwalacze funkcji dla normalnych komunikatów od klientów.

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

Wyzwalacz funkcji dla normalnych komunikatów z wywołaniem zwrotnym.

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

Właściwości	opis
arg_name	Nazwa zmiennej argumentu w funkcji reprezentująca powiązanie wyzwalacza.
type	Musi być socketiotrigger
koncentrator	Nazwa centrum, z którą klient musi nawiązać połączenie.
data_type	Musi być DataType.STRING
namespace	Przestrzeń nazw gniazda. Ustawienie domyślne: "/"
eventName	Nazwa zdarzenia wyzwalana przez funkcję. Niektóre nazwy zdarzeń są wstępnie zdefiniowane: connect dla zdarzenia połączenia gniazda. connected dla zdarzenia połączonego gniazda. disconnected dla zdarzenia odłączonego gniazda. Inne zdarzenia są definiowane przez użytkownika i muszą być zgodne z nazwą zdarzenia wysyłanego przez klienta.

Żądanie powiązania wejściowego

Struktura danych argumentów powiązania wejściowego różni się w zależności od typu komunikatu.

Połącz

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

Właściwości	opis
namespace	Przestrzeń nazw gniazda.
socketId	Unikatowa tożsamość gniazda.
oświadczenia	Oświadczenie JWT połączenia klienta. Pamiętaj, że nie jest to JWT, gdy usługa żąda funkcji, ale JWT, gdy klient Engine.IO łączy się z usługą.
zapytanie	Zapytanie dotyczące połączenia klienta. Uwaga: nie jest to zapytanie, gdy usługa żąda funkcji, ale zapytanie, gdy klient Engine.IO łączy się z usługą.
nagłówki	Nagłówki połączenia klienta. Pamiętaj, że nie jest to nagłówki, gdy usługa żąda funkcji, ale nagłówki, gdy klient Engine.IO łączy się z usługą.
clientCertificates	Certyfikat klienta, jeśli jest włączony

Połączono

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

Właściwości	opis
namespace	Przestrzeń nazw gniazda.
socketId	Unikatowa tożsamość gniazda.

Odłączony

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

Właściwości	opis
namespace	Przestrzeń nazw gniazda.
socketId	Unikatowa tożsamość gniazda.
reason	Opis przyczyny zamknięcia połączenia.

Zdarzenia normalne

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

Właściwości	opis
namespace	Przestrzeń nazw gniazda.
socketId	Unikatowa tożsamość gniazda.
payload	Ładunek komunikatu w protokole Engine.IO
eventName	Nazwa zdarzenia żądania.
parameters	Lista parametrów komunikatu.

Powiązanie wyjściowe

Powiązanie wyjściowe obsługuje obecnie następujące funkcje:

• Dodawanie gniazda do pokoju
• Usuwanie gniazda z pokoju
• Wysyłanie komunikatów do gniazda
• Wysyłanie wiadomości do pokoju
• Wysyłanie komunikatów do przestrzeni nazw
• Odłącz gniazda

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

Atrybut

Atrybut powiązania wejściowego to [SocketIO].

Właściwość atrybutu	opis
Piasta	Nazwa centrum, z którą klient musi nawiązać połączenie.
Connection	Nazwa ustawienia aplikacji, które zawiera Socket.IO parametry połączenia (wartość domyślna to WebPubSubForSocketIOConnectionString).

Model JavaScript w wersji 4

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

Konfigurowanie

Właściwość atrybutu	opis
type	Musi być socketio
koncentrator	Nazwa centrum, z którą klient musi nawiązać połączenie.
połączenie	Nazwa ustawienia aplikacji, które zawiera Socket.IO parametry połączenia (wartość domyślna to WebPubSubForSocketIOConnectionString).

Model języka Python w wersji 2

Funkcja zawsze wymaga powiązania wyzwalacza. Jako przykład w kodach używamy elementu TimerTrigger.

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

Właściwość atrybutu	opis
arg_name	Nazwa zmiennej argumentu w funkcji reprezentująca powiązanie wyjściowe.
type	Musi być socketio
data_type	Korzystanie z polecenia DataType.STRING
koncentrator	Nazwa centrum, z którą klient musi nawiązać połączenie.
połączenie	Nazwa ustawienia aplikacji, które zawiera Socket.IO parametry połączenia (wartość domyślna to WebPubSubForSocketIOConnectionString).

Akcje

Powiązanie wyjściowe używa akcji do wykonywania operacji. Obecnie obsługujemy następujące akcje:

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
}