上游端點

發行項
10/24/2023

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

注意

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

上游端點設定

上游端點的設定包含一份區分順序的專案清單：

URL 範本，指定訊息傳送至何處。
一組規則。
驗證組態。

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

URL 範本設定

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

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

這些預先定義的參數可用於 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 範本設定中的秘密參考

上游端點 URL 不會加密。您可以使用金鑰保存庫來保護敏感性上游端點，並使用受控識別加以存取。

若要在您的 SignalR 服務實例中啟用受控識別，並將它授與金鑰保存庫存取權：

新增系統指派的身分識別或使用者指派的身分識別。請參閱如何在 Azure 入口網站中新增受控識別。
在金鑰保存庫的存取原則中授與受控識別的秘密讀取權限。請參閱使用Azure 入口網站指派金鑰保存庫存取原則
將敏感性文字取代為上游端點 URL 模式中的下列語法：
```
{@Microsoft.KeyVault(SecretUri=<secret-identity>)}
```
<secret-identity>是金鑰保存庫中秘密的完整資料平面 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/)}
```

注意

每 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 服務。
選取設定。
將服務模式切換至無伺服器。
在 [上游 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-連線ion-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

Content-Type： application/json

已中斷連接