Tutorial: Creación de una API de REST como proxy de Amazon Kinesis

Para crear el rol de ejecución del proxy de servicio de AWS

1. Inicie sesión en AWS Management Console Management Console y abra la consola IAM en https://console.aws.amazon.com/iam/.

2. Elija Roles.

3. Elija Crear rol.

4. Elija Servicio de AWS en Seleccionar el tipo de entidad de confianza y, a continuación, elija API Gateway y seleccione Permite que API Gateway envíe registros a CloudWatch Logs.

5. Seleccione Siguiente y de nuevo Siguiente.

6. En Role name (Nombre de rol), escriba APIGatewayKinesisProxyPolicy y luego elija Create role (Crear rol).

7. En la lista Roles (Roles), elija el rol que acaba de crear. Puede que tenga que desplazarse o usar la barra de búsqueda para encontrar el rol.

8. Para el rol seleccionado, seleccione la pestaña Agregar permisos.

9. Elija Adjuntar políticas en la lista desplegable.

10. En la barra de búsqueda, escriba AmazonKinesisFullAccess y, a continuación, elija Añadir permisos.

    nota

    Para simplificar el proceso, este tutorial utiliza una política administrada. Como práctica recomendada, se deben crear políticas de IAM propias para otorgar los permisos mínimos requeridos.

11. Anote el ARN del rol recién creado, ya que lo usará más adelante.

Para crear una API como un proxy de servicio de AWS para Kinesis

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

2. Si es la primera vez que utiliza API Gateway, verá una página en la que aparecen las características del servicio. En REST API, elija Build (Compilación). Cuando aparezca el menú emergente Create Example API (Crear API de ejemplo), elija OK (Aceptar).

   Si esta no es la primera vez que utiliza API Gateway, elija Create API (Crear API). En REST API, elija Build (Compilación).

3. Elija New API (Nueva API).

4. En API name (Nombre de la API), escriba KinesisProxy. Mantenga los valores predeterminados en todos los demás campos.

5. (Opcional) En Description (Descripción), introduzca una descripción.

6. Seleccione Create API (Crear API).

Para listar los flujos de Kinesis con la consola de API Gateway

1. Seleccione el recurso / y, a continuación, elija Crear recurso.

2. En Nombre del recurso, escriba streams.

3. Mantenga desactivado CORS (uso compartido de recursos entre orígenes).

4. Elija Crear recurso.

5. Elija el recurso /streams y luego Crear método. A continuación, haga lo siguiente:

   1. En Tipo de método, seleccione GET.

      nota

      El verbo HTTP de un método invocado por un cliente puede ser diferente del verbo HTTP de una integración requerida por el backend. Aquí elegimos GET porque mostrar los flujos es intuitivamente una operación READ.

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

   3. En Región de AWS, seleccione la Región de AWS donde creó el flujo de Kinesis.

   4. En Servicio de AWS, seleccione Kinesis.

   5. Deje Subdominio de AWS en blanco.

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

      nota

      Aquí elegimos POST porque Kinesis requiere que la acción ListStreams también se invoque.

   7. En Tipo de acción, elija Usar nombre de acción.

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

   9. En Rol de ejecución, escriba el ARN del rol de ejecución.

   10. Deje el valor predeterminado Acceso directo en Tratamiento de contenido.

   11. Elija Crear método.

6. En la pestaña Solicitud de integración, en Configuración de la solicitud de integración, seleccione Editar.

7. En Acceso directo de cuerpo de la solicitud, elija Cuando no haya plantillas definidas (recomendado).

8. Elija Parámetros de encabezados de consulta de URL y luego haga lo siguiente:

   1. Seleccione Añadir parámetros de encabezados de solicitud.

   2. En Nombre, escriba Content-Type.

   3. En Mapeado de, introduzca 'application/x-amz-json-1.1'.

   Hemos utilizado un mapeo de parámetros de solicitud para definir el encabezado Content-Type en el valor estático 'application/x-amz-json-1.1' para informar a Kinesis de que la entrada es de una versión específica de JSON.

