上游端點
上游端點功能可讓 Azure SignalR Service 以無伺服器模式將訊息和線上活動傳送至一組端點。 您可以使用上游端點從無伺服器模式的用戶端叫用中樞方法,以在用戶端連線或中斷連線時通知端點。
注意
上游端點只能在無伺服器模式中設定。
上游端點設定
上游端點的設定包含一份區分順序的專案清單:
- URL 範本,指定訊息傳送至何處。
- 一組規則。
- 驗證組態。
引發事件時,會依序檢查項目的規則。 訊息會傳送至第一個相符專案的上游端點 URL。
URL 範本設定
您可以將上游端點 URL 參數化,以支援各種模式。 有三個預先定義的參數:
預先定義的參數 | 描述 |
---|---|
{hub} | 中樞是 Azure SignalR Service 的概念。 中樞是隔離單位。 使用者和訊息傳遞的範圍受限於中樞。 |
{category} | 類別可以是下列其中一個值:
|
{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
已中斷連接
Content-Type: application/json
名稱 | 類型 | 描述 |
---|---|---|
錯誤 | string | 已關閉連線的錯誤訊息。 當連線關閉且沒有錯誤時,則為空白。 |
調用訊息
Content-Type: application/json
或 application/x-msgpack
名稱 | 類型 | 描述 |
---|---|---|
InvocationId | string | 代表調用訊息的選擇性字串。 在調用中 尋找詳細資料 。 |
目標 | string | 與 事件相同,與調用訊息 中的 目標相同。 |
引數 | 物件的陣列 | 陣列,包含要套用至 中參考之方法的 Target 引數。 |
簽名
服務會使用主要存取金鑰和次要存取金鑰作為 HMAC
金鑰,計算 X-ASRS-Connection-Id
值的 SHA256 程式碼。 當向上游端點提出 HTTP 要求時,服務會在標頭中 X-ASRS-Signature
設定它:
Hex_encoded(HMAC_SHA256(accessKey, connection-id))