Tutorial: Criar uma API REST como um proxy do Amazon Kinesis

Como criar o perfil de execução do proxy de serviço da AWS

1. Faça login no AWS Management Console e abra o console do IAM em https://console.aws.amazon.com/iam/.

2. Escolha Funções.

3. Selecione Criar função.

4. Selecione Serviço da AWS em Selecionar tipo de entidade confiável, selecione API Gateway e Permite que o API Gateway envie logs ao CloudWatch Logs.

5. Selecione Próximo e, depois, Próximo.

6. Em Role name (Nome da função), digite APIGatewayKinesisProxyPolicy e escolha Create role (Criar função).

7. Na lista Roles (Funções), escolha a função que você acaba de criar. Talvez seja necessário rolar a página ou usar a barra de pesquisa para encontrar o perfil.

8. Para a função escolhida, selecione a guia Adicionar permissões.

9. Selecione Anexar políticas na lista suspensa.

10. Na barra de pesquisa, insira AmazonKinesisFullAccess e escolha Adicionar permissões.

    nota

    Este tutorial usa uma política gerenciada em prol da simplicidade. Como prática recomendada, você deve criar sua própria política do IAM para conceder as permissões mínimas necessárias.

11. Anote o ARN do perfil recém-criado, você o usará posteriormente.

Como criar uma API como um proxy de serviço da AWS para o Kinesis

1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

2. Se esta for a primeira vez que você usa o API Gateway, você verá uma página com os recursos do serviço. Em REST API, escolha Build (Criar). Quando o pop-up Create Example API (Criar API de exemplo) for exibido, escolha OK.

   Se essa não for a primeira vez que você usa o API Gateway, escolha Create API (Criar API). Em REST API, escolha Build (Criar).

3. Selecione New API (Nova API).

4. Em API name (Nome da API), insira KinesisProxy. Mantenha os valores padrão para todos os outros campos.

5. (Opcional) Em Description (Descrição), insira uma descrição.

6. Selecione Create API (Criar API).

Como listar streams do Kinesis usando o console do API Gateway

1. Selecione o recurso / e, depois, escolha Criar recurso.

2. Em Resource Name (Nome do recurso), insira streams.

3. Mantenha CORS (Compartilhamento de recursos de origem cruzada) desativado.

4. Selecione Criar recurso.

5. Selecione o recurso /streams e, depois, Criar método e faça o seguinte:

   1. Em Tipo de método, selecione GET.

      nota

      O verbo HTTP para um método invocado por um cliente pode ser diferente do verbo HTTP para uma integração exigida pelo backend. Aqui, selecionamos GET porque a listagem de fluxos é intuitivamente uma operação READ.

   2. Em Tipo de integração, selecione Serviço da AWS.

   3. Em Região da AWS, selecione a Região da AWS onde você criou o fluxo do Kinesis.

   4. Em AWS service (Serviço da AWS), selecione Kinesis.

   5. Mantenha o subdomínio da AWS em branco.

   6. Em Método HTTP, escolha POST.

      nota

      Aqui, escolhemos POST porque o Kinesis exige que a ação ListStreams seja invocada com ele.

   7. Em Tipo de ação, selecione Usar nome da ação.

   8. Em Nome da ação, insira ListStreams.

   9. Em Perfil de execução, digite o ARN para o perfil de execução.

   10. Deixe o padrão de Passagem para Manuseio de conteúdo.

   11. Escolha Criar método.

6. Na guia Solicitação de integração, em Configurações de solicitação de integração, selecione Editar.

7. Em Passagem do corpo da solicitação, selecione Quando não há modelos definidos (recomendado).

8. Selecione Parâmetros de cabeçalhos de solicitações de URL e faça o seguinte:

   1. Selecione Adicionar parâmetro de cabeçalhos de solicitação.

   2. Em Nome, digite Content-Type.

   3. Em Mapeado de, insira 'application/x-amz-json-1.1'.

   Usamos um mapeamento de parâmetros de solicitação para definir o cabeçalho Content-Type como o valor estático de 'application/x-amz-json-1.1' para informar ao Kinesis que a entrada é de uma versão específica do JSON.

