Lavorare con le route per le API WebSocket

Nell'API WebSocket, i messaggi JSON in entrata sono indirizzati a integrazioni di back-end basate sulle route configurate dall'utente. (Messaggi non JSON sono indirizzati a una route $default configurata dall'utente).

Una route include una chiave di route, che è il valore previsto dopo che un'espressione di selezione della route è stata valutata. routeSelectionExpression è un attributo definito a livello di API. Specifica una proprietà JSON che deve essere presente nel payload del messaggio. Per ulteriori informazioni sulle espressioni di selezione della route, consulta Espressioni di selezione dell'instradamento.

Ad esempio, se i messaggi JSON contengono una proprietà action e desideri eseguire operazioni diverse in base a questa proprietà, l'espressione di selezione della route potrebbe essere ${request.body.action}. La tabella di routing specifica quale operazione eseguire abbinando il valore della proprietà action ai valori delle chiavi route personalizzate definiti nella tabella.

Esistono tre route predefinite che possono essere utilizzate: $connect, $disconnect e $default. Inoltre, puoi creare route personalizzate.

• API Gateway chiama la route $connect quando viene avviata una connessione permanente tra il client e un'API WebSocket.

• API Gateway chiama la route $disconnect quando il client o il server si scollega dall'API.

• API Gateway chiama una route personalizzata dopo che l'espressione di selezione della route viene valutata rispetto al messaggio, se viene trovata una route corrispondente; la corrispondenza determina quale integrazione viene richiamata.

• API Gateway chiama la route $default se l'espressione di selezione della route non può essere valutata rispetto al messaggio o se non viene trovata una route corrispondente.

Espressioni di selezione dell'instradamento

Un'espressione di selezione dell'instradamento viene valutata quando il servizio seleziona l'instradamento da seguire per un messaggio in entrata. Il servizio utilizza la route il cui routeKey corrisponde esattamente al valore valutato. Se non trova alcuna corrispondenza ed è disponibile una route con una chiave di routing $default, verrà selezionata. Se nessuna route corrisponde al valore valutato e non è disponibile una route $default, il servizio restituisce un errore. Per le API basate su WebSocket, l'espressione deve avere il formato $request.body.{path_to_body_element}.

Supponiamo, ad esempio, che tu stia inviando il seguente messaggio JSON:

{
    "service" : "chat",
    "action" : "join",
    "data" : {
        "room" : "room1234"
   }
}

Potresti decidere di selezionare il comportamento dell'API in base alla proprietà action. In questo caso, potresti definire la seguente espressione di selezione dell'instradamento:

$request.body.action

In questo esempio, request.body si riferisce al payload JSON del messaggio e .action è un'espressione JSONPath. Puoi utilizzare qualsiasi espressione di percorso JSON dopo request.body, ma tieni presente che il risultato sarà in formato stringa. Se, ad esempio, la tua espressione JSONPath restituisce una matrice di due elementi, questa verrà presentata come stringa "[item1, item2]". Per questo motivo, è opportuno che l'espressione restituisca un valore e non una matrice o un oggetto.

Puoi semplicemente utilizzare un valore statico oppure utilizzare più variabili. La tabella seguente mostra esempi con i relativi risultati valutati per il payload precedente.

Espressione	Risultato valutato	Descrizione
$request.body.action	join	Una variabile da cui è stato rimosso il wrapping
${request.body.action}	join	Una variabile con wrapping
${request.body.service}/${request.body.action}	chat/join	Più variabili con valori statici
${request.body.action}-${request.body.invalidPath}	join-	Se l'espressione JSONPath non viene trovata, la variabile viene risolta come "".
action	action	Valore statico
\$default	$default	Valore statico

Il risultato valutato viene utilizzato per trovare una route. Se esiste una route con una chiave di routing corrispondente, viene selezionato per elaborare il messaggio. Se non è possibile trovare una route corrispondente, API Gateway cerca di trovare la route $default, se disponibile. Se la route $default non è definita, API Gateway restituisce un errore.

Configurazione delle route per un'API WebSocket in API Gateway

Quando crei per la prima volta una nuova API WebSocket, sono disponibili tre instradamenti predefiniti: $connect, $disconnect e $default. Puoi crearli utilizzando la console, l'API o la AWS CLI. Se lo desideri, puoi creare instradamenti personalizzati. Per ulteriori informazioni, consulta Informazioni sulle WebSocket API in API Gateway.

Nota

Nell'interfaccia a riga di comando, puoi creare instradamenti prima o dopo aver creato le integrazioni e puoi riutilizzare la stessa integrazione per più instradamenti.

Creazione di una route tramite la console API Gateway

Per creare una route utilizzando la console API Gateway

1. Accedere alla console API Gateway, scegliere l'API e selezionare Routes (Route).

2. Seleziona Crea instradamento.

3. Per Chiave instradamento inserisci il nome della chiave instradamento. È possibile creare gli instradamenti predefiniti ($connect, $disconnect e $default) o un instradamento personalizzato.

   Nota

   Quando crei un instradamento personalizzato, non utilizzare il prefisso $ nel nome della chiave di instradamento. Questo prefisso è riservato per gli instradamenti predefiniti.

4. Seleziona e configura il tipo di integrazione per l'instradamento. Per ulteriori informazioni, consulta Configurare una richiesta di integrazione WebSocket API utilizzando la console API Gateway.

Creazione di un instradamento mediante la AWS CLI

Per creare un instradamento utilizzando la AWS CLI, chiama create-route come mostrato nell'esempio seguente:

aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default

Output di esempio:

{
    "ApiKeyRequired": false,
    "AuthorizationType": "NONE",
    "RouteKey": "$default",
    "RouteId": "1122334"
}

Specifica delle impostazioni per la richiesta di instradamento per $connect

Quando configuri l'instradamento $connect per la tua API, sono disponibili le seguenti impostazioni facoltative per abilitare l'autorizzazione per l'API. Per ulteriori informazioni, consulta Instradamento $connect.

• Authorization (Autorizzazione): se non è richiesta alcuna autorizzazione, puoi specificare NONE. In caso contrario, puoi specificare:

  • AWS_IAM per utilizzare le policy AWS IAM standard per il controllo dell'accesso all'API.

  • CUSTOM per implementare l'autorizzazione per un'API specificando una funzione di autorizzazione Lambda creata in precedenza. L'autorizzatore può risiedere nel tuo account AWS o in un altro account AWS. Per ulteriori informazioni sui provider di autorizzazioni Lambda, consulta Uso di autorizzazioni Lambda di API Gateway.

    Nota

    Nella console API Gateway, l'impostazione CUSTOM è visibile solo dopo aver configurato una funzione di autorizzazione come descritto in Configurazione di un'autorizzazione Lambda tramite la console API Gateway.

  Importante

  L'impostazione Authorization (Autorizzazione) viene applicata all'intera API, non solo all'instradamento $connect. L'instradamento $connect protegge gli altri instradamenti, perché viene chiamato per ogni connessione.

• API Key Required (Chiave API richiesta): puoi richiedere facoltativamente una chiave API per un instradamento $connect dell'API. Puoi utilizzare le chiavi API insieme ai piani di utilizzo per controllare e tracciare l'accesso alle API. Per ulteriori informazioni, consulta Creazione e utilizzo dei piani di utilizzo con chiavi API.

Configurazione della richiesta di instradamento $connect mediante la console API Gateway

Per configurare la richiesta di instradamento $connect per un'API WebSocket mediante la console API Gateway:

1. Accedere alla console API Gateway, scegliere l'API e selezionare Routes (Route).

2. In Instradamenti scegli $connect o crea un instradamento $connect seguendo Creazione di una route tramite la console API Gateway.

3. Nella sezione Impostazioni della richiesta di instradamento scegli Modifica.

4. Per Autorizzazione seleziona un tipo di autorizzazione.

5. Per richiedere un'API per l'instradamento $connect seleziona Richiedi chiave API.

6. Seleziona Salva modifiche.