Freigeben über

Referenz zur REST-API des Azure SignalR-Diensts für die Datenebene

  • Artikel

Neben dem klassischen Client-/Servermuster bietet Azure SignalR Service eine Reihe von REST-APIs, die Ihnen dabei helfen, Echtzeitfunktionen in Ihre serverlose Architektur zu integrieren.

Hinweis

Azure SignalR Service unterstützt die Verwendung von REST-APIs nur zum Verwalten von Clients, die über ASP.NET Core SignalR verbunden sind. Clients, die über ASP.NET SignalR verbunden sind, verwenden ein anderes Datenprotokoll, das derzeit nicht unterstützt wird.

Typische serverlose Architektur mit Azure-Funktionen

Das folgende Diagramm zeigt eine typische serverlose Architektur, die Azure SignalR Service mit Azure Functions verwendet.

Diagramm einer typischen serverlosen Architektur für Azure SignalR Service.

  • Die negotiate Funktion gibt eine Aushandlungsantwort zurück und leitet alle Clients an azure SignalR Service weiter.
  • Die broadcast Funktion ruft die REST-API für Azure SignalR Service auf. Der Azure SignalR-Dienst sendet die Nachricht an alle verbundenen Clients.

In einer serverlosen Architektur verfügen Clients über dauerhafte Verbindungen mit dem Azure SignalR-Dienst. Da kein Anwendungsserver zur Verarbeitung des Datenverkehrs vorhanden ist, befinden sich Clients im LISTEN Modus. In diesem Modus können Clients Nachrichten empfangen, aber keine Nachrichten senden. Der Azure SignalR-Dienst trennt jeden Client, der Nachrichten sendet, da es sich um einen ungültigen Vorgang handelt.

Sie finden ein vollständiges Beispiel für die Verwendung des Azure SignalR-Diensts mit Azure Functions in diesem GitHub-Repository.

Implementieren des Aushandlungsendpunkts

Sie sollten eine negotiate Funktion implementieren, die eine Umleitungsverhandlungsantwort zurückgibt, damit Clients eine Verbindung mit dem Dienst herstellen können.

Eine typische Aushandlungsantwort hat dieses Format:

{
  "url": "https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
  "accessToken": "<a typical JWT token>"
}

Der accessToken Wert wird über den im Authentifizierungsbereich beschriebenen Algorithmus generiert. Der einzige Unterschied besteht darin, dass der aud Anspruch gleich sein sollte wie url.

Sie sollten Ihre Aushandlungs-API https://<hub_url>/negotiate hosten, damit Sie weiterhin einen SignalR-Client verwenden können, um eine Verbindung mit der Hub-URL herzustellen. Weitere Informationen zum Umleiten von Clients an den Azure SignalR-Dienst in Clientverbindungen.

REST-API-Versionen

In der folgenden Tabelle sind alle unterstützten REST-API-Versionen aufgeführt. Außerdem wird die Swagger-Datei für jede API-Version bereitgestellt.

API-Version Status Port Dokumentation Spezifikation
20220601 Neueste Version Standard Artikel Swagger-Datei
1.0 Stable Standard Artikel Swagger-Datei
1.0-preview Veraltet Standard Artikel Swagger-Datei

In der folgenden Tabelle sind die verfügbaren APIs aufgeführt.

API Pfad
Übertragen einer Nachricht an alle Clients, die mit dem Zielhub verbunden sind POST /api/v1/hubs/{hub}
Übertragen einer Nachricht an alle Clients, die dem Zielbenutzer angehören POST /api/v1/hubs/{hub}/users/{id}
Nachricht an die bestimmte Verbindung senden POST /api/v1/hubs/{hub}/connections/{connectionId}
Überprüfen, ob die Verbindung mit der angegebenen Verbindungs-ID vorhanden ist GET /api/v1/hubs/{hub}/connections/{connectionId}
Schließen der Clientverbindung DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Übertragen einer Nachricht an alle Clients innerhalb der Zielgruppe POST /api/v1/hubs/{hub}/groups/{group}
Überprüfen, ob in der angegebenen Gruppe Clientverbindungen vorhanden sind GET /api/v1/hubs/{hub}/groups/{group}
Überprüfen, ob für den angegebenen Benutzer Clientverbindungen verbunden sind GET /api/v1/hubs/{hub}/users/{user}
Hinzufügen einer Verbindung zur Zielgruppe PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Entfernen einer Verbindung aus der Zielgruppe DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Überprüfen, ob ein Benutzer in der Zielgruppe vorhanden ist GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Hinzufügen eines Benutzers zur Zielgruppe PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Entfernen eines Benutzers aus der Zielgruppe DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Entfernen eines Benutzers aus allen Gruppen DELETE /api/v1/hubs/{hub}/users/{user}/groups