9. Selecione Modelos de mapeamento, Adicionar modelo de mapeamento e faça o seguinte:

   1. Em Tipo de conteúdo, insira application/json.

   2. Em Corpo do modelo, insira {}.

   3. Escolha Salvar.

   A solicitação ListStreams requer uma carga com o seguinte formato JSON:

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

   No entanto, as propriedades são opcionais. Para usar os valores padrão, optamos por uma carga JSON vazia aqui.

10. Teste o método GET no recurso /streams para invocar a ação ListStreams no Kinesis:

    Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

    Selecione Testar para testar o método.

    Se você já criou dois streams chamados “myStream” e “yourStream” no Kinesis, o teste bem-sucedido retornará uma resposta 200 OK contendo a seguinte carga útil:

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

Como criar o recurso {stream-name}

1. Selecione o recurso /streams e Criar recurso.

2. Mantenha Recurso proxy desativado.

3. Em Caminho do recurso, selecione /streams.

4. Em Resource Name (Nome do recurso), insira {stream-name}.

5. Mantenha CORS (Compartilhamento de recursos de origem cruzada) desativado.

6. Selecione Criar recurso.

Para configurar e testar o método GET em um recurso de fluxo

1. Selecione o recurso /{stream-name} e Criar método.

2. Em Tipo de método, selecione GET.

3. Em Tipo de integração, selecione Serviço da AWS.

4. Em Região da AWS, selecione a Região da AWS onde você criou o fluxo do Kinesis.

5. Em AWS service (Serviço da AWS), selecione Kinesis.

6. Mantenha o subdomínio da AWS em branco.

7. Em Método HTTP, escolha POST.

8. Em Tipo de ação, selecione Usar nome da ação.

9. Em Nome da ação, insira DescribeStream.

10. Em Perfil de execução, digite o ARN para o perfil de execução.

11. Deixe o padrão de Passagem para Manuseio de conteúdo.

12. Escolha Criar método.

13. Na seção Solicitação de integração, adicione os seguintes parâmetros de cabeçalhos de solicitação de URL:

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

    A tarefa segue o mesmo procedimento para configurar o mapeamento do parâmetro de solicitação para o método GET /streams.

14. Adicione o seguinte modelo de mapeamento de corpo para mapear dados na solicitação do método GET /streams/{stream-name} à solicitação de integração POST /?Action=DescribeStream:

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

    Esse modelo de mapeamento gera a carga de solicitação de integração necessária para a ação DescribeStream do Kinesis do valor do parâmetro do caminho stream-name da solicitação do método.

15. Para testar o método GET /stream/{stream-name} para invocar a ação DescribeStream no Kinesis, selecione a guia Testar.

16. Em Caminho, em stream-name, insira o nome de um fluxo existente do Kinesis.

17. Escolha Testar. Se o teste for bem-sucedido, uma resposta 200 OK será retornada com uma carga semelhante à seguinte:

    {
      "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"
      }
    }

    Depois de implantar a API, você poderá fazer uma solicitação REST com base neste método de 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 e testar o método POST em um recurso de fluxo

1. Selecione o recurso /{stream-name} e Criar método.

2. Em Tipo de método, selecione POST.

3. Em Tipo de integração, selecione Serviço da AWS.

4. Em Região da AWS, selecione a Região da AWS onde você criou o fluxo do Kinesis.

5. Em AWS service (Serviço da AWS), selecione Kinesis.

6. Mantenha o subdomínio da AWS em branco.

7. Em Método HTTP, escolha POST.

8. Em Tipo de ação, selecione Usar nome da ação.

9. Em Nome da ação, insira CreateStream.

10. Em Perfil de execução, digite o ARN para o perfil de execução.

11. Deixe o padrão de Passagem para Manuseio de conteúdo.

12. Escolha Criar método.