9. Elija Plantillas de mapeo y, a continuación, elija Agregar plantilla de mapeo y haga lo siguiente:

   1. En Content-Type, indique application/json.

   2. En Cuerpo de plantilla, escriba {}.

   3. Seleccione Guardar.

   La solicitud ListStreams toma una carga con el siguiente formato JSON:

   
   {
       "ExclusiveStartStreamName": "string",
       "Limit": number
   }
                       

   Sin embargo, las propiedades son opcionales. Para utilizar los valores predeterminados, usamos aquí una carga JSON vacía.

10. Pruebe el método GET en el recurso /streams para invocar la acción ListStreams en Kinesis:

    Elija la pestaña Prueba. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.

    Elija Prueba para probar su método.

    Si ya ha creado dos flujos llamados "myStream" y "yourStream" en Kinesis, la prueba realizada correctamente devolverá una respuesta 200 OK que contiene la siguiente carga:

    
    {
         "HasMoreStreams": false,
         "StreamNames": [
             "myStream",
             "yourStream"
         ]
    }            
                        

Para crear un recurso {stream-name}

1. Elija el recurso /streams y, a continuación, elija Crear recurso.

2. Mantenga Recurso proxy desactivado.

3. En Ruta de recurso, seleccione /streams.

4. En Nombre del recurso, escriba {stream-name}.

5. Mantenga desactivado CORS (uso compartido de recursos entre orígenes).

6. Elija Crear recurso.

Para configurar y probar el método GET en un recurso de flujo

1. Elija el recurso /{stream-name} y, a continuación, elija Crear método.

2. En Tipo de método, seleccione GET.

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

4. En Región de AWS, seleccione la Región de AWS donde creó el flujo de Kinesis.

5. En Servicio de AWS, seleccione Kinesis.

6. Deje Subdominio de AWS en blanco.

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

8. En Tipo de acción, elija Usar nombre de acción.

9. En Nombre de la función, introduzca DescribeStream.

10. En Rol de ejecución, escriba el ARN del rol de ejecución.

11. Deje el valor predeterminado Acceso directo en Tratamiento de contenido.

12. Elija Crear método.

13. En la sección Solicitud de integración, añada los siguientes Parámetros de encabezados de solicitudes de URL:

    Content-Type: 'x-amz-json-1.1'

    La tarea sigue el mismo procedimiento para configurar el mapeo del parámetro de solicitud que el método GET /streams.

14. Añada la siguiente plantilla de mapeo de cuerpo para mapear los datos de la solicitud del método GET /streams/{stream-name} a la solicitud de integración POST /?Action=DescribeStream:

    {
        "StreamName": "$input.params('stream-name')"
    }

    Esta plantilla de mapeo genera la carga de la solicitud de integración necesaria para la acción DescribeStream de Kinesis a partir del valor del parámetro de ruta stream-name de la solicitud de método.

15. Para probar el método GET /stream/{stream-name} para invocar la acción DescribeStream en Kinesis, seleccione la pestaña Prueba.

16. En Ruta, en stream-name, introduzca el nombre de un flujo de Kinesis existente.

17. Seleccione Probar. Si la prueba tiene éxito, se devuelve la respuesta 200 OK con una carga similar a la siguiente:

    {
      "StreamDescription": {
        "HasMoreShards": false,
        "RetentionPeriodHours": 24,
        "Shards": [
          {
            "HashKeyRange": {
              "EndingHashKey": "68056473384187692692674921486353642290",
              "StartingHashKey": "0"
            },
            "SequenceNumberRange": {
              "StartingSequenceNumber": "49559266461454070523309915164834022007924120923395850242"
            },
            "ShardId": "shardId-000000000000"
          },
          ...
          {
            "HashKeyRange": {
              "EndingHashKey": "340282366920938463463374607431768211455",
              "StartingHashKey": "272225893536750770770699685945414569164"
            },
            "SequenceNumberRange": {
              "StartingSequenceNumber": "49559266461543273504104037657400164881014714369419771970"
            },
            "ShardId": "shardId-000000000004"
          }
        ],
        "StreamARN": "arn:aws:kinesis:us-east-1:12345678901:stream/myStream",
        "StreamName": "myStream",
        "StreamStatus": "ACTIVE"
      }
    }

    Después de implementar la API, puede realizar una solicitud REST a este método de la API:

    
    GET https://your-api-id.execute-api.region.amazonaws.com/stage/streams/myStream HTTP/1.1
    Host: your-api-id.execute-api.region.amazonaws.com
    Content-Type: application/json
    Authorization: ...
    X-Amz-Date: 20160323T194451Z
    
                        

