Eingabebindung des SignalR-Diensts für Azure Functions

  • Artikel

Bevor ein Client eine Verbindung mit dem Azure SignalR-Dienst herstellen kann, muss er die Endpunkt-URL des Diensts und ein gültiges Zugriffstoken abrufen. Die SignalRConnectionInfo-Eingabebindung erzeugt die Endpunkt-URL des SignalR-Diensts und ein gültiges Token. Beide werden verwendet, um die Verbindung mit dem Dienst herzustellen. Das Token ist nur für einen bestimmten Zeitraum gültig und nur kann für die Authentifizierung eines bestimmten Benutzers bzw. einer bestimmten Benutzerin für eine Verbindung verwendet werden. Daher sollten Sie das Token nicht zwischenspeichern oder für mehrere Clients verwenden. Normalerweise verwenden Sie SignalRConnectionInfo mit einem HTTP-Trigger für Clients, um die Verbindungsinformationen abzurufen.

Weitere Informationen zur Verwendung dieser Bindung zum Erstellen einer Verhandlungsfunktion, die mit einem SignalR-Client-SDK kompatibel ist, finden Sie unter Azure Functions-Entwicklung und -Konfiguration mit Azure SignalR Service. Informationen zu Setup- und Konfigurationsdetails finden Sie in der Übersicht.

Beispiel

Eine C#-Funktion kann mit einem der folgenden C#-Modi erstellt werden:

  • Isoliertes Workermodell: Kompilierte C#-Funktion, die in einem Workerprozess ausgeführt wird, der von der Runtime isoliert ist. Ein isolierter Workerprozess ist erforderlich, um C#-Funktionen zu unterstützen, die in LTS- und Nicht-LTS-Versionen von .NET und .NET Framework ausgeführt werden.
  • In-Process-Modell: Kompilierte C#-Funktion, die im gleichen Prozess wie die Functions-Runtime ausgeführt wird.
  • C#-Skript: Wird hauptsächlich beim Erstellen von C#-Funktionen im Azure-Portal verwendet.

Wichtig

Die Unterstützung für das In-Process-Modell endet am 10. November 2026. Es wird dringend empfohlen, Ihre Apps zum isolierten Workermodell zu migrieren, um den vollständigen Support zu ermöglichen.

Das folgende Beispiel zeigt eine C#-Funktion, die SignalR-Verbindungsinformationen mithilfe der Eingabebindung erwirbt und sie über HTTP zurückgibt.

