Tutorial: Criar uma API REST como um proxy do Amazon Kinesis - Amazon API Gateway
Criar uma função e política do IAM para a API acessar o KinesisCriar uma API como um proxy do KinesisListar streams no KinesisCriar, descrever e excluir um stream no KinesisObter registros de e adicionar registros a um stream no Kinesis

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

Esta página descreve como criar e configurar uma API REST com uma integração do tipo AWS para acessar o Kinesis.

nota

Para integrar sua API do API Gateway ao Kinesis, é necessário escolher uma região onde os serviços API Gateway e Kinesis estejam disponíveis. Para saber a disponibilidade da região, consulte Endpoints e cotas de serviço.

Para fins de ilustração, criamos uma API de exemplo para permitir que um cliente faça o seguinte:

  1. Listar os streams disponíveis do usuário no Kinesis

  2. Criar, descrever ou excluir um fluxo especificado

  3. Leia registros de dados ou escreva registros de dados no fluxo especificado

Para realizar as tarefas anteriores, a API expõe métodos em vários recursos para invocar o seguinte, respectivamente:

  1. A ação ListStreams no Kinesis

  2. A ação CreateStream, DescribeStream ou DeleteStream

  3. A ação GetRecords ou PutRecords (incluindo PutRecord) no Kinesis

Especificamente, construiremos a API da seguinte maneira:

  • Expondo um método HTTP GET no recurso /streams da API e integrando o método à ação ListStreams no Kinesis para listar os streams na conta do autor da chamada.

  • Expondo um método HTTP POST no recurso /streams/{stream-name} da API e integrando esse método à ação CreateStream no Kinesis para criar um stream nomeado na conta do autor da chamada.

  • Expondo um método HTTP GET no recurso /streams/{stream-name} da API e integrando esse método à ação DescribeStream no Kinesis para descrever um stream nomeado na conta do autor da chamada.

  • Expondo um método HTTP DELETE no recurso /streams/{stream-name} da API e integrando o método à ação DeleteStream no Kinesis para excluir um stream na conta do autor da chamada.

  • Expondo um método HTTP PUT no recurso /streams/{stream-name}/record da API e integrando o método à ação PutRecord no Kinesis. Isso permite que o cliente adicione um único registro de dados ao fluxo nomeado.

  • Expondo um método HTTP PUT no recurso /streams/{stream-name}/records da API e integrando o método à ação PutRecords no Kinesis. Isso permite que o cliente adicione uma lista de registros de dados ao fluxo nomeado.

  • Expondo um método HTTP GET no recurso /streams/{stream-name}/records da API e integrando esse método à ação GetRecords no Kinesis. Isso permite que o cliente liste registros de dados no fluxo nomeado com um iterador de fragmentos especificado. Um iterador de fragmentos especifica a posição do fragmento a partir da qual começar a ler os registros de dados sequencialmente.

  • Expondo um método HTTP GET no recurso /streams/{stream-name}/sharditerator da API e integrando esse método à ação GetShardIterator no Kinesis. Esse método auxiliar deve ser fornecido à ação ListStreams no Kinesis.

É possível aplicar as instruções apresentadas aqui a outras ações do Kinesis. Para obter a lista completa das ações do Kinesis, consulte Referência de API do Amazon Kinesis.

Em vez de usar o console do API Gateway para criar a API demonstrativa, é possível importar a API demonstrativa para o API Gateway usando a API de importação do API Gateway. Para obter informações sobre como usar o recurso Import API, consulte Desenvolver APIs REST usando OpenAPI no API Gateway.

Criar uma função e política do IAM para a API acessar o Kinesis

Para que a API invoque ações do Kinesis, é necessário ter as políticas do IAM apropriadas anexadas a um perfil do IAM.

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.

Criar uma API como um proxy do Kinesis

Use as etapas a seguir para criar a API no console do API Gateway.

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).

Após a criação da API, o console do API Gateway exibe a página Resources (Recursos), que contém apenas o recurso raiz (/) da API.

Listar streams no Kinesis

O Kinesis é compatível com a ação ListStreams com a seguinte chamada da API REST: 

POST /?Action=ListStreams HTTP/1.1
Host: kinesis.<region>.<domain>
Content-Length: <PayloadSizeBytes>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.1
Authorization: <AuthParams>
X-Amz-Date: <Date>
        
{
   ...
}