Para configurar y probar el método POST en un recurso de flujo

1. Elija el recurso /{stream-name} y, a continuación, elija Crear método.

2. En Tipo de método, seleccione POST.

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

4. En Región de AWS, seleccione la Región de AWS donde creó el flujo de Kinesis.

5. En Servicio de AWS, seleccione Kinesis.

6. Deje Subdominio de AWS en blanco.

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

8. En Tipo de acción, elija Usar nombre de acción.

9. En Nombre de la función, introduzca CreateStream.

10. En Rol de ejecución, escriba el ARN del rol de ejecución.

11. Deje el valor predeterminado Acceso directo en Tratamiento de contenido.

12. Elija Crear método.

13. En la sección Solicitud de integración, añada los siguientes Parámetros de encabezados de solicitudes de URL:

    Content-Type: 'x-amz-json-1.1'

    La tarea sigue el mismo procedimiento para configurar el mapeo del parámetro de solicitud que el método GET /streams.

14. Añada la siguiente plantilla de mapeo de cuerpo para mapear los datos de la solicitud del método POST /streams/{stream-name} a la solicitud de integración POST /?Action=CreateStream:

    {
        "ShardCount": #if($input.path('$.ShardCount') == '') 5 #else $input.path('$.ShardCount') #end,
        "StreamName": "$input.params('stream-name')"
    }

    En la plantilla de mapeo anterior, definimos ShardCount en un valor fijo de 5 si el cliente no especifica un valor en la carga de la solicitud de método.

15. Para probar el método POST /stream/{stream-name} para invocar la acción CreateStream en Kinesis, seleccione la pestaña Prueba.

16. En Ruta, en stream-name, introduzca el nombre de un flujo de Kinesis nuevo.

17. Seleccione Probar. Si la prueba tiene éxito, se devuelve una respuesta 200 OK sin datos.

    Después de implementar la API, también puede realizar una solicitud de API de REST al método POST en un recurso Stream para invocar la acción CreateStream en Kinesis:

    
    POST https://your-api-id.execute-api.region.amazonaws.com/stage/streams/yourStream HTTP/1.1
    Host: your-api-id.execute-api.region.amazonaws.com
    Content-Type: application/json
    Authorization: ...
    X-Amz-Date: 20160323T194451Z
    
    { 
        "ShardCount": 5
    }
                        

Configurar y probar el método DELETE en un recurso de flujo

1. Elija el recurso /{stream-name} y, a continuación, elija Crear método.

2. En Tipo de método, seleccione DELETE.

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

4. En Región de AWS, seleccione la Región de AWS donde creó el flujo de Kinesis.

5. En Servicio de AWS, seleccione Kinesis.

6. Deje Subdominio de AWS en blanco.

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

8. En Tipo de acción, elija Usar nombre de acción.

9. En Nombre de la función, introduzca DeleteStream.

10. En Rol de ejecución, escriba el ARN del rol de ejecución.

11. Deje el valor predeterminado Acceso directo en Tratamiento de contenido.

12. Elija Crear método.

13. En la sección Solicitud de integración, añada los siguientes Parámetros de encabezados de solicitudes de URL:

    Content-Type: 'x-amz-json-1.1'

    La tarea sigue el mismo procedimiento para configurar el mapeo del parámetro de solicitud que el método GET /streams.

