Socket.IO Azure 関数トリガーとバインド (プレビュー)

2024-12-23

この記事では、サーバーレスの Socket.IO を使用した Azure Functions との統合について説明します。

アクション	バインドの種類
URL とアクセストークンを含むクライアントネゴシエートの結果を取得する	入力バインド
サービスからメッセージによってトリガーする	トリガーバインド
サービスを呼び出してメッセージを送信するかクライアントを管理する	出力バインド

ソースコード | パッケージ | API リファレンスドキュメント | 製品ドキュメント | サンプル

重要

Azure 関数のバインドは、サーバーレスモードの Web PubSub for Socket.IO とのみ統合できます。

認証と接続文字列

拡張機能が Web PubSub for Socket.IO で動作できるようにするには、サービスで認証するためのアクセスキーベースまたは ID ベースの構成を指定する必要があります。

アクセスキーベースの構成

構成名	説明
WebPubSubForSocketIOConnectionString	必須。サービスへのキーベースの接続文字列

接続文字列は、Azure portal の Web PubSub for Socket.IO の [キー] ブレードにあります。

ローカル開発の場合は、local.settings.json ファイルを使用して接続情報を保存します。 WebPubSubForSocketIOConnectionString を、前の手順でコピーした接続文字列に設定します。

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

デプロイ時に、アプリケーション設定を使用して接続文字列を設定します。

ID ベースの構成

構成名	説明
WebPubSubForSocketIOConnectionString__endpoint	必須。サービスのエンドポイント。たとえば、https://mysocketio.webpubsub.azure.com のように指定します。
WebPubSubForSocketIOConnectionString__credential	接続のためにトークンを取得する方法を定義します。デプロイされた Azure Function でマネージド ID 認証を使用する場合は、この設定を `managedidentity` に設定する必要があります。この値は、ホスティング環境でマネージド ID が使用できる場合にのみ有効です。
WebPubSubForSocketIOConnectionString__clientId	`credential` が `managedidentity` に設定されると、このプロパティによって、トークン取得時に使用されるユーザー割り当て ID を指定できます。このプロパティは、アプリケーションに割り当てられたユーザー割り当て ID に相当するクライアント ID を受け取ります。指定されていない場合、システム割り当て ID が使用されます。

関数バインドは、ID ベースの構成の共通プロパティに従います。言及されていないプロパティの詳細については、「ID ベースの接続に共通のプロパティ」を参照してください。

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

ID ベースの構成を使用してオンラインで実行する場合、AzureWebJobsStorage では「ID を使用してホストストレージに接続する」を参照する必要があります。

入力バインディング

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

Attribute

入力バインドの属性は [SocketIONegotiation] です。

属性のプロパティ	説明
ハブ	クライアントが接続する必要があるハブ名。
つながり	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
});

構成

プロパティ	説明
type	`Default` である必要があります。
direction	`Default` である必要があります。
name	入力接続バインドオブジェクトの関数コードで使用される変数名
hub	クライアントが接続する必要があるハブ名。
connection	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)

注釈

プロパティ	説明
arg_name	入力バインドを表す関数内の引数の変数名。
type	`Default` である必要があります。
hub	クライアントが接続する必要があるハブ名。
connection	Socket.IO 接続文字列が含まれているアプリ設定の名前 (既定値は `WebPubSubForSocketIOConnectionString`)。
userId	接続の userId。接続内のすべてのソケットに適用されます。生成されたトークンの `sub` 要求になります。

トリガーバインド

Azure 関数ではトリガーバインドを使用して、Web PubSub for Socket.IO からのイベントを処理する関数をトリガーします。

トリガーバインドでは、Azure 関数エンドポイントに続く特定のパスを公開します。 URL は、サービスの URL テンプレートとして設定する必要があります (ポータル: 設定 -> イベントハンドラー -> URL テンプレート)。エンドポイントパターンでは、セキュリティ上の理由で、Azure 関数アプリを使用している場合は、クエリ部分 code=<API_KEY> が必須です。このキーは Azure portal で確認できます。関数アプリを 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] です。

