Share via

Verbinden ion-Zeichenfolgen im Azure SignalR-Dienst

  • Artikel

Ein Verbindungszeichenfolge enthält Informationen zum Herstellen einer Verbindung mit dem Azure SignalR-Dienst. In diesem Artikel lernen Sie die Grundlagen der Verbindungszeichenfolge kennen und erfahren, wie Sie eine in Ihrer Anwendung konfigurieren.

Was ein Verbindungszeichenfolge ist

Wenn eine Anwendung eine Verbindung mit dem Azure SignalR-Dienst herstellen muss, benötigt sie die folgenden Informationen:

  • Der HTTP-Endpunkt der Azure SignalR Service-Instanz
  • Die Möglichkeit, sich beim Dienstendpunkt zu authentifizieren

Eine Verbindungszeichenfolge enthält solche Informationen.

Wie ein Verbindungszeichenfolge aussieht

Ein Verbindungszeichenfolge besteht aus einer Reihe von Schlüssel-Wert-Paaren, die durch Semikolons getrennt sind (;)). Die Zeichenfolge verwendet ein Gleichheitszeichen (=), um jeden Schlüssel und dessen Wert zu verbinden. Bei Schlüsseln wird nicht zwischen Groß- und Kleinschreibung unterschieden.

Ein typisches Verbindungszeichenfolge könnte wie in diesem Beispiel aussehen:

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;Version=1.0;

Die Verbindungszeichenfolge enthält:

  • Endpoint=https://<resource_name>.service.signalr.net: Die Endpunkt-URL der Ressource.
  • AccessKey=<access_key>: Der Schlüssel für die Authentifizierung beim Dienst. Wenn Sie einen Zugriffsschlüssel im Verbindungszeichenfolge angeben, verwendet das Azure SignalR Service SDK es, um ein Token zu generieren, das der Dienst überprüft.
  • Version: Die Version der Verbindungszeichenfolge. Der Standardwert ist 1.0.

In der folgenden Tabelle sind alle gültigen Namen für Schlüssel-Wert-Paare in der Verbindungszeichenfolge aufgeführt:

Schlüssel BESCHREIBUNG Erforderlich Standardwert Beispielswert
Endpoint Die URL Ihrer Azure SignalR-Dienstinstanz. Ja Nicht zutreffend https://foo.service.signalr.net
Port Der Port, auf den Ihre Azure SignalR Service-Instanz lauscht. Nein 80 oder 443, abhängig vom Endpunkt-URI-Schema 8080
Version Die Version eines Verbindungszeichenfolge. Nein 1.0 1.0
ClientEndpoint Der URI Ihres Reverseproxys, z. B. Azure-App lication Gateway oder Azure API Management. Nein null https://foo.bar
AuthType Der Authentifizierungstyp. Standardmäßig verwendet AccessKey der Dienst die Autorisierung von Anforderungen. Die Groß-/Kleinschreibung wird hier nicht beachtet. Nein null Azure, azure.msi, azure.app

Verwenden von AccessKey

Der Dienst verwendet die lokale Authentifizierungsmethode, wenn diese auf null.a0> festgelegt ist.

Schlüssel BESCHREIBUNG Erforderlich Standardwert Beispielswert
AccessKey Die Schlüsselzeichenfolge im Base64-Format zum Erstellen eines Zugriffstokens. Ja null ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/

Verwenden Sie Microsoft Entra ID

Der Dienst verwendet die Microsoft Entra-Authentifizierungsmethode, wenn AuthType diese auf azure, azure.appoder azure.msi.

Schlüssel BESCHREIBUNG Erforderlich Standardwert Beispielswert
ClientId Eine GUID einer Azure-Anwendung oder einer Azure-Identität. Nein null 00000000-0000-0000-0000-000000000000
TenantId Eine GUID einer Organisation in der Microsoft Entra-ID. Nein null 00000000-0000-0000-0000-000000000000
ClientSecret Das Kennwort einer Azure-Anwendungsinstanz Nein null ***********************.****************
ClientCertPath Der absolute Pfad einer Clientzertifikatdatei zu einer Azure-Anwendungsinstanz. Nein null /usr/local/cert/app.cert

Der Dienst verwendet einen anderen TokenCredential Wert, um Microsoft Entra-Token zu generieren, abhängig von den parametern, die Sie angeben:

So erhalten Sie Verbindungszeichenfolge

Sie können die Azure-Portal oder die Azure CLI verwenden, um Verbindungszeichenfolge zu erhalten.

Azure-Portal

Öffnen Sie Ihre Azure SignalR Service-Ressource im Azure-Portal. Auf der Registerkarte "Schlüssel" werden zwei Verbindungszeichenfolge (primär und sekundär) im folgenden Format angezeigt:

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;Version=1.0;

Azure CLI

az signalr key list -g <resource_group> -n <resource_name>

Verbinden mit einer Microsoft Entra-Anwendung

Sie können eine Microsoft Entra-Anwendung verwenden, um eine Verbindung mit Ihrer Azure SignalR-Dienstinstanz herzustellen. Wenn die Anwendung über die berechtigung zum Zugriff auf den Azure SignalR-Dienst verfügt, ist kein Zugriffsschlüssel erforderlich.

