Implementa le WebSocket API in API Gateway

Dopo aver creato l' WebSocket API, devi distribuirla per renderla disponibile per 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' WebSocket API 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, l'URL di (ad esempio) un' WebSocket API in una determinata fase ({stageName}) ha il seguente formato:

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

Per rendere l'URL dell' WebSocket API 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 Nome di dominio personalizzato per REST APIs in API Gateway.

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 Prepara un palco per un REST API in API Gateway.

Crea una distribuzione WebSocket dell'API utilizzando il AWS CLI

AWS CLI Per creare una distribuzione, utilizzate il comando create-deployment come illustrato 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, utilizzate 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 deploymentId proprietà della fase con l'ID di distribuzione appena 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}

Creare una distribuzione WebSocket API utilizzando la console API Gateway

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

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.