属性のプロパティ	説明
ハブ	クライアントが接続する必要があるハブ名。
名前空間	ソケットの名前空間。既定値: "/"
EventName	関数がトリガーするイベント名。一部のイベント名は次のように事前に定義されています: ソケット接続イベントの場合は `connect`。ソケット接続済みイベントの場合は `connected`。ソケット切断済みイベントの場合は `disconnected`。また、他のイベントはユーザーによって定義されます。これは、クライアント側によって送信されるイベント名と一致する必要があります。
ParameterNames	イベントのパラメーター名リスト。リストの長さは、クライアントによって送信されるイベントと一致している必要があります。また、この名前はバインド式と、same-name 関数パラメーターによるアクセスを使用しています。

バインドデータ

[SocketIOTrigger] は、一部の変数をバインドデータにバインドします。詳細については、「Azure Functions のバインド式のパターン」を参照してください

SocketIOAttribute

SocketIOAttribute は ParameterNames のオルタナティヴであり、関数の定義を簡略化します。たとえば、次の 2 つの定義の効果は同じです。

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

構成

プロパティ	説明
type	`Default` である必要があります。
hub	クライアントが接続する必要があるハブ名。
namespace	ソケットの名前空間。既定値: "/"
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"]})

注釈

プロパティ	説明
arg_name	トリガーバインドを表す関数内の引数の変数名。
type	`Default` である必要があります。
hub	クライアントが接続する必要があるハブ名。
data_type	`Default` である必要があります。
namespace	ソケットの名前空間。既定値: "/"
eventName	関数がトリガーするイベント名。一部のイベント名は次のように事前に定義されています: ソケット接続イベントの場合は `connect`。ソケット接続済みイベントの場合は `connected`。ソケット切断済みイベントの場合は `disconnected`。また、他のイベントはユーザーによって定義されます。これは、クライアント側によって送信されるイベント名と一致する必要があります。

入力バインドの要求

入力バインド引数のデータ構造は、メッセージの種類によって異なります。

のインスタンスに接続するときには、

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

プロパティ	説明
namespace	ソケットの名前空間。
socketId	ソケットの一意の ID。
claims	クライアント接続の JWT の要求。これはサービスが関数を要求するときの JWT ではなく、Engine.IO クライアントがサービスに接続するときの JWT であることに注意してください。
クエリ	クライアント接続のクエリ。これはサービスが関数を要求するときのクエリではなく、Engine.IO クライアントがサービスに接続するときのクエリであることに注意してください。
headers	クライアント接続のヘッダー。これはサービスが関数を要求するときのヘッダーではなく、Engine.IO クライアントがサービスに接続するときのヘッダーであることに注意してください。
clientCertificates	クライアント証明書 (有効になっている場合)

接続済み

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

プロパティ	説明
namespace	ソケットの名前空間。
socketId	ソケットの一意の ID。

[Disconnected](切断済み)

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

プロパティ	説明
namespace	ソケットの名前空間。
socketId	ソケットの一意の ID。
reason	接続を閉じる理由の説明。

通常のイベント

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

プロパティ	説明
namespace	ソケットの名前空間。
socketId	ソケットの一意の ID。
ペイロード	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" }));
}

Attribute

入力バインドの属性は [SocketIO] です。

属性のプロパティ	説明
ハブ	クライアントが接続する必要があるハブ名。
つながり	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
});

構成

属性のプロパティ	説明
type	`Default` である必要があります。
hub	クライアントが接続する必要があるハブ名。
connection	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"
        ]
    }))

注釈

属性のプロパティ	説明
arg_name	出力バインドを表す関数内の引数の変数名。
type	`Default` である必要があります。
data_type	`DataType.STRING` を使用します
hub	クライアントが接続する必要があるハブ名。
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
}

次の方法で共有

Socket.IO Azure 関数トリガーとバインド (プレビュー)

認証と接続文字列

アクセス キー ベースの構成

ID ベースの構成

入力バインディング

Attribute

トリガー バインド

属性

バインド データ

SocketIOAttribute

入力バインドの要求

のインスタンスに接続するときには、

接続済み

[Disconnected](切断済み)

通常のイベント

出力バインディング

Attribute

アクション

AddSocketToRoomAction

RemoveSocketFromRoomAction

SendToNamespaceAction

SendToRoomsAction

SendToSocketAction

DisconnectSocketsAction

フィードバック

その他のリソース

アクセスキーベースの構成

トリガーバインド

バインドデータ