Gestion des utilisateurs et des applications client connectées : routes $connect et $disconnect - Amazon API Gateway
Route $connectTransmission des informations de connexion depuis la route $connectRoute $disconnect

Gestion des utilisateurs et des applications client connectées : routes $connect et $disconnect

La section suivante décrit comment utiliser les routes $connect et $disconnect pour votre API WebSocket.

Route $connect

Les applications client se connectent à votre API WebSocket en envoyant une demande de mise à niveau WebSocket. Si la demande aboutit, la route $connect est exécutée pendant l’établissement de la connexion.

Étant donné que la connexion WebSocket est une connexion avec état, vous pouvez configurer l’autorisation sur la route $connect uniquement. AuthN/AuthZ sera effectué uniquement au moment de la connexion.

Tant que l’exécution de l’intégration associée à la route $connect n’est pas terminée, la demande est en attente de mise à niveau et la connexion n’est pas établie. Si la demande $connect échoue (par exemple, en raison de l’échec de AuthN/AuthZ ou de l’intégration), la connexion ne sera pas établie.

Note

Si l’autorisation échoue sur $connect, la connexion ne sera pas établie, et le client recevra une réponse 401 ou 403.

La configuration d’une intégration pour $connect est facultative. Vous devez envisager la configuration d’une intégration $connect dans les cas suivants :

  • Vous souhaitez permettre aux clients de spécifier des sous-protocoles à l’aide du champ Sec-WebSocket-Protocol. Pour obtenir un exemple de code, consultez Configuration d’une route $connect exigeant un sous-protocole WebSocket.

  • Vous souhaitez être averti lorsque des clients se connectent.

  • Vous souhaitez limiter les connexions ou contrôler qui se connecte.

  • Vous voulez que votre serveur principal renvoie des messages aux clients à l’aide d’une URL de rappel.

  • Vous souhaitez stocker chaque ID de connexion et d’autres informations dans une base de données (par exemple, Amazon DynamoDB).

Transmission des informations de connexion depuis la route $connect

Vous pouvez utiliser des intégrations de proxy et autres que de proxy pour transmettre les informations de la route $connect vers une base de données ou un autre Service AWS.

Pour transmettre les informations de connexion en utilisant une intégration de proxy

Vous pouvez accéder aux informations de connexion d’une intégration proxy Lambda dans l’événement. Utilisez un autre Service AWS ou une autre fonction AWS Lambda à adresser à la connexion.

La fonction Lambda suivante montre comment utiliser l’objet requestContext pour enregistrer l’ID de connexion, le nom de domaine, le nom d’étape et les chaînes de requête dans un journal.

Node.js
 export const handler = async(event, context) => {
    const connectId = event["requestContext"]["connectionId"]
    const domainName = event["requestContext"]["domainName"]
    const stageName = event["requestContext"]["stage"]
    const qs = event['queryStringParameters']
    console.log('Connection ID: ', connectId, 'Domain Name: ', domainName, 'Stage Name: ', stageName, 'Query Strings: ', qs )
    return {"statusCode" : 200}
};
Python
import json
import logging
logger = logging.getLogger()
logger.setLevel("INFO")


def lambda_handler(event, context):
    connectId = event["requestContext"]["connectionId"]
    domainName = event["requestContext"]["domainName"]
    stageName = event["requestContext"]["stage"]
    qs = event['queryStringParameters']
    connectionInfo = {
        'Connection ID': connectId,
        'Domain Name': domainName,
        'Stage Name': stageName,
        'Query Strings': qs}
    logging.info(connectionInfo)
    return {"statusCode": 200}

Pour transmettre les informations de connexion en utilisant une intégration autre que de proxy

  • Vous pouvez accéder aux informations de connexion avec une intégration autre que de proxy. Configurez la demande d’intégration et fournissez un modèle de demande d’API WebSocket. Le modèle de mappage VTL (Velocity Template Language) suivant fournit une demande d’intégration. Cette demande envoie les informations suivantes à une intégration autre que de proxy :

    • ID de connexion

    • Nom de domaine

    • Nom de l’environnement

    • Chemin

    • En-têtes

    • Chaînes de requête

    Cette demande envoie l’ID de connexion, le nom de domaine, le nom d’étape, les chemins, les en-têtes et les chaînes de requête à une intégration autre que de proxy.

    {
    "connectionId": "$context.connectionId",
    "domain": "$context.domainName",
    "stage": "$context.stage",
    "params": "$input.params()"
}

    Pour obtenir plus d’informations sur la configuration des transformations de données, consultez Transformations de données pour les API WebSocket dans API Gateway.

    Pour terminer la demande d’intégration, définissez StatusCode: 200 pour la réponse d’intégration. Pour en savoir plus sur la configuration d’une réponse d’intégration, consultez Configuration d’une réponse d’intégration à l’aide de la console API Gateway.

Route $disconnect

La route $disconnect est exécutée une fois que la connexion est fermée.

La connexion peut être fermée par le serveur ou par le client. Comme la connexion est déjà fermée lorsqu’elle est exécutée, $disconnect est un événement exécuté au mieux de ce qui est possible. API Gateway fera de son mieux pour fournir l’événement $disconnect à votre intégration, mais il ne peut pas garantir sa fourniture.

Le serveur principal peut lancer la déconnexion à l’aide de l’API @connections. Pour plus d’informations, consultez Utilisation des commandes @connections dans votre service backend.