Na solicitação de API REST acima, a ação é especificada no parâmetro Action da consulta. Como alternativa, você pode especificar a ação em um cabeçalho X-Amz-Target:

POST / HTTP/1.1
Host: kinesis.<region>.<domain>
Content-Length: <PayloadSizeBytes>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.1
Authorization: <AuthParams>
X-Amz-Date: <Date>
X-Amz-Target: Kinesis_20131202.ListStreams        
{
   ...
}

Neste tutorial, usamos o parâmetro de consulta para especificar a ação.

Para expor uma ação do Kinesis na API, adicione um recurso /streams à raiz da API. Depois, defina um método GET no recurso e integre o método com a ação ListStreams do Kinesis.

O procedimento a seguir descreve como listar streams do Kinesis usando o console do API Gateway.

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

Criar, descrever e excluir um stream no Kinesis

As tarefas de criar, descrever e excluir um stream no Kinesis envolvem fazer as seguintes solicitações de API REST do Kinesis, respectivamente: 


POST /?Action=CreateStream HTTP/1.1
Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "ShardCount": number,
    "StreamName": "string"
}                               
            

POST /?Action=DescribeStream HTTP/1.1
Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "StreamName": "string"
}                                          
            

POST /?Action=DeleteStream HTTP/1.1
Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "StreamName":"string"
}

Podemos construir a API para aceitar a entrada necessária como uma carga de JSON da solicitação de método e passar essa carga diretamente à solicitação de integração. No entanto, para fornecer mais exemplos do mapeamento de dados entre solicitações de método e integração e respostas de método e integração, criamos nossa API de uma maneira um pouco diferente.

Expomos os métodos HTTP GET, POST e Delete em um recurso de Stream a ser nomeado. Usamos a variável de caminho {stream-name} como o espaço reservado do recurso de stream e integramos esses métodos de API às ações DescribeStream, CreateStream e DeleteStream do Kinesis, respectivamente. Exigimos que o cliente passe outros dados de entrada como cabeçalhos, parâmetros de consulta ou a carga de uma solicitação de método. Fornecemos modelos de mapeamento para transformar os dados na carga da solicitação de integração necessária.

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 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 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 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

{}

Obter registros de e adicionar registros a um stream no Kinesis

Depois de criar um stream no Kinesis, você poderá adicionar registros de dados ao stream e ler os dados desse stream. Adicionar registros de dados envolve chamar a ação PutRecords ou PutRecord no Kinesis. O primeiro adiciona vários registros, enquanto o último adiciona um único registro ao fluxo. 


POST /?Action=PutRecords HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "Records": [
        {
            "Data": blob,
            "ExplicitHashKey": "string",
            "PartitionKey": "string"
        }
    ],
    "StreamName": "string"
}

ou


POST /?Action=PutRecord HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "Data": blob,
    "ExplicitHashKey": "string",
    "PartitionKey": "string",
    "SequenceNumberForOrdering": "string",
    "StreamName": "string"
}

Aqui, StreamName identifica o fluxo de destino para adicionar registros. StreamName, Data e PartitionKey são dados de entrada necessários. No nosso exemplo, podemos usar os valores padrão para todos os dados de entrada opcionais e não especificaremos explicitamente valores para eles na entrada para a solicitação de método.

Ler dados no Kinesis equivale a chamar a ação GetRecords: 

POST /?Action=GetRecords HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

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

Aqui, o stream de origem do qual estamos obtendo registros é especificado no valor ShardIterator necessário, conforme indicado na ação a seguir do Kinesis para obter um iterador de fragmentos:


POST /?Action=GetShardIterator HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes
                
{
    "ShardId": "string",
    "ShardIteratorType": "string",
    "StartingSequenceNumber": "string",
    "StreamName": "string"
}

Para as ações GetRecords e PutRecords, expomos os métodos GET e PUT, respectivamente, em um recurso /records que está anexado a um recurso de fluxo nomeado (/{stream-name}). Da mesma forma, expomos a ação PutRecord como um método PUT em um recurso /record.

Como a ação GetRecords usa como entrada um valor ShardIterator, que é obtido ao chamar a ação auxiliar GetShardIterator, expomos um método auxiliar GET em um recurso ShardIterator (/sharditerator).

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:

    Crie o método Records:GET|PUT|PUT|GET para a API.

Os quatro procedimentos a seguir descrevem como configurar cada um dos métodos, como mapear dados de solicitações de método para solicitações de integração e como testar os métodos.

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 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 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 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 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": [ ... ]
}