13. Na seção Solicitação de integração, adicione os seguintes parâmetros de cabeçalhos de solicitação de URL:

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

    A tarefa segue o mesmo procedimento para configurar o mapeamento do parâmetro de solicitação para o método GET /streams.

14. Adicione o seguinte modelo de mapeamento de corpo para mapear dados na solicitação do método POST /streams/{stream-name} à solicitação de integração POST /?Action=CreateStream:

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

    No modelo de mapeamento anterior, definimos ShardCount como um valor fixo de 5 se o cliente não especificar um valor na carga da solicitação do método.

15. Para testar o método POST /stream/{stream-name} para invocar a ação CreateStream no Kinesis, selecione a guia Testar.

16. Em Caminho, em stream-name, insira o nome de um novo fluxo do Kinesis.

17. Escolha Testar. Se o teste for bem-sucedido, uma resposta 200 OK será retornado sem dados.

    Depois de implantar a API, também será possível fazer uma solicitação de API REST no método POST em um recurso Stream para invocar a ação CreateStream no 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
    }
                        

Configure e teste o método DELETE em um recurso de fluxo

1. Selecione o recurso /{stream-name} e Criar método.

2. Em Tipo de método, selecione DELETE.

3. Em Tipo de integração, selecione Serviço da AWS.

4. Em Região da AWS, selecione a Região da AWS onde você criou o fluxo do Kinesis.

5. Em AWS service (Serviço da AWS), selecione Kinesis.

6. Mantenha o subdomínio da AWS em branco.

7. Em Método HTTP, escolha POST.

8. Em Tipo de ação, selecione Usar nome da ação.

9. Em Nome da ação, insira DeleteStream.

10. Em Perfil de execução, digite o ARN para o perfil de execução.

11. Deixe o padrão de Passagem para Manuseio de conteúdo.

12. Escolha Criar método.

13. Na seção Solicitação de integração, adicione os seguintes parâmetros de cabeçalhos de solicitação de URL:

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

    A tarefa segue o mesmo procedimento para configurar o mapeamento do parâmetro de solicitação para o método GET /streams.

14. Adicione o seguinte modelo de mapeamento de corpo para mapear dados na solicitação do método DELETE /streams/{stream-name} à solicitação de integração correspondente de POST /?Action=DeleteStream:

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

    Esse modelo de mapeamento gera a entrada necessária para a ação DELETE /streams/{stream-name} no nome do caminho da URL de stream-name fornecido pelo cliente.

15. Para testar o método DELETE /stream/{stream-name} para invocar a ação DeleteStream no Kinesis, selecione a guia Testar.

16. Em Caminho, em stream-name, insira o nome de um fluxo existente do Kinesis.

17. Escolha Testar. Se o teste for bem-sucedido, uma resposta 200 OK será retornado sem dados.

    Depois de implantar a API, você também poderá fazer a solicitação de API REST a seguir no método DELETE em um recurso Stream para chamar a ação DeleteStream no 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
    
    {}
                        

Como criar os recursos /record, /records e /sharditerator

1. Selecione o recurso /{stream-name} e Criar recurso.

2. Mantenha Recurso proxy desativado.

3. Em Caminho do recurso, selecione /{stream-name}.

4. Em Resource Name (Nome do recurso), insira record.

5. Mantenha CORS (Compartilhamento de recursos de origem cruzada) desativado.

6. Selecione Criar recurso.

7. Repita as etapas anteriores para criar um recurso /records e um /sharditerator. A API final deve ter a seguinte aparência:

   

Como configurar e testar o método PUT /streams/{stream-name}/record para invocar PutRecord no Kinesis:

1. Selecione o recurso /record e Criar método.

2. Em Tipo de método, selecione PUT.

3. Em Tipo de integração, selecione Serviço da AWS.

4. Em Região da AWS, selecione a Região da AWS onde você criou o fluxo do Kinesis.

5. Em AWS service (Serviço da AWS), selecione Kinesis.

6. Mantenha o subdomínio da AWS em branco.

7. Em Método HTTP, escolha POST.

