分享方式:


上游端點

上游端點功能可讓 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 存取權:

  1. 新增系統指派或使用者指派的身分識別。 請參閱如何在 Azure 入口網站中新增受控識別

  2. 在 Key Vault 的 [存取] 原則中授與受控識別的密碼讀取權限。 請參閱使用 Azure 入口網站指派 Key Vault 存取原則

  3. 在上游端點 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 環境整合。

  1. 移至 [Azure SignalR Service]。
  2. 選取設定
  3. 將 [服務模式] 切換為 [無伺服器]
  4. 在 [上游 URL 模式] 下方新增 URL。 AzureSignalR 服務上游設定的螢幕快照。
  5. 選取 [中樞規則] 以開啟 [上游設定]Azure SignalR 上游設定詳細數據的螢幕快照。
  6. 在對應的欄位中輸入規則值,以變更 [中樞規則]、[事件規則] 和 [類別規則]
  7. 在 [上游驗證] 下選取
  8. [使用受控識別]。 (確定您已啟用受控識別)
  9. 選擇 [已發行權杖中的對象] 下的任意選項。 如需詳細資訊,請參閱 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

已中斷連接

內容-類型:application/json

名稱 類型​​ 描述
錯誤 string 關閉連線的錯誤訊息。 當連線在沒有錯誤的狀況下關閉時為空白。

叫用訊息

內容類型:application/jsonapplication/x-msgpack

名稱 類型​​ 描述
InvocationId string 代表叫用訊息的選擇性字串。 在叫用中尋找詳細資料。
Target string 與事件相同,也與叫用訊息中的目標相同。
引數 物件陣列 一種陣列,其中包含要套用至 Target 所參考的方法的引數。

簽章

該服務會使用主要存取金鑰和次要存取金鑰做為 HMAC 金鑰來計算 X-ASRS-Connection-Id 值的 SHA256 程式碼。 對上游端點提出 HTTP 要求時,該服務會在 X-ASRS-Signature 標題中設定該項目:

Hex_encoded(HMAC_SHA256(accessKey, connection-id))

下一步