Azure Functions の Azure Web PubSub トリガー バインド

Azure Web PubSub トリガーを使用して、Azure Web PubSub サービスからのクライアント イベントを処理します。

トリガー エンドポイント パターンは次のようになります。これは Web PubSub サービス側で設定する必要があります (ポータル: settings -> イベント ハンドラー -> URL テンプレート)。 エンドポイント パターンでは、code=<API_KEY>上の理由で、Azure 関数アプリを使用している場合は、クエリ部分 が必須です。 このキーは Azure portal で確認できます。 関数アプリを Azure にデプロイした後に、関数アプリ リソースを見つけて、[関数] ->[アプリ キー] ->[システム キー] ->[webpubsub_extension] の順に移動します。 ただし、ローカル関数を使用する場合、このキーは必要ありません。

<Function_App_Url>/runtime/webhooks/webpubsub?code=<API_KEY>

例

次の例は、クライアントからのユーザー イベントを処理する方法を示しています。

分離ワーカー モデル

[Function("Broadcast")]
public static void Run(
[WebPubSubTrigger("<hub>", WebPubSubEventType.User, "message")] UserEventRequest request, ILogger log)
{
    log.LogInformation($"Request from: {request.ConnectionContext.UserId}");
    log.LogInformation($"Request message data: {request.Data}");
    log.LogInformation($"Request message dataType: {request.DataType}");
}

インプロセス モデル

[FunctionName("WebPubSubTrigger")]
public static void Run(
    [WebPubSubTrigger("<hub>", WebPubSubEventType.User, "message")] UserEventRequest request, ILogger log)
{
    log.LogInformation($"Request from: {request.ConnectionContext.UserId}");
    log.LogInformation($"Request message data: {request.Data}");
    log.LogInformation($"Request message dataType: {request.DataType}");
}

WebPubSubTrigger バインドでは、同期シナリオの戻り値もサポートされています。たとえば、サーバーがクライアント要求を確認して拒否できる場合や、呼び出し元に直接メッセージを送信できる場合の、システム Connect イベントやユーザー イベントなどです。 Connect イベントでは ConnectEventResponse と EventErrorResponse が考慮され、ユーザー イベントでは UserEventResponse と EventErrorResponse が考慮されます。現在のシナリオと一致しない残りの型は無視されます。

分離ワーカー モデル

[Function("Broadcast")]
public static UserEventResponse Run(
[WebPubSubTrigger("<hub>", WebPubSubEventType.User, "message")] UserEventRequest request)
{
    return new UserEventResponse("[SYSTEM ACK] Received.");
}

インプロセス モデル

[FunctionName("WebPubSubTriggerReturnValueFunction")]
public static UserEventResponse Run(
    [WebPubSubTrigger("hub", WebPubSubEventType.User, "message")] UserEventRequest request)
{
    return request.CreateResponse(BinaryData.FromString("ack"), WebPubSubDataType.Text);
}

モデル v4

const { app, trigger } = require('@azure/functions');

const wpsTrigger = trigger.generic({
    type: 'webPubSubTrigger',
    name: 'request',
    hub: '<hub>',
    eventName: 'message',
    eventType: 'user'
});

app.generic('message', {
    trigger: wpsTrigger,
    handler: async (request, context) => {
        context.log('Request from: ', request.connectionContext.userId);
        context.log('Request message data: ', request.data);
        context.log('Request message dataType: ', request.dataType);
    }
});

モデル v3

function.jsonでトリガー バインドを定義します。

{
  "disabled": false,
  "bindings": [
    {
      "type": "webPubSubTrigger",
      "direction": "in",
      "name": "data",
      "hub": "<hub>",
      "eventName": "message",
      "eventType": "user"
    }
  ]
}

index.jsで関数を定義します。

module.exports = function (context, data) {
  context.log('Request from: ', context.bindingData.request.connectionContext.userId);
  context.log('Request message data: ', data);
  context.log('Request message dataType: ', context.bindingData.request.dataType);
}

WebPubSubTrigger バインドでは、同期シナリオの戻り値もサポートされています。たとえば、サーバーがクライアント要求を確認して拒否できる場合や、要求クライアントに直接メッセージを送信できる場合の、システム Connect イベントやユーザー イベントなどです。 厳密に型指定されていない JavaScript 言語では、オブジェクト キーに関して逆シリアル化されます。 また、 EventErrorResponse は、rest オブジェクトと比較して最も優先度が高く、 code が戻り値にある場合は、 EventErrorResponseに解析されます。

モデル v4

app.generic('message', {
    trigger: wpsTrigger,
    handler: async (request, context) => {
          return {
              "data": "ack",
              "dataType" : "text"
          };
    }
});

モデル v3

module.exports = async function (context) {
  return {
    "data": "ack",
    "dataType" : "text"
  };
}

注

この言語の完全なサンプルは保留中です。

注

Java 用 Web PubSub 拡張機能はまだサポートされていません。

構成

次の表は、function.json ファイルで設定したバインド構成のプロパティを説明しています。

