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: connections: Ereignisse der Verbindungslebensdauer. Sie wird ausgelöst, wenn eine Clientverbindung hergestellt oder getrennt wird. Sie umfasst verbundene und nicht verbundene Ereignisse. messages: Wird ausgelöst, wenn Clients eine Hubmethode aufrufen. Sie umfasst alle anderen Ereignisse, mit Ausnahme der Ereignisse in der Kategorie connections.
{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

1. 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.

2. 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.

3. 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.

1. Wechseln Sie zu Azure SignalR Service.
2. Wählen Sie Einstellungen aus.
3. Ändern Sie den Dienstmodus in Serverlos.
4. Fügen Sie unter Upstream-URL-Muster URLs hinzu.
5. Wählen Sie Hubregeln aus, um Upstream-Einstellungen zu öffnen.
6. Ändern Sie Hubregeln, Ereignisregeln und Kategorieregeln, indem Sie den Regelwert in das entsprechende Feld eingeben.
7. Wählen Sie unter Upstream-Authentifizierung die Option
8. Verwaltete Identität verwenden aus. (Stellen Sie sicher, dass Sie die verwaltete Identität aktiviert haben)
9. 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))

Nächste Schritte

• Verwaltete Identitäten für Azure SignalR Service
• Azure Functions-Entwicklung und -Konfiguration mit Azure SignalR Service
• Verarbeiten von Nachrichten von SignalR Service (Triggerbindung)
• Beispiel einer SignalR Service-Auslöserbindung