[Function(nameof(Negotiate))]
public static string Negotiate([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
    [SignalRConnectionInfoInput(HubName = "serverless")] string connectionInfo)
{
    // The serialization of the connection info object is done by the framework. It should be camel case. The SignalR client respects the camel case response only.
    return connectionInfo;
}

Das folgende Beispiel zeigt eine SignalR-Verbindungsinformations-Eingabebindung in der Datei function.json sowie eine Funktion, die die Bindung verwendet, um die Verbindungsinformationen zurückzugeben.

Dies sind die Bindungsdaten für das Beispiel in der Datei function.json:

{
    "type": "signalRConnectionInfo",
    "name": "connectionInfo",
    "hubName": "hubName1",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "direction": "in"
}

Der JavaScript-Code sieht wie folgt aus:

const { app, input } = require('@azure/functions');

const inputSignalR = input.generic({
    type: 'signalRConnectionInfo',
    name: 'connectionInfo',
    hubName: 'hubName1',
    connectionStringSetting: 'AzureSignalRConnectionString',
});

app.post('negotiate', {
    authLevel: 'function',
    handler: (request, context) => {
        return { body: JSON.stringify(context.extraInputs.get(inputSignalR)) }
    },
    route: 'negotiate',
    extraInputs: [inputSignalR],
});

Vollständige PowerShell-Beispiele stehen aus.

Das folgende Beispiel zeigt eine SignalR-Verbindungsinformations-Eingabebindung in der Datei function.json sowie eine Python-Funktion, die die Bindung verwendet, um die Verbindungsinformationen zurückzugeben.

Dies ist der Python-Code:

def main(req: func.HttpRequest, connectionInfoJson: str) -> func.HttpResponse:
    return func.HttpResponse(
        connectionInfoJson,
        status_code=200,
        headers={
            'Content-type': 'application/json'
        }
    )

Das folgende Beispiel zeigt eine Java-Funktion, die SignalR-Verbindungsinformationen mithilfe der Eingabebindung abruft und sie über HTTP zurückgibt.

@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> req,
        @SignalRConnectionInfoInput(
            name = "connectionInfo",
            HubName = "hubName1") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

Verwendung

Authentifizierte Token

Wenn die Funktion von einem authentifizierten Client ausgelöst wird, können Sie dem erzeugten Token einen Benutzer-ID-Anspruch hinzufügen. Mithilfe der App Service-Authentifizierung können Sie einer Funktions-App problemlos eine Authentifizierung hinzufügen.

App Service-Authentifizierung legt HTTP-Header mit den Namen x-ms-client-principal-id und x-ms-client-principal-name fest, die die Clientprinzipal-ID bzw. den Namen des authentifizierten Benutzers enthalten.

Sie können die UserId-Eigenschaft der Bindung mithilfe eines Bindungsausdrucks auf den Wert eines der beiden Header festlegen: {headers.x-ms-client-principal-id} oder {headers.x-ms-client-principal-name}.

[Function("Negotiate")]
public static string Negotiate([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
    [SignalRConnectionInfoInput(HubName = "hubName1", UserId = "{headers.x-ms-client-principal-id}")] string connectionInfo)
{
    // The serialization of the connection info object is done by the framework. It should be camel case. The SignalR client respects the camel case response only.
    return connectionInfo;
}

@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST, HttpMethod.GET },
            authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> req,
        @SignalRConnectionInfoInput(name = "connectionInfo", hubName = "hubName1", userId = "{headers.x-ms-signalr-userid}") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

Die Bindungsdaten in der Datei function.json:

{
    "type": "signalRConnectionInfo",
    "name": "connectionInfo",
    "hubName": "hubName1",
    "userId": "{headers.x-ms-client-principal-id}",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "direction": "in"
}

Der JavaScript-Code sieht wie folgt aus:

const { app, input } = require('@azure/functions');

const inputSignalR = input.generic({
    type: 'signalRConnectionInfo',
    name: 'connectionInfo',
    hubName: 'hubName1',
    connectionStringSetting: 'AzureSignalRConnectionString',
    userId: '{headers.x-ms-client-principal-id}',
});

app.post('negotiate', {
    authLevel: 'function',
    handler: (request, context) => {
        return { body: JSON.stringify(context.extraInputs.get(inputSignalR)) }
    },
    route: 'negotiate',
    extraInputs: [inputSignalR],
});

Vollständige PowerShell-Beispiele stehen aus.

Dies ist der Python-Code:

def main(req: func.HttpRequest, connectionInfo: str) -> func.HttpResponse:
    # connectionInfo contains an access key token with a name identifier
    # claim set to the authenticated user
    return func.HttpResponse(
        connectionInfo,
        status_code=200,
        headers={
            'Content-type': 'application/json'
        }
    )

@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> req,
        @SignalRConnectionInfoInput(
            name = "connectionInfo",
            HubName = "hubName1",
            userId = "{headers.x-ms-client-principal-id}") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

Attribute

Von C#-Bibliotheken des Typs In-Process und Isolierter Workerprozess wird das Attribut verwendet, um die Funktion zu definieren. Vom C#-Skript wird stattdessen die Konfigurationsdatei function.json verwendet.

In der folgenden Tabelle werden die Eigenschaften des SignalRConnectionInfoInput-Attributs erläutert:

Attributeigenschaft BESCHREIBUNG
HubName Erforderlich. Der Hubname.
ConnectionStringSetting Der Name der Anwendungseinstellung, die die Verbindungszeichenfolge des SignalR-Diensts enthält (standardmäßig AzureSignalRConnectionString).
UserId Optional. Die Benutzer-ID einer SignalR-Verbindung. Sie können einen Bindungsausdruck verwenden, um den Wert an einen HTTP-Anforderungsheader oder eine HTTP-Abfrage zu binden.
IdToken Optional. Ein JWT-Token, dessen Ansprüche den Benutzeransprüchen hinzugefügt werden. Es sollte zusammen mit ClaimTypeList verwendet werden. Sie können einen Bindungsausdruck verwenden, um den Wert an einen HTTP-Anforderungsheader oder eine HTTP-Abfrage zu binden.
ClaimTypeList Optional. Eine Liste der Anspruchstypen, durch die die Ansprüche in IdToken gefiltert werden.

Anmerkungen

In der folgenden Tabelle werden die unterstützten Einstellungen für die SignalRConnectionInfoInput-Anmerkung erläutert.

Einstellung BESCHREIBUNG
name Variablenname, der im Funktionscode für das Verbindungsinfoobjekt verwendet wird.
hubName Erforderlich. Der Hubname.
connectionStringSetting Der Name der Anwendungseinstellung, die die Verbindungszeichenfolge des SignalR-Diensts enthält (standardmäßig AzureSignalRConnectionString).
userId Optional. Die Benutzer-ID einer SignalR-Verbindung. Sie können einen Bindungsausdruck verwenden, um den Wert an einen HTTP-Anforderungsheader oder eine HTTP-Abfrage zu binden.
idToken Optional. Ein JWT-Token, dessen Ansprüche den Benutzeransprüchen hinzugefügt werden. Es sollte zusammen mit claimTypeList verwendet werden. Sie können einen Bindungsausdruck verwenden, um den Wert an einen HTTP-Anforderungsheader oder eine HTTP-Abfrage zu binden.
claimTypeList Optional. Eine Liste der Anspruchstypen, durch die die Ansprüche in idToken gefiltert werden.

Anmerkungen

In der folgenden Tabelle werden die unterstützten Einstellungen für die SignalRConnectionInfoInput-Anmerkung erläutert.

Einstellung BESCHREIBUNG
name Variablenname, der im Funktionscode für das Verbindungsinfoobjekt verwendet wird.
hubName Erforderlich. Der Hubname.
connectionStringSetting Der Name der Anwendungseinstellung, die die Verbindungszeichenfolge des SignalR-Diensts enthält (standardmäßig AzureSignalRConnectionString).
userId Optional. Die Benutzer-ID einer SignalR-Verbindung. Sie können einen Bindungsausdruck verwenden, um den Wert an einen HTTP-Anforderungsheader oder eine HTTP-Abfrage zu binden.
idToken Optional. Ein JWT-Token, dessen Ansprüche den Benutzeransprüchen hinzugefügt werden. Es sollte zusammen mit claimTypeList verwendet werden. Sie können einen Bindungsausdruck verwenden, um den Wert an einen HTTP-Anforderungsheader oder eine HTTP-Abfrage zu binden.
claimTypeList Optional. Eine Liste der Anspruchstypen, durch die die Ansprüche in idToken gefiltert werden.

Konfiguration

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json festlegen.

function.json-Eigenschaft BESCHREIBUNG
type Muss auf signalRConnectionInfo festgelegt sein.
direction Muss auf in festgelegt sein.
hubName Erforderlich. Der Hubname.
connectionStringSetting Der Name der Anwendungseinstellung, die die Verbindungszeichenfolge des SignalR-Diensts enthält (standardmäßig AzureSignalRConnectionString).
userId Optional. Die Benutzer-ID einer SignalR-Verbindung. Sie können einen Bindungsausdruck verwenden, um den Wert an einen HTTP-Anforderungsheader oder eine HTTP-Abfrage zu binden.
idToken Optional. Ein JWT-Token, dessen Ansprüche den Benutzeransprüchen hinzugefügt werden. Es sollte zusammen mit claimTypeList verwendet werden. Sie können einen Bindungsausdruck verwenden, um den Wert an einen HTTP-Anforderungsheader oder eine HTTP-Abfrage zu binden.
claimTypeList Optional. Eine Liste der Anspruchstypen, durch die die Ansprüche in idToken gefiltert werden.

Bindungsausdrücke für HTTP-Trigger

Es kommt häufig vor, dass die Werte einiger Attribute der SignalR-Eingabebindung von HTTP-Anforderungen stammen. Daher wird hier erläutert, wie Werte von HTTP-Anforderungen über einen Bindungsausdruck an SignalR-Eingabebindungsattribute gebunden werden.

HTTP-Metadatentyp Bindungsausdruckformat Beschreibung Beispiel
HTTP-Anforderungsabfrage {query.QUERY_PARAMETER_NAME} Bindet den Wert des entsprechenden Abfrageparameters an ein Attribut {query.userName}
Mit dem HTTP-Anforderungsheader. {headers.HEADER_NAME} Bindet den Wert eines Headers an ein Attribut {headers.token}

Nächste Schritte