Upstream-Endpunkte
Das Feature für Upstream-Endpunkte ermöglicht Azure SignalR Service das Senden von Nachrichten und Verbindungsereignissen an eine Reihe von Endpunkten im serverlosen Modus. Sie können Upstream-Endpunkte verwenden, um eine Hubmethode von Clients im serverlosen Modus aufzurufen, damit Endpunkte benachrichtigt werden, wenn Clientverbindungen bestehen oder getrennt sind.
Hinweis
Upstream-Endpunkte können nur im serverlosen Modus konfiguriert werden.
Einstellungen für Upstream-Endpunkte
Die Einstellungen für Upstream-Endpunkte bestehen aus einer Liste von Elementen mit einer bestimmten Reihenfolge:
- Eine URL-Vorlage, die angibt, wohin Nachrichten gesendet werden
- Eine Reihe von Regeln
- Authentifizierungskonfigurationen
Wenn ein Ereignis ausgelöst wird, werden die Regeln eines Elements nacheinander der Reihe nach geprüft. Die Nachrichten werden an die Upstream-Endpunkt-URL des ersten übereinstimmenden Elements gesendet.
URL-Vorlageneinstellungen
Sie können die Upstream-Endpunkt-URL parametrisieren, um verschiedene Muster zu unterstützen. Es gibt drei vordefinierte Parameter:
Vordefinierter Parameter | Beschreibung |
---|---|
{hub} | Ein Hub ist ein Konzept von Azure SignalR Service. Ein Hub ist eine Isolationseinheit. Der Bereich der Benutzer und der Nachrichtenübermittlung ist auf einen Hub beschränkt. |
{category} | Eine Kategorie kann einen der folgenden Werte aufweisen:
|
{event} | Für die Kategorie messages ist ein Ereignis das Ziel in der Aufrufnachricht, die Clients senden. Für die Kategorie connections werden nur connected und disconnected verwendet. |
Diese vordefinierten Parameter können im URL-Muster verwendet werden. Parameter werden durch einen angegebenen Wert ersetzt, wenn Sie die Upstream-Endpunkt-URL auswerten. Zum Beispiel:
http://host.com/{hub}/api/{category}/{event}
Wenn eine Clientverbindung im „chat“-Hub verbunden ist, wird eine Nachricht an diese URL gesendet:
http://host.com/chat/api/connections/connected
Wenn ein Client im „chat“-Hub die Hubmethode broadcast
aufruft, wird eine Nachricht an diese URL gesendet:
http://host.com/chat/api/messages/broadcast
Verweis auf Key Vault-Geheimnis in den URL-Vorlageneinstellungen
Die Upstream-Endpunkt-URL ist nicht verschlüsselt. Sie können sensible Upstream-Endpunkte mithilfe von Key Vault schützen und mit einer verwalteten Identität darauf zugreifen.
So aktivieren Sie die verwaltete Identität in Ihrer SignalR Service-Instanz und gewähren ihr Key Vault-Zugriff
Fügen Sie eine systemseitig oder benutzerseitig zugewiesene Identität hinzu. Mehr dazu finden Sie unter Hinzufügen einer verwalteter Identität im Azure-Portal.
Erteilen Sie der verwalteten Identität in den Zugriffsrichtlinien im Key Vault Leseberechtigung. Weitere Informationen finden Sie unter Zuweisen einer Key Vault-Zugriffsrichtlinie über das Azure-Portal.
Ersetzen Sie Ihren vertraulichen Text im Upstream-Endpunkt-URL-Muster durch die folgende Syntax:
{@Microsoft.KeyVault(SecretUri=<secret-identity>)}
<secret-identity>
ist der vollständige URI der Datenebene eines Geheimnisses in Key Vault, optional einschließlich einer Version, z. B. https://myvault.vault.azure.net/secrets/mysecret/ oder https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931.Ein vollständiger Verweis kann beispielsweise wie folgt aussehen:
{@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
Eine Upstream-Endpunkt-URL zu Azure Functions sähe wie folgt aus:
https://contoso.azurewebsites.net/runtime/webhooks/signalr?code={@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
Hinweis
Alle 30 Minuten oder jedes Mal, wenn sich die Einstellungen des Upstream-Endpunkts oder die verwaltete Identität ändern, liest der Dienst den Geheimnisinhalt neu. Sie können ein Update sofort auslösen, indem Sie die Einstellungen des Upstream-Endpunkts ändern.
Regeleinstellungen
Sie können Hubregeln, Kategorieregeln und Ereignisregeln separat festlegen. Die Abgleichsregel unterstützt drei Formate:
- Verwenden Sie ein Sternchen (*), um alle Ereignisse zu vergleichen.
- Verwenden Sie ein Komma (,), um mehrere Ereignisse zu verknüpfen. Beispielsweise entspricht
connected, disconnected
den verbundenen und nicht verbundenen Ereignissen. - Verwenden Sie den vollständigen Namen des Ereignisses, um das Ereignis abzugleichen. Beispielsweise entspricht
connected
dem verbundenen Ereignis.
Hinweis
Wenn Sie Azure Functions mit dem SignalR-Trigger verwenden, macht der SignalR-Trigger einen einzelnen Endpunkt im folgenden Format verfügbar: <Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>
.
Sie können einfach URL-Vorlageneinstellungen mit dieser URL konfigurieren und für die Regeleinstellungen die Standardwerte beibehalten. Ausführliche Informationen zum Finden von <Function_App_URL>
und <API_KEY>
finden Sie unter SignalR Service-Integration.
Authentifizierungseinstellungen
Sie können die Authentifizierung für jede Upstream-Endpunkteinstellung separat konfigurieren. Wenn Sie die Authentifizierung konfigurieren, wird ein Token im Authentication
-Header der Upstreamnachricht festgelegt. Derzeit unterstützt Azure SignalR Service die folgenden Authentifizierungstypen:
None
ManagedIdentity
Wenn Sie ManagedIdentity
auswählen, müssen Sie zuerst eine verwaltete Identität in Azure SignalR Service aktivieren und optional eine Ressource angeben. Weitere Informationen finden Sie unter Verwaltete Identitäten für Azure SignalR Service.
Konfigurieren von Upstream-Endpunkteinstellungen über das Azure-Portal
Hinweis
Die Integration in App Service-Umgebung wird derzeit nicht unterstützt.
- Wechseln Sie zu Azure SignalR Service.
- Wählen Sie Einstellungen aus.
- Ändern Sie den Dienstmodus in Serverlos.
- Fügen Sie unter Upstream-URL-Muster URLs hinzu.
- Wählen Sie Hubregeln aus, um Upstream-Einstellungen zu öffnen.
- Ändern Sie Hubregeln, Ereignisregeln und Kategorieregeln, indem Sie den Regelwert in das entsprechende Feld eingeben.
- Wählen Sie unter Upstream-Authentifizierung die Option
- Verwaltete Identität verwenden aus. (Stellen Sie sicher, dass Sie die verwaltete Identität aktiviert haben)
- Wählen Sie beliebige Optionen unter Zielgruppe im ausgestellten Token aus. Weitere Informationen finden Sie unter Verwaltete Identitäten für Azure SignalR Service.
Konfigurieren von Upstream-Endpunkteinstellungen über eine Resource Manager-Vorlage
Um Upstream-Endpunkteinstellungen unter Verwendung einer Azure Resource Manager-Vorlage zu konfigurieren, legen Sie die Eigenschaft upstream
in der Eigenschaft properties
fest. Der folgende Codeschnipsel zeigt, wie die Eigenschaft upstream
zum Erstellen und Aktualisieren von Upstream-Endpunkteinstellungen festgelegt werden kann.
{
"properties": {
"upstream": {
"templates": [
{
"UrlTemplate": "http://host.com/{hub}/api/{category}/{event}",
"EventPattern": "*",
"HubPattern": "*",
"CategoryPattern": "*",
"Auth": {
"Type": "ManagedIdentity",
"ManagedIdentity": {
"Resource": "<resource>"
}
}
}
]
}
}
}
Serverlose Protokolle
Azure SignalR Service sendet Nachrichten an Endpunkte, die den folgenden Protokollen folgen. Sie können SignalR Service-Triggerbindung mit der Funktions-App verwenden, die diese Protokolle für Sie verarbeitet.
Method
NACHRICHT
Anforderungsheader
Name | Beschreibung |
---|---|
X-ASRS-Connection-Id | Die Verbindungs-ID für die Clientverbindung. |
X-ASRS-Hub | Der Hub, zu dem die Clientverbindung gehört. |
X-ASRS-Category | Die Kategorie, zu der die Nachricht gehört. |
X-ASRS-Event | Das Ereignis, zu dem die Nachricht gehört. |
X-ASRS-Signature | Ein Hash-based Message Authentication Code (HMAC), der zur Validierung verwendet wird. Weitere Informationen finden Sie unter Signatur. |
X-ASRS-User-Claims | Eine Gruppe von Ansprüchen der Clientverbindung. |
X-ASRS-User-Id | Die Benutzeridentität des Clients, der die Nachricht sendet. |
X-ASRS-Client-Query | Die Abfrage der Anforderung, wenn sich Clients mit dem Dienst verbinden. |
Authentifizierung | Ein optionales Token, wenn Sie ManagedIdentity verwenden. |
Anforderungstext
Verbunden
Content-Type: application/json
Getrennt
Content-Type: application/json
Name | Typ | Beschreibung des Dataflows |
---|---|---|
Fehler | Zeichenfolge | Die Fehlermeldung einer geschlossenen Verbindung. Leer, wenn Verbindungen ohne Fehler geschlossen werden. |
Aufrufnachricht
Content-Type: application/json
oder application/x-msgpack
Name | Typ | Beschreibung |
---|---|---|
InvocationId | Zeichenfolge | Eine optionale Zeichenfolge, die eine Aufrufnachricht darstellt. Details finden Sie in den Aufrufen. |
Ziel | Zeichenfolge | Dasselbe wie das Ereignis und das Ziel in einer Aufrufnachricht. |
Argumente | Array von Objekten | Ein Array, das Argumente enthält, die auf die in Target genannte Methode anzuwenden sind. |
Signature
Der Dienst berechnet den SHA256-Code für den X-ASRS-Connection-Id
-Wert, indem er sowohl den primären als auch den sekundären Zugriffsschlüssel als HMAC
-Schlüssel verwendet. Der Dienst legt sie im Header X-ASRS-Signature
fest, wenn HTTP-Anforderungen für einen Upstream-Endpunkt ausgeführt werden:
Hex_encoded(HMAC_SHA256(accessKey, connection-id))