function.json のプロパティ	属性のプロパティ	説明
タイプ	該当なし	必須 - webPubSubTrigger に設定する必要があります。
方向	該当なし	必須 - in に設定する必要があります。
名前	該当なし	必須 - イベント データを受信するパラメーターの、関数コードで使われている変数名。
ハブ	ハブ	必須 - この値は、トリガーされる関数の Web PubSub ハブの名前に設定する必要があります。 高い優先順位として属性への値の設定をサポートしていますが、またはグローバル値としてアプリ設定に設定することもできます。
イベントタイプ	WebPubSubEventType	必須 - この値は、トリガーされる関数のメッセージのイベントの種類として設定する必要があります。 値は、user または system である必要があります。
eventName	イベント名	必須 - この値は、トリガーされる関数のメッセージのイベントとして設定する必要があります。 system イベントの種類の場合、イベント名は connect、connected、disconnectedにする必要があります。 ユーザー定義サブプロトコルの場合、イベント名はmessage。 システムでサポートされているサブプロトコル json.webpubsub.azure.v1.の場合、イベント名はユーザー定義のイベント名です。
clientProtocols	ClientProtocols	省略可能 - Web PubSub トリガー関数をトリガーできるクライアント プロトコルを指定します。 大文字と小文字を区別しない値は有効です。 all: すべてのクライアント プロトコルを受け入れます。 既定値です。 webPubSub: Web PubSub プロトコルのみを受け入れます。 mqtt: MQTT プロトコルのみを受け入れます。
接続	つながり	省略可能 - アップストリームの Azure Web PubSub サービスを指定するアプリ設定または設定コレクションの名前。 値は署名の検証に使用されます。 また、この値は既定で WebPubSubConnectionString アプリ設定で自動的に解決されます。 nullは、検証が必要ではなく、常に成功したことを意味します。

重要

最適なセキュリティを確保するために、関数アプリでは、共有シークレット キーを含む接続文字列を使用する代わりに、Web PubSub サービスに接続するときにマネージド ID を使用する必要があります。 詳細については、「 Microsoft Entra ID を使用してマネージド ID 要求を認証するを参照してください。

使用法

C# で WebPubSubEventRequest は、型が認識されたバインディング パラメーターであり、残りのパラメーターはパラメーター名によってバインドされます。 使用可能なパラメーターと型については、次の表を参照してください。

JavaScript のような弱く型指定された言語では、nameのfunction.jsonを使用して、次のマッピング テーブルに関するトリガー オブジェクトをバインドします。 さらに、トリガー入力のバインディング オブジェクトとして dataType が function.json に設定されている場合に、name の data が考慮され、それに応じてメッセージが変換されます。 すべてのパラメーターは context.bindingData.<BindingName> から読み取ることができ、JObject 変換されます。

バインディング名	バインドの種類	説明	プロパティ
リクエスト	WebPubSubEventRequest	アップストリーム要求を記述します	プロパティは、派生クラスの ConnectEventRequest、 MqttConnectEventRequest、 ConnectedEventRequest、 MqttConnectedEventRequest、 UserEventRequest、 DisconnectedEventRequest、 MqttDisconnectedEventRequestなど、さまざまなイベントの種類によって異なります。
接続コンテキスト	WebPubSubConnectionContext	一般的な要求情報	EventType、EventName、Hub、ConnectionId、UserId、Headers、Origin、Signature、States
データ	BinaryData、string、Stream、byte[]	ユーザー message イベントでのクライアントからの要求メッセージ データ	-
データタイプ	WebPubSubDataType	要求メッセージのデータ型。binary、text、json がサポートされています	-
主張	IDictionary<string, string[]>	システム connect 要求でのユーザー要求	-
問い合わせ	IDictionary<string, string[]>	システム connect 要求でのユーザー クエリ	-
サブプロトコル	IList<string>	システム connect 要求での使用可能なサブプロトコル	-
クライアント証明書	IList<ClientCertificate>	システム connect 要求でのクライアントからの証明書の拇印のリスト	-
理由	string	システム disconnected 要求での理由	-

重要

C# では、関数バインドを正しく行うために、複数の型がサポートされるパラメータを最初 (つまり、既定値の 型以外の request または data) に入れるBinaryData。

応答を返す

WebPubSubTrigger では、connect の同期イベントおよびユーザー イベントに対して、顧客が返した応答が考慮されます。 一致した応答だけがサービスに送り返されます。それ以外の場合は無視されます。 さらに、WebPubSubTrigger 戻りオブジェクトでは、接続のメタデータを管理するために、ユーザによる SetState() と ClearStates() がサポートされます。 また、拡張機能により、戻り値の結果が要求の WebPubSubConnectionContext.States の元の値とマージされます。 既存のキーの値が上書きされ、新しいキーの値が追加されます。

返り値の種類	説明	プロパティ
ConnectEventResponse	connect イベントの応答	Groups、Roles、UserId、Subprotocol
UserEventResponse	ユーザー イベントの応答	DataType、Data
EventErrorResponse	同期イベントのエラー応答	Code、ErrorMessage
*WebPubSubEventResponse	戻り値が不明な場合に使用される、サポートされている基本の応答の種類	-