8. Em Tipo de ação, selecione Usar nome da ação.

9. Em Nome da ação, insira PutRecord.

10. Em Perfil de execução, digite o ARN para o perfil de execução.

11. Deixe o padrão de Passagem para Manuseio de conteúdo.

12. Escolha Criar método.

13. Na seção Solicitação de integração, adicione os seguintes parâmetros de cabeçalhos de solicitação de URL:

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

    A tarefa segue o mesmo procedimento para configurar o mapeamento do parâmetro de solicitação para o método GET /streams.

14. Adicione o seguinte modelo de mapeamento de corpo para mapear dados na solicitação do método PUT /streams/{stream-name}/record à solicitação de integração correspondente de POST /?Action=PutRecord:

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

    Esse modelo de mapeamento pressupõe que a carga da solicitação de método seja do seguinte formato:

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

    Esses dados podem ser modelados pelo seguinte 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" }
      }
    }

    Você pode criar um modelo para incluir esse esquema e usar o modelo para facilitar a geração do modelo de mapeamento. No entanto, pode gerar um modelo de mapeamento sem usar qualquer modelo.

15. Para testar o método PUT /streams/{stream-name}/record, defina a variável de caminho stream-name como o nome de um fluxo existente, forneça uma carga do formato necessário e, em seguida, envie a solicitação de método. O resultado bem-sucedido é uma resposta 200 OK com uma carga no seguinte formato:

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

Como configurar e testar o método PUT /streams/{stream-name}/records para invocar PutRecords no Kinesis

1. Selecione o recurso /records e Criar método.

2. Em Tipo de método, selecione PUT.

3. Em Tipo de integração, selecione Serviço da AWS.

4. Em Região da AWS, selecione a Região da AWS onde você criou o fluxo do Kinesis.

5. Em AWS service (Serviço da AWS), selecione Kinesis.

6. Mantenha o subdomínio da AWS em branco.

7. Em Método HTTP, escolha POST.

8. Em Tipo de ação, selecione Usar nome da ação.

9. Em Nome da ação, insira PutRecords.

10. Em Perfil de execução, digite o ARN para o perfil de execução.

11. Deixe o padrão de Passagem para Manuseio de conteúdo.

12. Escolha Criar método.

13. Na seção Solicitação de integração, adicione os seguintes parâmetros de cabeçalhos de solicitação de URL:

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

    A tarefa segue o mesmo procedimento para configurar o mapeamento do parâmetro de solicitação para o método GET /streams.

14. Adicione o seguinte modelo de mapeamento para associar dados na solicitação do método PUT /streams/{stream-name}/records à solicitação de integração correspondente de POST /?Action=PutRecords:

    {
        "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
        ]
    }

    Esse modelo de mapeamento pressupõe que a carga da solicitação do método pode ser modelada pelo seguinte esquema JSON:

    {
      "$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" }
            }
          }
        }
      }
    }

    Você pode criar um modelo para incluir esse esquema e usar o modelo para facilitar a geração do modelo de mapeamento. No entanto, pode gerar um modelo de mapeamento sem usar qualquer modelo.

    Neste tutorial, usamos dois formatos de carga um pouco diferentes para ilustrar que um desenvolvedor de API pode optar por expor o formato de dados de backend ao cliente ou ocultá-lo do cliente. Um formato é para o método PUT /streams/{stream-name}/records (acima). O outro formato é usado para o método PUT /streams/{stream-name}/record (no procedimento anterior). Em um ambiente de produção, você deve manter os dois formatos consistentes.

15. Para testar o método PUT /streams/{stream-name}/records, defina a variável de caminho stream-name como um fluxo existente, forneça a carga a seguir e envie a solicitação de método.

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

    O resultado bem-sucedido é uma resposta 200 OK com uma carga semelhante à saída a seguir:

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

Como configurar e testar o método GET /streams/{stream-name}/sharditerator, invoque GetShardIterator no Kinesis