Um die Microsoft Entra-Authentifizierung zu verwenden, müssen Sie aus dem Verbindungszeichenfolge entfernen AccessKey und hinzufügenAuthType=azure.app. Sie müssen auch die Anmeldeinformationen Ihrer Microsoft Entra-Anwendung angeben, einschließlich Client-ID, geheimer Clientschlüssel und Mandanten-ID. Die Verbindungszeichenfolge sieht wie im folgenden Beispiel aus:

Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.app;ClientId=<client_id>;ClientSecret=<client_secret>;TenantId=<tenant_id>;Version=1.0;

Weitere Informationen zum Authentifizieren mithilfe einer Microsoft Entra-Anwendung finden Sie unter Autorisieren von Anforderungen an SignalR-Ressourcen mit Microsoft Entra-Anwendungen.

Authentifizieren mit einer verwalteten Identität

Sie können eine vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität verwenden, um sich bei Azure SignalR Service zu authentifizieren.

Um eine vom System zugewiesene Identität zu verwenden, fügen Sie AuthType=azure.msi den Verbindungszeichenfolge hinzu:

Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.msi;Version=1.0;

Das Azure SignalR Service SDK verwendet automatisch die Identität Ihres App-Servers.

Um eine vom Benutzer zugewiesene Identität zu verwenden, schließen Sie die Client-ID der verwalteten Identität in die Verbindungszeichenfolge ein:

Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.msi;ClientId=<client_id>;Version=1.0;

Weitere Informationen zum Konfigurieren verwalteter Identitäten finden Sie unter Autorisieren von Anforderungen an SignalR-Ressourcen mit von Microsoft Entra verwalteten Identitäten.

Hinweis

Es wird dringend empfohlen, verwaltete Identitäten zur Authentifizierung bei Azure SignalR Service zu verwenden, da sie sicherer als Zugriffstasten sind. Wenn Sie keine Zugriffstasten für die Authentifizierung verwenden, sollten Sie sie im Azure-Portal vollständig deaktivieren (wählen Sie "Tastenzugriffsschlüssel>>deaktivieren" aus).

Wenn Sie sich für die Verwendung von Zugriffstasten entscheiden, empfehlen wir, diese regelmäßig zu drehen. Weitere Informationen finden Sie unter Drehen von Zugriffstasten für den Azure SignalR-Dienst.

Verwenden des Verbindungszeichenfolge-Generators

Das manuelle Erstellen von Verbindungszeichenfolge kann mühsam und fehleranfällig sein. Um Fehler zu vermeiden, stellt Azure SignalR Service einen Verbindungszeichenfolge Generator bereit, der Ihnen dabei hilft, eine Verbindungszeichenfolge zu generieren, die Microsoft Entra-Identitäten wie clientId und tenantId. Um das Tool zu verwenden, öffnen Sie Ihre Azure SignalR Service-Instanz in Azure-Portal, und wählen Sie im linken Menü Verbinden ion-Zeichenfolgen aus.

Screenshot that shows the connection string generator for Azure SignalR Service in the Azure portal.

Auf dieser Seite können Sie zwischen Authentifizierungstypen (Zugriffsschlüssel, verwaltete Identität oder Microsoft Entra-Anwendung) auswählen und Informationen wie Clientendpunkt, Client-ID und geheimen Clientschlüssel eingeben. Anschließend wird die Verbindungszeichenfolge automatisch generiert. Sie können sie kopieren und in Ihrer Anwendung verwenden.

Hinweis

Informationen, die Sie eingeben, werden nach dem Verlassen der Seite nicht gespeichert. Sie müssen Ihre Verbindungszeichenfolge kopieren und speichern, um sie in Ihrer Anwendung zu verwenden.

Weitere Informationen dazu, wie Zugriffstoken generiert und überprüft werden, finden Sie im Abschnitt "Authentifizieren über Microsoft Entra-Token" in der REST-API-Referenz zu Azure SignalR Service.for more information about how access tokens are generated and valid, see the Authenticate via Microsoft Entra token section in the Azure SignalR Service data plane REST API reference.

Bereitstellen von Client- und Serverendpunkten

Ein Verbindungszeichenfolge enthält den HTTP-Endpunkt für den App-Server, um eine Verbindung mit dem Azure SignalR-Dienst herzustellen. Der Server gibt den HTTP-Endpunkt an die Clients in einer Aushandlungsantwort zurück, sodass der Client eine Verbindung mit dem Dienst herstellen kann.

In einigen Anwendungen gibt es möglicherweise eine zusätzliche Komponente vor dem Azure SignalR-Dienst. Alle Clientverbindungen müssen zuerst diese Komponente durchlaufen. Beispielsweise ist Azure-App lizenzierungsgateway ein gemeinsamer Dienst, der zusätzliche Netzwerksicherheit bietet.

