Tutorial: Creación de una API de WebSocket con una integración de AWS

Para crear una pila de AWS CloudFormation

1. Abra la consola de AWS CloudFormation en https://console.aws.amazon.com/cloudformation.

2. Seleccione Create stack (Crear pila) y, a continuación, seleccione With new resources (standard) (Con nuevos recursos [estándar]).

3. En Specify template (Especificar plantilla), elija Upload a template file (Cargar un archivo de plantilla).

4. Seleccione la plantilla que ha descargado.

5. Elija Next (Siguiente).

6. En Stack name (Nombre de pila), escriba websocket-step-functions-tutorial y, a continuación, elija Next (Siguiente).

7. En Configure stack options (Configurar opciones de pila), elija Next (Siguiente).

8. Para Capabilities (Capacidades), sepa que AWS CloudFormation puede crear recursos de IAM en su cuenta.

9. Seleccione Enviar.

Para crear una API de WebSocket

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Seleccione Create API (Crear API). En WebSocket API (API de WebSocket), elija Build (Crear).

3. En API name (Nombre de la API), escribawebsocket-step-functions-tutorial.

4. Para Route selection expression (Expresión de selección de ruta), ingrese request.body.action.

   La expresión de selección de ruta determina la ruta que API Gateway invoca cuando un cliente envía un mensaje.

5. Elija Siguiente.

6. Para Rutas predefinidas, elija Agregar $connect, Agregar $disconnect y Agregar $default.

   Las rutas $connect y $disconnect son rutas especiales que API Gateway invoca automáticamente cuando un cliente se conecta o se desconecta de una API. API Gateway invoca la ruta $default cuando ninguna otra ruta coincide con una solicitud. Creará una ruta personalizada para conectarse a Step Functions después de crear la API.

7. Elija Siguiente.

8. Para Integración para $connect, haga lo siguiente:

   1. Para Tipo de integración, elija Lambda.

   2. Para Función de Lambda, elija la función de Lambda $connect correspondiente que creó con AWS CloudFormation en el paso 1. El nombre de la función de Lambda debe comenzar con websocket-step.

9. Para Integración para $disconnect, haga lo siguiente:

   1. Para Tipo de integración, elija Lambda.

   2. Para Función de Lambda, elija la función de Lambda $disconnect correspondiente que creó con AWS CloudFormation en el paso 1. El nombre de la función de Lambda debe comenzar con websocket-step.

10. Para Integración para $default, elija simulación.

    En una integración simulada, API Gateway administra la respuesta de la ruta sin un backend de integración.

11. Elija Siguiente.

12. Revise la etapa que API Gateway le crea. De forma predeterminada, API Gateway crea una etapa denominada producción e implementa automáticamente la API en esa etapa. Elija Next (Siguiente).

13. Elija Create and deploy (Crear e implementar).

Creación de un autorizador de Lambda

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. En el panel de navegación principal, elija Autorizadores.

3. Elija Creación de un autorizador.

4. Para Nombre del autorizador, ingrese LambdaAuthorizer.

5. Para ARN de autorizador, ingrese el nombre del autorizador creado por la plantilla de AWS CloudFormation. El nombre no debe comenzar por websocket-step-functions-tutorial-AuthorizerHandler.

   nota

   Le recomendamos que no utilice este autorizador de ejemplo para las API de producción.

6. Para Tipo de origen de identidad, elija Encabezado. En Clave, escriba Authorization.

7. Elija Crear autorizador.

Asociación de un autorizador a la ruta de $connect

1. En el panel de navegación principal, elija Rutas.

2. Elija la ruta $connect.

3. En la sección Configuración de la solicitud de ruta, elija Editar.

4. Para Autorización, elija el menú desplegable y, a continuación, seleccione el autorizador de solicitudes.

5. Elija Guardar cambios.

Creación de una integración simulada

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Elija la ruta $default y, a continuación, elija la pestaña Solicitud de integración.

3. Para las Plantillas de solicitud, elija Editar.

4. Para Expresión de selección de plantilla, ingrese 200 y, a continuación, elija Editar.

5. En la pestaña Solicitud de integración, para Plantillas de solicitud, elija Crear plantilla.

6. Para Clave de plantilla, ingrese 200.

7. Para Generar plantilla, ingrese la siguiente plantilla de asignación:

   {"statusCode": 200}

   Seleccione Crear plantilla.

   El resultado debe ser similar a lo siguiente:

   

8. Para el panel de la ruta $default, elija Habilitar la comunicación bidireccional.

9. Elija la pestaña Respuesta de integración y, a continuación, elija Creación de respuesta de integración.

10. Para Clave de respuesta, escriba $default.

11. Para Expresión de selección de plantillas, ingrese 200.

12. Elija Crear respuesta.

13. En Plantillas de respuesta, elija Crear plantilla.

14. Para Clave de plantilla, ingrese 200.

15. Para Plantilla de respuesta, ingrese la siguiente plantilla de asignación:

    {"Use the sendmessage route to send a message. Connection ID: $context.connectionId"}

16. Seleccione Crear plantilla.

    El resultado debe ser similar a lo siguiente:

    

