Socket.IO Azure 函式觸發程式和系結 （預覽）

本文說明如何使用 Socket.IO 無伺服器與 Azure Functions 整合。

動作	繫結類型
取得用戶端交涉結果，包括 URL 和存取令牌	輸入繫結
由來自服務的訊息觸發	觸發程序繫結
叫用服務以傳送訊息或管理用戶端	輸出繫結

原始程式碼 | 套件 | API 參考文件 | 產品文件 | 範例

重要

Azure 函式系結只能與無伺服器模式中 Socket.IO 的 Web PubSub 整合。

驗證和連接字串

若要讓擴充功能與 web PubSub for Socket.IO 搭配運作，您必須提供存取密鑰或身分識別型組態，以向服務進行驗證。

存取金鑰型設定

組態名稱	描述
WebPubSubForSocketIOConnectionString	必要。 以金鑰為基礎的服務 連接字串

您可以在 web PubSub 的 [金鑰] 刀鋒視窗中找到 [連接字串]，Azure 入口網站 中 Socket.IO。

針對本機開發，請使用 local.settings.json 檔案來儲存 連接字串。 設定WebPubSubForSocketIOConnectionString為從上一個步驟複製的 連接字串：

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

部署時，請使用應用程式設定來設定 連接字串。

身分識別型設定

組態名稱	描述
WebPubSubForSocketIOConnectionString__endpoint	必要。 服務的端點。 例如，https://mysocketio.webpubsub.azure.com
WebPubSubForSocketIOConnectionString__credential	定義如何為連線取得權杖。 如果您已部署的 Azure 函式想要使用受控識別驗證，則此設定應設定為 managedidentity。 僅在裝載環境中有受控識別可用時，這個值才有效。
WebPubSubForSocketIOConnectionString__clientId	當 credential 設定為 managedidentity 時，可將這個屬性設定為指定在取得權杖時要使用的使用者指派身分識別。 屬性接受的用戶端識別碼，對應至指派給應用程式的使用者指派身分識別。 如果沒有指定，則會使用系統指派的身分識別。

函式系結會遵循身分識別型組態的通用屬性。 如需更多未提及的屬性，請參閱 身分識別型連線 的通用屬性。

針對本機開發，請使用 local.settings.json 檔案來儲存 連接字串。 設定WebPubSubForSocketIOConnectionString為從上一個步驟複製的 連接字串：

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

如果您想要使用身分識別型組態並在在線執行， AzureWebJobsStorage 應該參考 使用身分識別連線到主機記憶體。

輸入繫結

Socket.IO 輸入系結會產生 SocketIONegotiationResult 用戶端交涉要求的 。 當 Socket.IO 客戶端嘗試連線到服務時，它必須知道 endpoint、 path和 access token 以進行驗證。 讓伺服器產生這些數據是常見的做法，這稱為交涉。

C#

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

屬性

輸入系結的屬性為 [SocketIONegotiation]。

屬性內容	描述
中樞	用戶端需要連線的中樞名稱。
連線	包含 Socket.IO 連接字串 的應用程式設定名稱（預設值為WebPubSubForSocketIOConnectionString）。
UserId	連接的userId。 它會套用至連線中的所有套接字。 它會成為 sub 所產生令牌中的宣告。

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

組態

屬性	描述
type	必須是 socketionegotiation
direction	必須是 in
NAME	用於輸入連接系結物件的函式程式代碼中的變數名稱
中樞	用戶端需要連線的中樞名稱。
connection	包含 Socket.IO 連接字串 的應用程式設定名稱（預設值為WebPubSubForSocketIOConnectionString）。
userId	連接的userId。 它會套用至連線中的所有套接字。 它會成為 sub 所產生令牌中的宣告。

Python 模型 v2

函式一律需要觸發程序系結。 我們使用 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)

註釋

屬性	說明
arg_name	函式中要代表輸入系結之自變數的變數名稱。
type	必須是 socketionegotiation
中樞	用戶端需要連線的中樞名稱。
connection	包含 Socket.IO 連接字串 的應用程式設定名稱（預設值為WebPubSubForSocketIOConnectionString）。
userId	連接的userId。 它會套用至連線中的所有套接字。 它會成為 sub 所產生令牌中的宣告。

觸發程式系結

Azure 函式會使用觸發程式系結來觸發函式，以處理來自 Web PubSub 的事件 Socket.IO。

觸發程式系結會公開遵循 Azure 函式端點的特定路徑。 URL 應設定為服務的 URL 範本（入口網站：設定 -> 事件處理程式 -> URL 範本）。 在端點模式中，當您基於安全性考量使用 Azure Function 應用程式時，需要使用查詢組件 code=<API_KEY>。 可以在 Azure 入口網站中找到該金鑰。 尋找函式應用程式資源，並在您將函式應用程式部署至 Azure 之後，流覽至 Functions ->App 金鑰 ->系統金鑰 ->socketio_extension。 不過，當您使用本機函式時，不需要此金鑰。

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

C#

套接字連線事件的函式觸發程式。

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

套接字連線事件的函式觸發程式。

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

套接字中斷連線事件的函式觸發程式。

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

來自用戶端之一般訊息的函式觸發程式。

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

屬性

觸發程式系結的屬性為 [SocketIOTrigger]。