In solchen Fällen muss der Client eine Verbindung mit einem Endpunkt herstellen, der sich von Azure SignalR Service unterscheidet. Anstatt den Endpunkt manuell auf der Clientseite zu ersetzen, können Sie dem Verbindungszeichenfolge hinzufügenClientEndpoint:

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;ClientEndpoint=https://<url_to_app_gateway>;Version=1.0;

Der App-Server gibt eine Antwort auf die Aushandlungsanforderung des Clients zurück. Die Antwort enthält die richtige Endpunkt-URL für den Client, mit der eine Verbindung hergestellt werden soll. Weitere Informationen zu Clientverbindungen finden Sie unter Internen des Azure SignalR-Diensts.

Wenn der Server versucht, Serververbindungen herzustellen oder REST-APIs an den Dienst aufzurufen, liegt azure SignalR Service möglicherweise auch hinter einem anderen Dienst wie Azure-App lizenzierungsgateway. In diesem Fall können Sie ServerEndpoint verwenden, um den tatsächlichen Endpunkt für Serververbindungen und REST-APIs anzugeben:

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;ServerEndpoint=https://<url_to_app_gateway>;Version=1.0;

Konfigurieren einer Verbindungszeichenfolge in Ihrer Anwendung

Es gibt zwei Möglichkeiten zum Konfigurieren einer Verbindungszeichenfolge in Ihrer Anwendung.

Sie können die Verbindungszeichenfolge beim Aufrufen der AddAzureSignalR() API festlegen:

services.AddSignalR().AddAzureSignalR("<connection_string>");

Sie können auch ohne Argumente aufrufen AddAzureSignalR() . Das Dienst-SDK gibt die Verbindungszeichenfolge aus einer Konfiguration zurück, die in Ihrem Konfigurationsanbieter benannt istAzure:SignalR:ConnectionString.

In einer lokalen Entwicklungsumgebung wird die Konfiguration in einer Datei (appsettings.json oder secrets.json) oder in Umgebungsvariablen gespeichert. Sie können eine der folgenden Möglichkeiten zum Konfigurieren von Verbindungszeichenfolge verwenden:

  • Verwenden Sie einen geheimen .NET-Manager (dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>").
  • Legen Sie eine Umgebungsvariable fest, die auf die Verbindungszeichenfolge benannt istAzure__SignalR__ConnectionString. Die Doppelpunkte müssen durch einen doppelten Unterstrich im Konfigurationsanbieter der Umgebungsvariablen ersetzt werden.

In einer Produktionsumgebung können Sie andere Azure-Dienste verwenden, um Konfigurationen und geheime Schlüssel wie Azure Key Vault und App-Konfiguration zu verwalten. In der Dokumentation erfahren Sie, wie Sie einen Konfigurationsanbieter für diese Dienste einrichten.

Hinweis

Auch wenn Sie eine Verbindungszeichenfolge direkt mithilfe von Code festlegen, wird davon abgeraten, die Verbindungszeichenfolge im Quellcode hart zu codieren. Lesen Sie stattdessen die Verbindungszeichenfolge aus einem geheimen Speicher wie Key Vault und übergeben Sie es an AddAzureSignalR().

Konfigurieren mehrerer Verbindungszeichenfolgen

Mit dem Azure SignalR-Dienst kann der Server gleichzeitig eine Verbindung mit mehreren Dienstendpunkten herstellen, sodass mehr Verbindungen verarbeitet werden können, die über das Limit einer Dienstinstanz hinausgehen. Wenn eine Dienstinstanz nicht mehr vorhanden ist, können Sie die anderen Dienstinstanzen als Sicherung verwenden. Weitere Informationen zur Verwendung mehrerer Instanzen finden Sie unter Scale SignalR Service with multiple instances.

Es gibt zwei Möglichkeiten zum Konfigurieren mehrerer Instanzen:

  • Über Code:

    services.AddSignalR().AddAzureSignalR(options =>
    {
        options.Endpoints = new ServiceEndpoint[]
        {
            new ServiceEndpoint("<connection_string_1>", name: "name_a"),
            new ServiceEndpoint("<connection_string_2>", name: "name_b", type: EndpointType.Primary),
            new ServiceEndpoint("<connection_string_3>", name: "name_c", type: EndpointType.Secondary),
        };
    });

    Sie können jedem Dienstendpunkt einen Namen und Typ zuweisen, um sie später unterscheiden zu können.

  • Durch Konfiguration:

    Sie können jeden unterstützten Konfigurationsanbieter (z. B. geheimer Manager, Umgebungsvariablen oder Schlüsseltresor) verwenden, um Verbindungszeichenfolge zu speichern. Hier ist ein Beispiel, das einen geheimen Manager verwendet:

    dotnet user-secrets set Azure:SignalR:ConnectionString:name_a <connection_string_1>
dotnet user-secrets set Azure:SignalR:ConnectionString:name_b:primary <connection_string_2>
dotnet user-secrets set Azure:SignalR:ConnectionString:name_c:secondary <connection_string_3>

    Sie können jedem Endpunkt einen Namen und einen Typ zuweisen, indem Sie einen anderen Konfigurationsnamen im folgenden Format verwenden:

    Azure:SignalR:ConnectionString:<name>:<type>