Creación de una integración que no sea de proxy

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Elija Create route (Crear ruta).

3. Para Route key (Clave de ruta), ingrese sendmessage.

4. En Tipo de integración, seleccione Servicio de AWS.

5. Para Región de AWS, ingrese la región en la que implementó la plantilla de AWS CloudFormation.

6. Para Servicio de AWS, elija Step Functions.

7. En HTTP method (Método HTTP), elija POST.

8. En Nombre de la función, introduzca StartExecution.

9. Para Rol de ejecución, ingrese el rol de ejecución creado por la plantilla de AWS CloudFormation. El nombre debe ser WebsocketTutorialApiRole.

10. Elija Create route (Crear ruta).

Para crear una plantilla de mapeo

1. Elija la ruta sendmessage y, a continuación, elija la pestaña Solicitud de integración.

2. En la sección Plantillas de solicitud, elija Editar.

3. Para Expresión de selección de plantillas, ingrese \$default.

4. Elija Editar.

5. En la sección Plantillas de solicitud, elija Crear plantilla.

6. Para Clave de plantilla, ingrese \$default.

7. Para Generar plantilla, ingrese la siguiente plantilla de asignación:

   #set($domain = "$context.domainName")
   #set($stage = "$context.stage")
   #set($body = $input.json('$'))
   #set($getMessage = $util.parseJson($body))
   #set($mymessage = $getMessage.message)
   {
   "input": "{\"domain\": \"$domain\", \"stage\": \"$stage\", \"message\": \"$mymessage\"}",
   "stateMachineArn": "arn:aws:states:us-east-2:123456789012:stateMachine:WebSocket-Tutorial-StateMachine"
   }

   Sustituya stateMachineArn por el ARN de la máquina de estado creada por AWS CloudFormation.

   La plantilla de asignación hace lo siguiente:

   • Crea la variable $domain mediante la variable de contexto domainName.

   • Crea la variable $stage mediante la variable de contexto stage.

     Las variables $domain y $stage son necesarias para crear una URL de devolución de llamada.

   • Toma el mensaje JSON sendmessage entrante y extrae la propiedad de message.

   • Crea la entrada de la máquina de estado. La entrada es el dominio y la etapa de la API de WebSocket y el mensaje de la ruta sendmessage.

8. Seleccione Crear plantilla.

   

Para implementar su API

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. En el panel de navegación principal, elija Rutas.

3. Elija Deploy API (Implementar API).

4. Para Etapa, elija producción.

5. (Opcional) Para Descripción de implementación, ingrese una descripción.

6. Elija Implementar.

Obtención de la URL de invocación para la API

1. Elija la API.

2. Elija Stages (Etapas) y, a continuación, elija production (producción).

3. Tenga en cuenta la WebSocket URL (URL de WebSocket) de la API. La dirección URL debe tener un aspecto similar al siguiente: wss://abcdef123.execute-api.us-east-2.amazonaws.com/production.

Prueba de la conexión a la API

1. Para conectarse a la API, utilice el siguiente comando. En primer lugar, se prueba la conexión invocando la ruta de /ping.

   wscat -c wss://abcdef123.execute-api.us-east-2.amazonaws.com/production -H "Authorization: Allow" --slash -P

   Connected (press CTRL+C to quit)

2. Ingrese el siguiente comando para hacer ping al marco de control. Puede utilizar un marco de control para keepalive los fines del cliente.

   /ping

   El resultado debe ser similar a lo siguiente:

   < Received pong (data: "")

Para probar la API

1. Abra un nuevo terminal y ejecute el comando wscat de nuevo con los siguientes parámetros.

   wscat -c wss://abcdef123.execute-api.us-east-2.amazonaws.com/production -H "Authorization: Allow"

   Connected (press CTRL+C to quit)

2. API Gateway determina qué ruta invocar en función de la expresión de selección de solicitud de rutas de la API. La expresión de selección de rutas de la API es $request.body.action. Como resultado, API Gateway invoca la ruta sendmessage cuando envía el siguiente mensaje:

   {"action": "sendmessage", "message": "hello, from Step Functions!"}

   La máquina de estados de Step Functions asociada a la ruta invoca una función de Lambda con el mensaje y la URL de devolución de llamada. La función de Lambda llama a la API de administración de API Gateway y envía el mensaje a todos los clientes conectados. Todos los clientes reciben el siguiente mensaje:

   < hello, from Step Functions!

Para desconectarse de la API

• Pulse CTRL+C para desconectarse de la API.

  Cuando un cliente se desconecta de la API, API Gateway invoca la ruta $disconnect de la API. La integración de Lambda para la ruta $disconnect de la API elimina el ID de conexión de DynamoDB.

Para eliminar una API de WebSocket

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. En la página de las API, seleccione la websocket-api.

3. Elija Action (Acciones), elija Delete (Eliminar)y, a continuación, confirme su elección.

Para eliminar una pila de AWS CloudFormation

1. Abra la consola de AWS CloudFormation en https://console.aws.amazon.com/cloudformation.

2. Seleccione su pila de AWS CloudFormation.

3. Elija Delete (Eliminar) y, a continuación, confirme su elección.