上游端點
上游端點功能可讓 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
已中斷連接
內容-類型:application/json
名稱 | 類型 | 描述 |
---|---|---|
錯誤 | string | 關閉連線的錯誤訊息。 當連線在沒有錯誤的狀況下關閉時為空白。 |
叫用訊息
內容類型:application/json
或 application/x-msgpack
名稱 | 類型 | 描述 |
---|---|---|
InvocationId | string | 代表叫用訊息的選擇性字串。 在叫用中尋找詳細資料。 |
Target | string | 與事件相同,也與叫用訊息中的目標相同。 |
引數 | 物件陣列 | 一種陣列,其中包含要套用至 Target 所參考的方法的引數。 |
簽章
該服務會使用主要存取金鑰和次要存取金鑰做為 HMAC
金鑰來計算 X-ASRS-Connection-Id
值的 SHA256 程式碼。 對上游端點提出 HTTP 要求時,該服務會在 X-ASRS-Signature
標題中設定該項目:
Hex_encoded(HMAC_SHA256(accessKey, connection-id))