14. Añada la siguiente plantilla de mapeo de cuerpo para mapear los datos de la solicitud de método DELETE /streams/{stream-name} a la solicitud de integración de POST /?Action=DeleteStream correspondiente:

    {
        "StreamName": "$input.params('stream-name')"
    }

    Esta plantilla de mapeo genera la entrada necesaria de la DELETE /streams/{stream-name} acción desde el nombre de ruta URL proporcionada por el cliente: stream-name.

15. Para probar el método DELETE /stream/{stream-name} para invocar la acción DeleteStream en Kinesis, seleccione la pestaña Prueba.

16. En Ruta, en stream-name, introduzca el nombre de un flujo de Kinesis existente.

17. Seleccione Probar. Si la prueba tiene éxito, se devuelve una respuesta 200 OK sin datos.

    Después de implementar la API, también puede realizar la siguiente solicitud API de REST al método DELETE en el recurso Stream para llamar a la acción DeleteStream en Kinesis:

    
    DELETE https://your-api-id.execute-api.region.amazonaws.com/stage/streams/yourStream HTTP/1.1
    Host: your-api-id.execute-api.region.amazonaws.com
    Content-Type: application/json
    Authorization: ...
    X-Amz-Date: 20160323T194451Z
    
    {}
                        

Para crear los recursos /record, /records y /sharditerator

1. Elija el recurso /{stream-name} y, a continuación, elija Crear recurso.

2. Mantenga Recurso proxy desactivado.

3. En Ruta de recurso, seleccione /{stream-name}.

4. En Nombre del recurso, escriba record.

5. Mantenga desactivado CORS (uso compartido de recursos entre orígenes).

6. Elija Crear recurso.

7. Repita los pasos anteriores para crear un recurso /records y un recurso /sharditerator. La API final debe ser similar a la siguiente:

   

Para configurar y probar el método PUT /streams/{stream-name}/record para invocar a PutRecord en Kinesis

1. Elija /record y, a continuación, elija Crear método.

2. En Tipo de método, seleccione PUT.

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

4. En Región de AWS, seleccione la Región de AWS donde creó el flujo de Kinesis.

5. En Servicio de AWS, seleccione Kinesis.

6. Deje Subdominio de AWS en blanco.

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

8. En Tipo de acción, elija Usar nombre de acción.

9. En Nombre de la función, introduzca PutRecord.

10. En Rol de ejecución, escriba el ARN del rol de ejecución.

11. Deje el valor predeterminado Acceso directo en Tratamiento de contenido.

12. Elija Crear método.

13. En la sección Solicitud de integración, añada los siguientes Parámetros de encabezados de solicitudes de URL:

    Content-Type: 'x-amz-json-1.1'

    La tarea sigue el mismo procedimiento para configurar el mapeo del parámetro de solicitud que el método GET /streams.

14. Añada la siguiente plantilla de mapeo de cuerpo para mapear los datos de la solicitud de método PUT /streams/{stream-name}/record a la solicitud de integración de POST /?Action=PutRecord correspondiente:

    {
        "StreamName": "$input.params('stream-name')",
        "Data": "$util.base64Encode($input.json('$.Data'))",
        "PartitionKey": "$input.path('$.PartitionKey')"
    }

    En esta plantilla de asignación se asume que la carga del método de solicitud tiene el siguiente formato:

    {
       "Data": "some data",
       "PartitionKey": "some key"
    }

    Estos datos se pueden modelar mediante el siguiente esquema JSON:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "PutRecord proxy single-record payload",
      "type": "object",
      "properties": {
          "Data": { "type": "string" },
          "PartitionKey": { "type": "string" }
      }
    }

    Puede crear un modelo para incluir este esquema y utilizar el modelo para facilitar la generación de la plantilla de asignación. Sin embargo, puede generar una plantilla de asignación sin usar ningún modelo.