屬性內容	描述
中樞	用戶端需要連線的中樞名稱。
Namespace	套接字的命名空間。 默認值：“/”
EventName	函式觸發的事件名稱。 某些事件名稱已預先定義： connect 適用於套接字連線事件。 connected 適用於套接字連線事件。 disconnected 用於套接字中斷連線的事件。 其他事件是由使用者定義，而且它必須符合用戶端傳送的事件名稱。
ParameterNames	事件的參數名稱清單。 清單長度應該與從用戶端傳送的事件一致。 而且名稱會 使用 Binding 運算式 ，並使用同名函式參數進行存取。

系結數據

[SocketIOTrigger] 將某些變數系結至系結數據。 您可以從 Azure Functions 系結運算式模式深入瞭解它

SocketIOAttribute

SocketIOAttribute 是的 ParameterNames替代方案，可簡化函式定義。 例如，下列兩個定義的效果相同：

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

請注意， ParameterNames 和 [SocketIOParameter] 不能一起使用。

JavaScript 模型 v4

套接字連線事件的函式觸發程式。

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

套接字連線事件的函式觸發程式。

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

套接字中斷連線事件的函式觸發程式。

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

來自用戶端之一般訊息的函式觸發程式。

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

組態

屬性	描述
type	必須是 socketiotrigger
中樞	用戶端需要連線的中樞名稱。
命名空間	套接字的命名空間。 默認值：“/”
eventName	函式觸發的事件名稱。 某些事件名稱已預先定義： connect 適用於套接字連線事件。 connected 適用於套接字連線事件。 disconnected 用於套接字中斷連線的事件。 其他事件是由使用者定義，而且它必須符合用戶端傳送的事件名稱。
ParameterNames	事件的參數名稱清單。 清單長度應該與從用戶端傳送的事件一致。 而且名稱會使用 Binding 運算式 和 存取方式 context.bindings.<name>。

Python 模型 v2

套接字連線事件的函式觸發程式。

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

套接字連線事件的函式觸發程式。

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

套接字中斷連線事件的函式觸發程式。

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

來自用戶端之一般訊息的函式觸發程式。

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

具有回呼之一般訊息的函式觸發程式。

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

註釋

屬性	說明
arg_name	函式中要代表觸發程式系結之自變數的變數名稱。
type	必須是 socketiotrigger
中樞	用戶端需要連線的中樞名稱。
data_type	必須是 DataType.STRING
命名空間	套接字的命名空間。 默認值：“/”
eventName	函式觸發的事件名稱。 某些事件名稱已預先定義： connect 適用於套接字連線事件。 connected 適用於套接字連線事件。 disconnected 用於套接字中斷連線的事件。 其他事件是由使用者定義，而且它必須符合用戶端傳送的事件名稱。

輸入系結的要求

輸入系結自變數的數據結構會根據訊息類型而有所不同。

連線

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

屬性	說明
命名空間	套接字的命名空間。
socketId	套接字的唯一識別。
claims	用戶端連線的 JWT 宣告。 請注意，當服務要求函式時，它不是 JWT，而是當 Engine.IO 用戶端連線到服務時 JWT。
query	用戶端連線的查詢。 請注意，當服務要求函式時，不是查詢，而是當 Engine.IO 用戶端連線至服務時查詢。
標題	用戶端連線的標頭。 請注意，當服務要求函式時，不是標頭，而是當 Engine.IO 用戶端連線至服務時標頭。
clientCertificates	如果客戶端憑證已啟用，則為

Connected

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

屬性	說明
命名空間	套接字的命名空間。
socketId	套接字的唯一識別。

已中斷連線

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

屬性	說明
命名空間	套接字的命名空間。
socketId	套接字的唯一識別。
reason	線上關閉原因描述。

一般事件

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

屬性	說明
命名空間	套接字的命名空間。
socketId	套接字的唯一識別。
承載	Engine.IO 通訊協定中的訊息承載
eventName	要求的事件名稱。
parameters	訊息的參數清單。

輸出繫結

輸出系結目前支援下列功能：

• 將套接字新增至會議室
• 從會議室移除套接字
• 將訊息傳送至套接字
• 將訊息傳送至會議室
• 將訊息傳送至命名空間
• 中斷套接字連線

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

屬性

輸入系結的屬性為 [SocketIO]。

屬性內容	描述
中樞	用戶端需要連線的中樞名稱。
連線	包含 Socket.IO 連接字串 的應用程式設定名稱（預設值為WebPubSubForSocketIOConnectionString）。

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

組態

屬性內容	描述
type	必須是 socketio
中樞	用戶端需要連線的中樞名稱。
connection	包含 Socket.IO 連接字串 的應用程式設定名稱（預設值為WebPubSubForSocketIOConnectionString）。

Python 模型 v2

函式一律需要觸發程序系結。 我們會使用 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"
        ]
    }))

註釋

屬性內容	描述
arg_name	函式中自變數的變數名稱，表示輸出系結。
type	必須是 socketio
data_type	使用 DataType.STRING
中樞	用戶端需要連線的中樞名稱。
connection	包含 Socket.IO 連接字串 的應用程式設定名稱（預設值為WebPubSubForSocketIOConnectionString）。

動作

輸出系結會使用動作來執行作業。 目前，我們支援下列動作：

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
}