Verwenden der REST-API

Authentifizierung über AccessKey im Azure SignalR-Dienst

In jeder HTTP-Anforderung ist ein Autorisierungsheader mit einem JSON-Webtoken (JWT) erforderlich, um sich bei Azure SignalR Service zu authentifizieren.

Signaturalgorithmus und Signatur

HS256 (HMAC-SHA256) wird als Signaturalgorithmus verwendet.

Verwenden Sie den AccessKey Wert in der Verbindungszeichenfolge der Azure SignalR-Dienstinstanz, um das generierte JWT zu signieren.

Ansprüche

Die folgenden Ansprüche müssen im JWT enthalten sein.

Anspruchstyp Ist erforderlich Beschreibung
aud true Muss mit Ihrer HTTP-Anforderungs-URL identisch sein, nicht einschließlich des nachgestellten Schrägstrichs und der Abfrageparameter. Die Zielgruppe einer Übertragungsanforderung sollte beispielsweise wie folgt aussehen: https://example.service.signalr.net/api/v1/hubs/myhub.
exp true Zeitpunkt in Unixzeit (Epoch), zu der dieses Token abläuft.

Authentifizierung über Microsoft Entra-Token

Ähnlich wie bei der Authentifizierung AccessKeyüber ist ein JWT erforderlich, um eine HTTP-Anforderung mithilfe eines Microsoft Entra-Tokens zu authentifizieren.

Der Unterschied besteht darin, dass in diesem Szenario die Microsoft Entra-ID das JWT generiert. Weitere Informationen finden Sie unter "Informationen zum Generieren von Microsoft Entra-Token".

Der verwendete Anmeldeinformationsbereich sollte https://signalr.azure.com/.default sein.

Sie können auch die rollenbasierte Zugriffssteuerung (RBAC) verwenden, um die Anforderung von Ihrem Client oder Server an Azure SignalR Service zu autorisieren. Weitere Informationen finden Sie unter Autorisieren des Zugriffs mit Microsoft Entra ID für Azure SignalR Service.

Um die benutzerbezogene REST-API aufzurufen, sollte jeder Ihrer Clients sich selbst für den Azure SignalR-Dienst identifizieren. Andernfalls kann der Azure SignalR-Dienst keine Zielverbindungen aus der Benutzer-ID finden.

Sie können die Clientidentifikation erreichen, indem Sie einen nameid Anspruch in das JWT jedes Clients einschließen, wenn es eine Verbindung mit dem Azure SignalR-Dienst herstellt. Azure SignalR Service verwendet dann den Wert des nameid Anspruchs als Benutzer-ID für jede Clientverbindung.

Beispiel

In diesem GitHub-Repository finden Sie eine vollständige Konsolen-App, um zu veranschaulichen, wie Sie manuell eine REST-API-HTTP-Anforderung in Azure SignalR Service erstellen.

Sie können auch Microsoft.Azure.SignalR.Management verwenden, um Nachrichten mithilfe der ähnlichen Schnittstellen in IHubContextAzure SignalR Service zu veröffentlichen. Beispiele finden Sie in diesem GitHub-Repository. Weitere Informationen finden Sie unter Azure SignalR Service Management SDK.

Begrenzungen

Derzeit gelten die folgenden Einschränkungen für REST-API-Anforderungen:

  • Die Headergröße darf maximal 16 KB betragen.
  • Die Textkörpergröße darf maximal 1 MB betragen.

Wenn Sie Nachrichten senden möchten, die größer als 1 MB sind, verwenden Sie das Service Management SDK im persistent Modus.