アップストリームエンドポイント

[アーティクル]
10/31/2023

アップストリームエンドポイント機能を使用すると、Azure SignalR Service からサーバーレスモードで一連のエンドポイントにメッセージと接続イベントを送信することができます。アップストリームエンドポイントを使用すると、サーバーレスモードのクライアントからハブメソッドを呼び出し、クライアント接続が確立または切断されたときにエンドポイントに通知します。

Note

アップストリームエンドポイントは、サーバーレスモードでのみ構成できます。

アップストリームエンドポイント設定

アップストリームエンドポイントの設定は、順序が区別される項目の一覧で構成されています。

URL テンプレート。メッセージの送信先を指定します。
一連のルール。
認証の構成。

イベントが発生すると、項目のルールが 1 つずつ順番にチェックされます。メッセージは、最初に一致した項目のアップストリームエンドポイント URL に送信されます。

URL テンプレートの設定

アップストリームエンドポイント URL をパラメーター化すると、さまざまなパターンをサポートできます。次の 3 つの定義済みパラメーターがあります。

定義済みパラメーター	説明
{hub}	ハブは Azure SignalR Service の概念です。ハブは分離の単位です。ユーザーとメッセージ配信の範囲はハブに制限されています。
{category}	カテゴリには次のいずれかの値を指定することができます。 connections: 接続の有効期間イベント。このイベントは、クライアント接続が確立または切断されたときに発生します。これには connected イベントと disconnected イベントがあります。 messages: クライアントからハブメソッドが呼び出されたときに発生します。これには、connections カテゴリのイベントを除く、他のすべてのイベントが含まれます。
{event}	messages カテゴリの場合、イベントはクライアントから送信される呼び出しメッセージのターゲットです。 connections カテゴリの場合、connected と disconnected のみが使用されます。

これらの定義済みパラメーターは、URL パターン内で使用できます。アップストリームエンドポイント URL の評価時に、パラメーターは指定された値に置き換えられます。次に例を示します。

http://host.com/{hub}/api/{category}/{event}

"チャット" ハブでクライアント接続が確立すると、次の URL にメッセージが送信されます。

http://host.com/chat/api/connections/connected

"チャット" ハブのクライアントからハブメソッド broadcast が呼び出されると、次の URL にメッセージが送信されます。

http://host.com/chat/api/messages/broadcast

URL テンプレート設定の Key Vault シークレット参照

アップストリームエンドポイント URL は暗号化されません。 Key Vault を使用して機密性の高いアップストリームエンドポイントをセキュリティで保護し、マネージド ID を使用してアクセスするようにできます。

SignalR サービスインスタンスでマネージド ID を有効にし、Key Vault のアクセス権を付与するには、次の手順を実施します。

