Distribuire un'API WebSocket nel gateway API

Dopo aver creato l'API WebSocket, è necessario distribuirla in modo che possa essere richiamata dagli utenti.

Per distribuire un'API, crea una distribuzione API e associala a una fase. Ogni fase è una snapshot dell'API ed è resa disponibile per essere chiamata dalle app client.

Importante

Ogni volta che aggiorni un'API, devi ripeterne l'implementazione. Le modifiche a qualcosa di diverso dalle impostazioni di fase richiedono una nuova implementazione, incluse le modifiche alle seguenti risorse:

• Route

• Integrazioni

• Authorizers

C'è un limite predefinito di 10 fasi per API. Si consiglia di riutilizzare le fasi per le implementazioni.

Per chiamare un API WebSocket distribuita, il client invia un messaggio all'URL dell'API. L'URL viene determinato dal nome host e dal nome fase dell'API.

Nota

API Gateway supporta payload fino a 128 KB con dimensione del frame massima di 32 KB. Se un messaggio supera i 32 KB, deve essere suddiviso in più frame, ciascuno di 32 KB o più piccolo.

Utilizzando il nome di dominio predefinito dell'API, il formato dell'URL di (ad esempio) un'API WebSocket in una fase specifica ({stageName}) è il seguente:

wss://{api-id}.execute-api.{region}.amazonaws.com/{stageName}

Per rendere l'URL dell'API WebSocket più intuitivo, puoi creare un nome di dominio personalizzato (ad esempio api.example.com) per sostituire il nome host predefinito dell'API. Il processo di configurazione è lo stesso delle API REST. Per ulteriori informazioni, consulta Configurazione di nomi di dominio personalizzati per le API REST.

Le fasi permettono un efficace controllo delle versioni dell'API. Ad esempio, puoi distribuire un'API in una fase test e una fase prod e utilizzare la fase test come build di test e la fase prod come build stabile. Dopo che gli aggiornamenti hanno superato il test, puoi promuovere la fase test alla fase prod. La promozione può essere eseguita ridistribuendo l'API nella fase prod. Per ulteriori dettagli sulle fasi, consulta Configurazione di una fase per un'API REST.

Creazione di una distribuzione API WebSocket mediante AWS CLI

Per utilizzare AWS CLI per creare una distribuzione, utilizza il comando create-deployment come mostrato nell'esempio seguente:

aws apigatewayv2 --region us-east-1 create-deployment --api-id aabbccddee

Output di esempio:

{
    "DeploymentId": "fedcba",
    "DeploymentStatus": "DEPLOYED",
    "CreatedDate": "2018-11-15T06:49:09Z"
}

L'API distribuita non può essere chiamata fino a quando non si associa la distribuzione a una fase. Puoi creare una nuova fase o riutilizzare una fase creata in precedenza.

Per creare una nuova fase e associarla alla distribuzione, utilizza il comando create-stage come mostrato nell'esempio seguente:

aws apigatewayv2 --region us-east-1 create-stage --api-id aabbccddee --deployment-id fedcba --stage-name test

Output di esempio:

{
    "StageName": "test",
    "CreatedDate": "2018-11-15T06:50:28Z",
    "DeploymentId": "fedcba",
    "DefaultRouteSettings": {
        "MetricsEnabled": false,
        "ThrottlingBurstLimit": 5000,
        "DataTraceEnabled": false,
        "ThrottlingRateLimit": 10000.0
    },
    "LastUpdatedDate": "2018-11-15T06:50:28Z",
    "StageVariables": {},
    "RouteSettings": {}
}

Per riutilizzare una fase esistente, aggiorna la proprietà deploymentId della fase con il nuovo ID di distribuzione creato ({deployment-id}) utilizzando il comando update-stage.

 aws apigatewayv2 update-stage --region {region} \
    --api-id {api-id} \ 
    --stage-name {stage-name} \ 
    --deployment-id {deployment-id}

Creazione di una distribuzione API WebSocket mediante la console API Gateway

Per utilizzare la console API Gateway per creare una distribuzione per un'API WebSocket:

1. Accedere alla console API Gateway e scegliere l'API.

2. Seleziona Deploy API (Distribuisci API).

3. Scegliere la fase desiderata dall'elenco a discesa oppure immettere il nome di una nuova fase.