Liaisons d’entrée SignalR Service pour Azure Functions

  • Article

Avant qu’un client puisse se connecter au service SignalR Azure, il doit récupérer l’URL du point de terminaison du service et un jeton d’accès valide. La liaison d’entrée SignalRConnectionInfo génère l’URL du point de terminaison du service SignalR et un jeton valide qui sont utilisés pour se connecter au service. Le jeton est limité dans le temps et peut être utilisé pour authentifier un utilisateur spécifique à une connexion. Par conséquent, vous ne devez pas mettre en cache le jeton ou le partager entre les clients. Généralement, vous utilisez SignalRConnectionInfo avec un déclencheur HTTP pour que les clients récupèrent les informations de connexion.

Pour plus d'informations sur l'utilisation de cette liaison pour créer une fonction de « négociation » compatible avec un SDK client SignalR, consultez Développement et configuration d'Azure Functions avec Azure SignalR Service. Pour plus d’informations sur les détails d’installation et de configuration, consultez la vue d’ensemble.

Exemple

Une fonction C# peut être créée à l’aide de l’un des modes C# suivants :

  • Modèle worker isolé : fonction C# compilée exécutée dans un processus worker isolé du runtime. Le processus Worker isolé est requis pour prendre en charge les fonctions C# exécutées sur les versions LTS et non-LTS de .NET et de .NET Framework.
  • Modèle In-process : fonction C# compilée exécutée dans le même processus que le runtime Functions.
  • Script C# : principalement utilisé lors de la création de fonctions C# dans le portail Azure.

Important

La prise en charge du modèle in-process prendra fin le 10 novembre 2026. Pour continuer à bénéficier d’une prise en charge complète, nous vous recommandons vivement de migrer vos applications vers le modèle Worker isolé.

L’exemple suivant montre une fonction C# qui acquiert des informations de connexion SignalR à l’aide de la liaison d’entrée et les renvoie via HTTP.

[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;
}

L’exemple suivant montre une liaison d’entrée d’informations de connexion SignalR dans un fichier function.json et une fonction qui utilise la liaison pour retourner les informations de connexion.

Voici les données de liaison pour l’exemple du fichier function.json :

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

Voici le code JavaScript :

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],
});

Des exemples PowerShell complets sont à venir.

L’exemple suivant montre une liaison d’entrée d’informations de connexion SignalR dans un fichier function.json et une fonction Python qui utilise la liaison pour retourner les informations de connexion.

Voici le code Python :

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

L’exemple suivant montre une fonction Java qui acquiert des informations de connexion SignalR à l’aide de la liaison d’entrée et les renvoie via HTTP.

@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;
}

Utilisation

Jetons authentifiés

Lorsqu'un client authentifié déclenche la fonction, vous pouvez ajouter une revendication d'ID utilisateur au jeton généré. Vous pouvez facilement ajouter l’authentification à une application de fonction à l’aide de Authentification App Service.

L’authentification App Service définit les en-têtes HTTP nommés x-ms-client-principal-id et x-ms-client-principal-name qui contiennent l’identité principale du client et le nom de l’utilisateur authentifié, respectivement.

Vous pouvez définir la propriété UserId de la liaison sur la valeur de l’un des en-têtes à l’aide d’une expression de liaison : {headers.x-ms-client-principal-id} ou {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;
}

Voici les données de liaison dans le fichier 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"
}

Voici le code JavaScript :

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],
});

Des exemples PowerShell complets sont à venir.

Voici le code Python :

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;
}

Attributs

Les bibliothèques C# in-process et de processus Worker isolés utilisent des attributs pour définir la fonction. Le script C# utilise à la place un fichier config function.json.

Le tableau ci-dessous explique les propriétés de l’attribut SignalRConnectionInfoInput :