システム割り当て ID またはユーザー割り当て ID を追加します。 Azure portal でマネージド ID を追加する方法に関する記事を参照してください。
Key Vault のアクセスポリシーで、マネージド ID に対する読み取りアクセス許可をシークレットに付与します。 Azure portal を使用した Key Vault アクセスポリシーの割り当てに関する説明を参照してください
機密テキストをアップストリームエンドポイント URL パターンの次の構文に置き換えます。
```
{@Microsoft.KeyVault(SecretUri=<secret-identity>)}
```
<secret-identity> は、Key Vault におけるシークレットのフルデータプレーン URI であり、オプションでバージョン (例: https://myvault.vault.azure.net/secrets/mysecret/ または https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931) を含めることができます。

たとえば、完全な参照は次のようになります。
```
{@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
```
Azure 関数のアップストリームエンドポイント URL は次のようになります。
```
https://contoso.azurewebsites.net/runtime/webhooks/signalr?code={@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
```

Note

30 分ごと、またはアップストリームエンドポイント設定やマネージド ID が変更されるたびに、サービスはシークレットコンテンツを再読み取りします。アップストリームエンドポイントの設定を変更することで、すぐに更新をトリガーできます。

ルールの設定

"ハブルール"、"カテゴリルール"、および "イベントルール" は個別に設定できます。照合ルールは 3 つの形式をサポートしています。

すべてのイベントに一致させるには、アスタリスク (*) を使用します。
複数のイベントを結合するには、コンマ (,) を使用します。たとえば、connected, disconnected は connected イベントと disconnected イベントと一致します。
イベントと一致させるには、完全なイベント名を使用します。たとえば、connected は connected イベントと一致します。

Note

Azure Functions および SignalR トリガーを使用している場合、SignalR トリガーは、次の形式で単一のエンドポイントを公開します: <Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>。 URL テンプレート設定にはこの URL を構成し、ルール設定は既定のままにします。 <Function_App_URL> と <API_KEY> の検索方法については、SignalR Service の統合に関する説明を参照してください。

認証設定

アップストリームエンドポイントの設定ごとに個別に認証を設定することができます。認証を構成すると、アップストリームのメッセージの Authentication ヘッダーにトークンが設定されます。現在、Azure SignalR Service は次の認証の種類をサポートしています。

None
ManagedIdentity

ManagedIdentity を選択する場合は、まず Azure SignalR Service でマネージド ID を有効にする必要があります。また、必要に応じてリソースを指定します。詳細については、「Azure SignalR Service のマネージド ID」を参照してください。

Azure portal を使用してアップストリームエンドポイント設定を構成する

Note

現在、App Service Environment との統合はサポートされていません。

Azure SignalR Service に移動します。
設定を選択します。
[サービスモード] を [サーバーレス] に切り替えます。
[Upstream URL Pattern]\(アップストリームの URL パターン\) に URL を追加します。
[ハブルール] を選択して、[アップストリーム設定] を開きます。
対応するフィールドにルール値を入力して、[ハブルール]、[イベントルール]、および [カテゴリルール] を変更します。
[アップストリーム認証] で、
[マネージド ID を使用する] を選択します。 (マネージド ID が有効になっていることを確認します)
[発行されたトークン内の対象ユーザー] で任意のオプションを選択します。詳細については、「Azure SignalR Service のマネージド ID」を参照してください。

Resource Manager テンプレートを使用してアップストリームエンドポイント設定を構成する

Azure Resource Manager テンプレートを使用してアップストリームエンドポイント設定を構成するには、properties プロパティで upstream プロパティを設定します。次のスニペットは、アップストリームエンドポイント設定を作成および更新するために upstream プロパティを設定する方法を示しています。

{
  "properties": {
    "upstream": {
      "templates": [
        {
          "UrlTemplate": "http://host.com/{hub}/api/{category}/{event}",
          "EventPattern": "*",
          "HubPattern": "*",
          "CategoryPattern": "*",
          "Auth": {
            "Type": "ManagedIdentity",
            "ManagedIdentity": {
              "Resource": "<resource>"
            }
          }
        }
      ]
    }
  }
}

サーバーレスプロトコル

Azure SignalR Service からは、次のプロトコルに従うメッセージがエンドポイントに送信されます。 Function App で SignalR Service トリガーバインドを使用して、これらのプロトコルを処理できます。

方法

投稿

要求ヘッダー

名前	説明
X-ASRS-Connection-Id	クライアント接続の接続 ID。
X-ASRS-Hub	クライアント接続が属するハブ。
X-ASRS-Category	メッセージが属するカテゴリ。
X-ASRS-Event	メッセージが属するイベント。
X-ASRS-Signature	検証に使用されるハッシュベースのメッセージ認証コード (HMAC)。詳細については「署名」を参照してください。
X-ASRS-User-Claims	クライアント接続の要求のグループ。
X-ASRS-User-Id	メッセージを送信するクライアントのユーザー ID。
X-ASRS-Client-Query	クライアントがサービスに接続するときの要求のクエリ。
認証	`ManagedIdentity` を使用している場合の省略可能なトークン。

要求本文

接続済み

Content-Type: application/json

Disconnected

Content-Type: application/json

名前	タイプ	説明
Error	string	閉じられた接続のエラーメッセージ。エラーなしで接続が閉じた場合は空。

呼び出しメッセージ

Content-Type: application/json または application/x-msgpack

名前	タイプ	説明
InvocationId	string	呼び出しメッセージを表す省略可能な文字列。詳細については、「Invocations」 (呼び出し) を参照してください。
移行先	string	イベントと同じであり、呼び出しメッセージのターゲットと同じです。
引数	オブジェクトの配列	`Target` で参照されるメソッドに適用する引数を含む配列。

署名

サービスでは、プライマリアクセスキーとセカンダリアクセスキーの両方が HMAC キーとして使用され、X-ASRS-Connection-Id 値の SHA256 コードが計算されます。アップストリームエンドポイントへの HTTP 要求を行うときは、サービスによって X-ASRS-Signature ヘッダーに設定されます。

Hex_encoded(HMAC_SHA256(accessKey, connection-id))

アップストリームエンドポイント

アップストリームエンドポイント設定

URL テンプレートの設定

URL テンプレート設定の Key Vault シークレット参照

ルールの設定

認証設定

Azure portal を使用してアップストリームエンドポイント設定を構成する

Resource Manager テンプレートを使用してアップストリームエンドポイント設定を構成する

サーバーレスプロトコル

方法

要求ヘッダー

要求本文

接続済み

Disconnected

呼び出しメッセージ

署名

次のステップ

その他のリソース

アップストリーム エンドポイント

アップストリーム エンドポイント設定

URL テンプレートの設定

URL テンプレート設定の Key Vault シークレット参照

ルールの設定

認証設定

Azure portal を使用してアップストリーム エンドポイント設定を構成する

Resource Manager テンプレートを使用してアップストリーム エンドポイント設定を構成する

サーバーレス プロトコル

方法

要求ヘッダー

要求本文

接続済み

Disconnected

呼び出しメッセージ

署名

次のステップ

その他のリソース

アップストリームエンドポイント

アップストリームエンドポイント設定

Azure portal を使用してアップストリームエンドポイント設定を構成する

Resource Manager テンプレートを使用してアップストリームエンドポイント設定を構成する

サーバーレスプロトコル