上游端點

發行項
05/28/2024

上游端點功能可讓 Azure SignalR Service 以無伺服器模式將訊息和連線活動傳送至一組端點。您可以使用上游端點，從用戶端以無伺服器模式叫用中樞方法，並在用戶端連線或中斷連線時通知端點。

注意

上游端點只能在無伺服器模式中設定。

上游端點設定

上游端點設定中包含區分順序的項目清單：

一個指定訊息應傳送至何處的 URL 範本。
一組規則。
驗證設定。

當事件被引發時，系統會依序檢查項目的規則。訊息會傳送至第一個相符項目的上游端點 URL。

URL 範本設定

您可以將上游端點 URL 參數化以支援各種模式。預先定義的參數有三種：

預先定義的參數	描述
{中樞}	中樞是 Azure SignalR Service 的概念。中樞是隔離的單位。使用者和訊息傳遞的範圍受限於中樞。
{類別}	類別可以是下列數值之一：連線：連線存留期事件。用戶端連線或中斷連線時會引發此事件。它包含已連線和中斷連線的事件。訊息：當用戶端叫用中樞方法時會引發此事件。其中包含除了 [連線] 類別之外的所有其他事件。
{事件}	對於 [訊息] 類別，事件是用戶端傳送的叫用訊息中的目標。對於 [連線] 類別，它只會用到 [連線] 和 [中斷連線]。

這些預先定義的參數可用於 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 保護敏感性上游端點，並使用受控識別進行存取。

若要在 SignalR Service 執行個體中啟用受控識別，並授與 Key Vault 存取權：

新增系統指派或使用者指派的身分識別。請參閱如何在 Azure 入口網站中新增受控識別。
在 Key Vault 的 [存取] 原則中授與受控識別的密碼讀取權限。請參閱使用 Azure 入口網站指派 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 Function 的上游端點 URL 如下所示：
```
https://contoso.azurewebsites.net/runtime/webhooks/signalr?code={@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
```

注意

每隔 30 分鐘或當上游設定或受控識別變更時，服務便會重新讀取秘密內容。您可以透過變更上游端點設定，藉此立即觸發更新。

規則設定

您可以分別設定「中樞規則」、「類別規則」和「事件規則」。比對規則支援三種格式：

使用星號 (*) 來比對任何事件。
使用逗號 (,) 來聯結多個事件。例如，connected, disconnected 符合已連線和已中斷連線的事件。
使用完整的事件名稱來比對事件。例如，connected 符合已連線事件。

注意

如果您使用 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 中啟用受控識別，並視需要指定資源。如需詳細資訊，請參閱 Azure SignalR Service 的受控識別。

透過 Azure 入口網站設定上游端點設定

注意

目前不支援與 App Service 環境整合。

移至 [Azure SignalR Service]。
選取設定。
將 [服務模式] 切換為 [無伺服器]。
在 [上游 URL 模式] 下方新增 URL。
選取 [中樞規則] 以開啟 [上游設定]。
在對應的欄位中輸入規則值，以變更 [中樞規則]、[事件規則] 和 [類別規則]。
在 [上游驗證] 下選取
[使用受控識別]。 (確定您已啟用受控識別)
選擇 [已發行權杖中的對象] 下的任意選項。如需詳細資訊，請參閱 Azure SignalR Service 的受控識別。

透過 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 將訊息傳送至遵循下列通訊協定的端點。您可以利用函式應用程式來使用 SignalR Service 觸發程序繫結，讓它為您處理通訊協定。

方法

POST

要求標頭

名稱	描述
X-ASRS-Connection-Id	用戶端連線的連線識別碼。
X-ASRS-Hub	用戶端連線所屬的中樞。
X-ASRS-Category	訊息所屬的類別。
X-ASRS-Event	訊息所屬的事件。
X-ASRS-Signature	用於驗證的雜湊式訊息驗證碼 (HMAC)。如需詳細資訊，請參閱簽章。
X-ASRS-User-Claims	用戶端連線的宣告群組。
X-ASRS-User-Id	傳送訊息的用戶端使用者身分識別。
X-ASRS-Client-Query	用戶端連線至服務時的要求查詢。
驗證	您在使用 `ManagedIdentity` 時可以選用的權杖。

要求本文

Connected

內容-類型：application/json

已中斷連接