Propriété d’attribut Description
HubName Obligatoire. Nom du hub.
ConnectionStringSetting Nom du paramètre d’application contenant la chaîne de connexion SignalR Service, dont la valeur par défaut est AzureSignalRConnectionString.
UserId facultatif. L'identifiant d'utilisateur d'une connexion SignalR. Vous pouvez utiliser une expression de liaison pour lier la valeur à un en-tête de requête HTTP ou à une requête.
IdToken facultatif. Un jeton JWT dont les revendications seront ajoutées aux revendications de l'utilisateur. Il doit être utilisé avec ClaimTypeList. Vous pouvez utiliser une expression de liaison pour lier la valeur à un en-tête de requête HTTP ou à une requête.
ClaimTypeList facultatif. Une liste de types de revendications, qui filtrent les revendications dans IdToken .

Annotations

Le tableau suivant décrit les paramètres pris en charge pour l'annotation SignalRConnectionInfoInput.

Paramètre Description
name Nom de variable utilisé dans le code de fonction pour l’objet d’informations de connexion.
hubName Obligatoire. Nom du hub.
connectionStringSetting Nom du paramètre d’application contenant la chaîne de connexion SignalR Service, dont la valeur par défaut est AzureSignalRConnectionString.
userId facultatif. L'identifiant d'utilisateur d'une connexion SignalR. Vous pouvez utiliser une expression de liaison pour lier la valeur à un en-tête de requête HTTP ou à une requête.
idToken facultatif. Un jeton JWT dont les revendications seront ajoutées aux revendications de l'utilisateur. Il doit être utilisé avec claimTypeList. Vous pouvez utiliser une expression de liaison pour lier la valeur à un en-tête de requête HTTP ou à une requête.
claimTypeList facultatif. Une liste de types de revendications, qui filtrent les revendications dans idToken .

Annotations

Le tableau suivant décrit les paramètres pris en charge pour l'annotation SignalRConnectionInfoInput.

Paramètre Description
name Nom de variable utilisé dans le code de fonction pour l’objet d’informations de connexion.
hubName Obligatoire. Nom du hub.
connectionStringSetting Nom du paramètre d’application contenant la chaîne de connexion SignalR Service, dont la valeur par défaut est AzureSignalRConnectionString.
userId facultatif. L'identifiant d'utilisateur d'une connexion SignalR. Vous pouvez utiliser une expression de liaison pour lier la valeur à un en-tête de requête HTTP ou à une requête.
idToken facultatif. Un jeton JWT dont les revendications seront ajoutées aux revendications de l'utilisateur. Il doit être utilisé avec claimTypeList. Vous pouvez utiliser une expression de liaison pour lier la valeur à un en-tête de requête HTTP ou à une requête.
claimTypeList facultatif. Une liste de types de revendications, qui filtrent les revendications dans idToken .

Configuration

Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier function.json.

Propriété function.json Description
type Cette propriété doit être définie sur signalRConnectionInfo.
direction Cette propriété doit être définie sur in.
hubName Obligatoire. Nom du hub.
connectionStringSetting Nom du paramètre d’application contenant la chaîne de connexion SignalR Service, dont la valeur par défaut est AzureSignalRConnectionString.
userId facultatif. L'identifiant d'utilisateur d'une connexion SignalR. Vous pouvez utiliser une expression de liaison pour lier la valeur à un en-tête de requête HTTP ou à une requête.
idToken facultatif. Un jeton JWT dont les revendications seront ajoutées aux revendications de l'utilisateur. Il doit être utilisé avec claimTypeList. Vous pouvez utiliser une expression de liaison pour lier la valeur à un en-tête de requête HTTP ou à une requête.
claimTypeList facultatif. Une liste de types de revendications, qui filtrent les revendications dans idToken .

Expressions de liaison pour le déclencheur HTTP

Il est courant que les valeurs de certains attributs de la liaison d'entrée SignalR proviennent de requêtes HTTP. Par conséquent, nous montrons comment lier les valeurs des requêtes HTTP aux attributs de liaison d'entrée SignalR via l'expression de liaison.

Type de métadonnées HTTP Format d'expression de liaison Description Exemple
Requête de requête HTTP {query.QUERY_PARAMETER_NAME} Lie la valeur du paramètre de requête correspondant à un attribut {query.userName}
En-tête de requête HTTP {headers.HEADER_NAME} Lie la valeur d'un en-tête à un attribut {headers.token}

Étapes suivantes