O método GET /streams/{stream-name}/sharditerator é um método auxiliar para adquirir um iterador de fragmentos necessário antes de chamar o método GET /streams/{stream-name}/records.

1. Selecione o recurso /sharditerator e Criar método.

2. Em Tipo de método, selecione GET.

3. Em Tipo de integração, selecione Serviço da AWS.

4. Em Região da AWS, selecione a Região da AWS onde você criou o fluxo do Kinesis.

5. Em AWS service (Serviço da AWS), selecione Kinesis.

6. Mantenha o subdomínio da AWS em branco.

7. Em Método HTTP, escolha POST.

8. Em Tipo de ação, selecione Usar nome da ação.

9. Em Nome da ação, insira GetShardIterator.

10. Em Perfil de execução, digite o ARN para o perfil de execução.

11. Deixe o padrão de Passagem para Manuseio de conteúdo.

12. Selecione Parâmetros de string de consulta de URL.

    A ação GetShardIterator requer uma entrada de um valor ShardId. Para transmitir um valor ShardId fornecido pelo cliente, adicionamos um parâmetro de consulta shard-id à solicitação de método, conforme mostrado na etapa a seguir.

13. Escolha Add query string (Adicionar string de consulta).

14. Em Nome, digite shard-id.

15. Mantenha Obrigatório e Armazenamento em cache desativados.

16. Escolha Criar método.

17. Na seção Solicitação de integração, adicione o modelo de mapeamento a seguir para gerar a entrada necessária (ShardId e StreamName) à ação GetShardIterator dos parâmetros shard-id e stream-name da solicitação de método. Além disso, o modelo de mapeamento também define ShardIteratorType como TRIM_HORIZON como um padrão.

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

18. Usando a opção Test (Testar) no console do API Gateway, insira um nome de stream existente como o valor da variável stream-name Path (Caminho), defina shard-id Query string (String de consulta) como um valor ShardId existente (por exemplo, shard-000000000004), e escolha Test (Testar).

    A carga da resposta bem-sucedida é semelhante à saída a seguir:

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

    Anote o valor de ShardIterator. Você precisa dela para obter registros de um fluxo.

Como configurar e testar o método GET /streams/{stream-name}/records para invocar a ação GetRecords no Kinesis

1. Selecione o recurso /records e Criar método.

2. Em Tipo de método, selecione GET.

3. Em Tipo de integração, selecione Serviço da AWS.

4. Em Região da AWS, selecione a Região da AWS onde você criou o fluxo do Kinesis.

5. Em AWS service (Serviço da AWS), selecione Kinesis.

6. Mantenha o subdomínio da AWS em branco.

7. Em Método HTTP, escolha POST.

8. Em Tipo de ação, selecione Usar nome da ação.

9. Em Nome da ação, insira GetRecords.

10. Em Perfil de execução, digite o ARN para o perfil de execução.

11. Deixe o padrão de Passagem para Manuseio de conteúdo.

12. Escolha Cabeçalhos de solicitação HTTP.

    A ação GetRecords requer uma entrada de um valor ShardIterator. Para transmitir um valor ShardIterator fornecido pelo cliente, adicionamos um parâmetro de cabeçalho Shard-Iterator à solicitação de método.

13. Escolha Add header (Adicionar cabeçalho).

14. Em Nome, digite Shard-Iterator.

15. Mantenha Obrigatório e Armazenamento em cache desativados.

16. Escolha Criar método.

17. Na seção Solicitação de integração, adicione o modelo de mapeamento do corpo a seguir para associar o valor do parâmetro de cabeçalho Shard-Iterator ao valor da propriedade ShardIterator da carga útil de JSON para a ação GetRecords no Kinesis.

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

18. Usando a opção Testar no console do API Gateway, digite um nome de fluxo existente como o valor da variável Caminho de stream-name, defina o Cabeçalho de Shard-Iterator como o valor ShardIterator obtido da execução de teste do método GET /streams/{stream-name}/sharditerator (acima) e selecione Testar.

    A carga da resposta bem-sucedida é semelhante à saída a seguir:

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