15. Para probar el método PUT /streams/{stream-name}/record, establezca la variable de ruta stream-name en el nombre de un flujo existente, introduzca la carga del formato necesario y, a continuación, envíe la solicitud de método. El resultado correcto es una respuesta 200 OK con una carga con el formato siguiente:

    
    {
      "SequenceNumber": "49559409944537880850133345460169886593573102115167928386",
      "ShardId": "shardId-000000000004"
    }
                        

Para configurar y probar el método PUT /streams/{stream-name}/records para invocar a PutRecords en Kinesis

1. Elija el recurso /records y, a continuación, elija Crear método.

2. En Tipo de método, seleccione PUT.

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

4. En Región de AWS, seleccione la Región de AWS donde creó el flujo de Kinesis.

5. En Servicio de AWS, seleccione Kinesis.

6. Deje Subdominio de AWS en blanco.

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

8. En Tipo de acción, elija Usar nombre de acción.

9. En Nombre de la función, introduzca PutRecords.

10. En Rol de ejecución, escriba el ARN del rol de ejecución.

11. Deje el valor predeterminado Acceso directo en Tratamiento de contenido.

12. Elija Crear método.

13. En la sección Solicitud de integración, añada los siguientes Parámetros de encabezados de solicitudes de URL:

    Content-Type: 'x-amz-json-1.1'

    La tarea sigue el mismo procedimiento para configurar el mapeo del parámetro de solicitud que el método GET /streams.

14. Añada la siguiente plantilla de mapeo para mapear los datos de la solicitud del método PUT /streams/{stream-name}/records a la solicitud de integración de POST /?Action=PutRecords correspondiente:

    {
        "StreamName": "$input.params('stream-name')",
        "Records": [
           #foreach($elem in $input.path('$.records'))
              {
                "Data": "$util.base64Encode($elem.data)",
                "PartitionKey": "$elem.partition-key"
              }#if($foreach.hasNext),#end
            #end
        ]
    }

    Esta plantilla de mapeo asume que el siguiente esquema JSON puede modelar la carga de la solicitud de método:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "PutRecords proxy payload data",
      "type": "object",
      "properties": {
        "records": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "data": { "type": "string" },
              "partition-key": { "type": "string" }
            }
          }
        }
      }
    }

    Puede crear un modelo para incluir este esquema y utilizar el modelo para facilitar la generación de la plantilla de asignación. Sin embargo, puede generar una plantilla de asignación sin usar ningún modelo.

    En este tutorial, hemos usado dos formatos de carga ligeramente diferentes para ilustrar que un desarrollador de API puede optar por exponer el formato de datos de backend al cliente u ocultárselo. Un formato es para el método PUT /streams/{stream-name}/records (anterior). Otro formato se utiliza en el método PUT /streams/{stream-name}/record (en el procedimiento anterior). En un entorno de producción, debe mantener la coherencia de ambos formatos.

15. Para probar el método PUT /streams/{stream-name}/records, establezca la variable de ruta stream-name en un flujo existente, introduzca la siguiente carga y envíe la solicitud del método.

    
    {
        "records": [
            {
                "data": "some data",
                "partition-key": "some key"
            },
            {
                "data": "some other data",
                "partition-key": "some key"
            }
        ]
    }
                            

    El resultado correcto es una respuesta 200 OK con una carga similar a la siguiente:

    {
      "FailedRecordCount": 0,
      "Records": [
        {
          "SequenceNumber": "49559409944537880850133345460167468741933742152373764162",
          "ShardId": "shardId-000000000004"
        },
        {
          "SequenceNumber": "49559409944537880850133345460168677667753356781548470338",
          "ShardId": "shardId-000000000004"
        }
      ]
    }

Para configurar y probar el método GET /streams/{stream-name}/sharditerator para invocar a GetShardIterator en Kinesis

GET /streams/{stream-name}/sharditerator es un método auxiliar para adquirir un iterador de fragmento necesario antes de llamar al método GET /streams/{stream-name}/records.

1. Elija el recurso /sharditerator y, a continuación, elija Crear método.

2. En Tipo de método, seleccione GET.

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

4. En Región de AWS, seleccione la Región de AWS donde creó el flujo de Kinesis.

