你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Socket.IO Azure 函数触发器和绑定（预览版）

2024-12-18

本文介绍如何使用 Socket.IO 与 Azure Functions 进行无服务器集成。

操作	绑定类型
获取客户端协商结果，包括 URL 和访问令牌	输入绑定
由来自服务的消息触发	触发器绑定
调用服务以发送消息或管理客户端	输出绑定

源代码 | 包 | API 参考文档 | 产品文档 | 示例

重要

Azure 函数绑定只能在无服务器模式下与 Socket.IO 的 Web PubSub 集成。

身份验证和连接字符串

要让扩展与 Socket.IO 的 Web PubSub 一起工作，需要提供访问密钥或基于标识的配置，以便与服务进行身份验证。

基于访问密钥的配置

配置名称	说明
WebPubSubForSocketIOConnectionString	必需。基于密钥的服务连接字符串

可以在 Azure 门户中 Socket.IO 的 Web PubSub“密钥”边栏选项卡中找到连接字符串。

对于本地开发，请使用 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` 时，此属性可以设为指定在获取令牌时要使用的用户分配的标识。该属性接受与分配给应用程序的用户分配的标识对应的客户端 ID。如果未指定，则使用系统分配的标识。

函数绑定遵循基于标识配置的通用属性。有关更多未提及的属性，请参阅基于标识的连接的通用属性。

对于本地开发，请使用 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 以进行身份验证。通常的做法是由服务器来生成这些数据，这就是所谓的协商。

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

属性

输入绑定的属性是 [SocketIONegotiation]。

Attribute 属性	说明
集线器	客户端需要连接到的中心名称。
连接	包含 Socket.IO 连接字符串的应用设置名称（默认为 `WebPubSubForSocketIOConnectionString`）。
UserID	连接的 userId。它适用于连接中的所有套接字。它将成为生成的令牌中的 `sub` 声明。

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

配置

properties	说明
type	必须是 `socketionegotiation`
direction	必须是 `in`
name	变量名称，在输入连接绑定对象的函数代码中使用
中心	客户端需要连接到的中心名称。
连接	包含 Socket.IO 连接字符串的应用设置名称（默认为 `WebPubSubForSocketIOConnectionString`）。
userId	连接的 userId。它适用于连接中的所有套接字。它将成为生成的令牌中的 `sub` 声明。

函数总是需要一个触发器绑定。我们在代码中以 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)

注释

properties	说明
arg_name	函数中表示输入绑定的参数的变量名称。
type	必须是 `socketionegotiation`
中心	客户端需要连接到的中心名称。
连接	包含 Socket.IO 连接字符串的应用设置名称（默认为 `WebPubSubForSocketIOConnectionString`）。
userId	连接的 userId。它适用于连接中的所有套接字。它将成为生成的令牌中的 `sub` 声明。

触发器绑定

Azure 函数使用触发器绑定来触发一个函数，以处理来自 Socket.IO 的 Web PubSub 的事件。

触发器绑定会在 Azure 功能终结点之后公开一个特定路径。应将 URL 设置为服务的 URL 模板（门户：设置 -> 事件处理程序 -> URL 模板）。在终结点模式中，出于安全原因使用 Azure Function 应用时，查询部分 code=<API_KEY> 是必需的。密钥可在“Azure 门户”中找到。找到函数应用资源，将函数应用部署到 Azure 后，导航到函数 ->应用密钥 ->系统密钥 ->socketio_extension。但是，在使用本地函数时不需要此密钥。

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

套接字连接事件的函数触发器。

[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]。

Attribute 属性	说明
集线器	客户端需要连接到的中心名称。
命名空间	套接字的命名空间。默认值："/"
EventName	函数触发的事件名称。某些事件名称为预定义：`connect` 表示套接字连接事件。 `connected` 表示套接字连接事件。 `disconnected` 表示套接字断开连接事件。其他事件由用户定义，需要与客户端发送的事件名称相匹配。
ParameterNames	事件的参数名称列表。列表的长度应与客户端发送的事件一致。而该名称会使用绑定表达式，并通过同名函数参数进行访问。

绑定数据

[SocketIOTrigger] 会将某些变量与绑定数据绑定。可以从 Azure 函数绑定表达模式中了解更多信息。

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] 不能同时使用。

套接字连接事件的函数触发器。

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

配置

properties	说明
type	必须是 `socketiotrigger`
中心	客户端需要连接到的中心名称。
命名空间	套接字的命名空间。默认值："/"
eventName	函数触发的事件名称。某些事件名称为预定义：`connect` 表示套接字连接事件。 `connected` 表示套接字连接事件。 `disconnected` 表示套接字断开连接事件。其他事件由用户定义，需要与客户端发送的事件名称相匹配。
ParameterNames	事件的参数名称列表。列表的长度应与客户端发送的事件一致。而该名称使用绑定表达式并通过 `context.bindings.<name>` 访问。

套接字连接事件的函数触发器。

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

注释

properties	说明
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": ""
        }
    }
}

properties	说明
命名空间	套接字的命名空间。
socketId	套接字的唯一标识。
声明	客户端连接的 JWT 声明。请注意，这不是服务请求函数时的 JWT，而是当 Engine.IO 客户端连接到服务时的 JWT。
查询	客户端连接的查询。请注意，这不是服务请求函数时的查询，而是 Engine.IO 客户端连接到服务时的查询。
headers	客户端连接的标头。请注意，这不是服务请求函数时的标头，而是 Engine.IO 客户端连接到服务时的标头。
clientCertificates	客户端证书（如已启用）

已连接

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

properties	说明
命名空间	套接字的命名空间。
socketId	套接字的唯一标识。

已断开连接

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

properties	说明
命名空间	套接字的命名空间。
socketId	套接字的唯一标识。
reason	连接关闭原因的说明。

正常事件

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

properties	说明
命名空间	套接字的命名空间。
socketId	套接字的唯一标识。
payload	Engine.IO 协议中的消息有效负荷
eventName	请求的事件名称。
parameters	消息的参数列表。

输出绑定

输出绑定目前支持以下功能：

将套接字添加到空间
从空间中删除套接字
向套接字发送消息
向空间发送消息
向命名空间发送消息
断开套接字

[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]。

Attribute 属性	说明
集线器	客户端需要连接到的中心名称。
连接	包含 Socket.IO 连接字符串的应用设置名称（默认为 `WebPubSubForSocketIOConnectionString`）。

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

配置

Attribute 属性	说明
type	必须是 `socketio`
中心	客户端需要连接到的中心名称。
连接	包含 Socket.IO 连接字符串的应用设置名称（默认为 `WebPubSubForSocketIOConnectionString`）。

函数总是需要一个触发器绑定。我们在代码中以 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"
        ]
    }))

注释

Attribute 属性	说明
arg_name	函数中表示输出绑定的参数的变量名称。
type	必须是 `socketio`
data_type	使用 `DataType.STRING`
中心	客户端需要连接到的中心名称。
连接	包含 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
}

通过

Socket.IO Azure 函数触发器和绑定（预览版）

身份验证和连接字符串

基于访问密钥的配置

基于标识的配置

输入绑定

属性

触发器绑定

特性

绑定数据

SocketIOAttribute

输入绑定的请求

连接

已连接

已断开连接

正常事件

输出绑定

属性

操作

AddSocketToRoomAction

RemoveSocketFromRoomAction

SendToNamespaceAction

SendToRoomsAction

SendToSocketAction

DisconnectSocketsAction

反馈

其他资源