5. En Servicio de AWS, seleccione Kinesis.

6. Deje Subdominio de AWS en blanco.

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

8. En Tipo de acción, elija Usar nombre de acción.

9. En Nombre de la función, introduzca GetShardIterator.

10. En Rol de ejecución, escriba el ARN del rol de ejecución.

11. Deje el valor predeterminado Acceso directo en Tratamiento de contenido.

12. Elija Parámetros de cadenas de consulta de URL.

    La acción GetShardIterator requiere una entrada de un valor de ShardId. Para pasar un valor de ShardId proporcionado por el cliente, añadimos un parámetro de consulta shard-id a la solicitud del método, tal y como se muestra en el siguiente paso.

13. Elija Add query string (Añadir cadena de consulta).

14. En Nombre, escriba shard-id.

15. Mantenga desactivados Obligatorio y Almacenamiento en caché.

16. Elija Crear método.

17. En la sección Solicitud de integración, añada la siguiente plantilla de mapeo para generar la entrada requerida (ShardId y StreamName) a la acción GetShardIterator a partir de los parámetros shard-id y stream-name de la solicitud de método. Además, la plantilla de mapeo también establece ShardIteratorType en TRIM_HORIZON como valor predeterminada.

    {
        "ShardId": "$input.params('shard-id')",
        "ShardIteratorType": "TRIM_HORIZON",
        "StreamName": "$input.params('stream-name')"
    }

18. Con la opción Test (Prueba) de la consola de API Gateway, escriba un nombre de flujo existente como el valor de la variable stream-name de Path (Ruta), establezca shard-id para Query string (Cadena de consulta) en un valor ShardId existente (por ejemplo, shard-000000000004) y elija Test (Prueba).

    La carga de la respuesta correcta es similar al siguiente resultado:

    {
      "ShardIterator": "AAAAAAAAAAFYVN3VlFy..."
    }

    Anote el valor de ShardIterator. Lo necesita para obtener los registros de un flujo.

Para configurar y probar el método GET /streams/{stream-name}/records para invocar la acción GetRecords en Kinesis

1. Elija el recurso /records y, a continuación, elija Crear método.

2. En Tipo de método, seleccione GET.

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

4. En Región de AWS, seleccione la Región de AWS donde creó el flujo de Kinesis.

5. En Servicio de AWS, seleccione Kinesis.

6. Deje Subdominio de AWS en blanco.

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

8. En Tipo de acción, elija Usar nombre de acción.

9. En Nombre de la función, introduzca GetRecords.

10. En Rol de ejecución, escriba el ARN del rol de ejecución.

11. Deje el valor predeterminado Acceso directo en Tratamiento de contenido.

12. Elija Encabezados de solicitud HTTP.

    La acción GetRecords requiere una entrada de un valor de ShardIterator. Para pasar un valor de ShardIterator proporcionado por el cliente, agregamos un parámetro de encabezado Shard-Iterator a la solicitud del método.

13. Elija Add header (Añadir encabezado).

14. En Nombre, escriba Shard-Iterator.

15. Mantenga desactivados Obligatorio y Almacenamiento en caché.

16. Elija Crear método.

17. En la sección Solicitud de integración, añada la siguiente plantilla de mapeo de cuerpo para mapear el valor del parámetro de encabezado Shard-Iterator al valor de la propiedad ShardIterator de la carga JSON para la acción GetRecords en Kinesis.

    {
        "ShardIterator": "$input.params('Shard-Iterator')"
    }

18. Con la opción Prueba de la consola de API Gateway, escriba un nombre de flujo existente como el valor de la variable stream-name de Ruta, establezca el Shard-Iterator de Encabezado en el valor de ShardIterator obtenido de la serie de pruebas del método GET /streams/{stream-name}/sharditerator (arriba) y elija Prueba.

    La carga de la respuesta correcta es similar al siguiente resultado:

    {
      "MillisBehindLatest": 0,
      "NextShardIterator": "AAAAAAAAAAF...",
      "Records": [ ... ]
    }