Capturar dados de alterações para o DynamoDB Streams

O DynamoDB Streams captura uma sequência em ordem temporal de modificações em nível de item em qualquer tabela do DynamoDB e armazena essas informações em um log por até 24 horas. As aplicações podem acessar esse log e visualizar os itens de dados à medida que eles aparecem antes e depois de serem modificados, quase em tempo real.

A criptografia em repouso criptografa os dados em fluxos do DynamoDB. Para ter mais informações, consulte Criptografia em repouso do DynamoDB.

Um fluxo do DynamoDB é um fluxo ordenado de informações sobre alterações em itens de uma tabela do DynamoDB. Quando você habilita um fluxo em uma tabela, o DynamoDB captura informações sobre todas as modificações em itens de dados na tabela.

Sempre que uma aplicação cria, atualiza ou exclui itens nessa tabela, o DynamoDB Streams grava um registro de fluxo com os atributos de chave primária dos itens que foram modificados. Um registro de fluxo contém informações sobre uma modificação de dados em um único item de uma tabela do DynamoDB. É possível configurar o stream de modo que os registros de stream capturem informações adicionais, como as imagens "antes" e "depois" de itens modificados.

O DynamoDB Streams ajuda a garantir:

• Cada registro do fluxo aparece exatamente uma vez no fluxo.

• Para cada item modificado em uma tabela do DynamoDB, os registros de fluxo aparecem na mesma sequência que as modificações reais no item.

O DynamoDB Streams grava registros de fluxo em tempo quase real para que você possa criar aplicações que consomem esses fluxos e executam ações com base no conteúdo.

Tópicos

• Endpoints para DynamoDB Streams
• Habilitar um fluxo
• Ler e processar um fluxo
• DynamoDB Streams e vida útil
• Usar o adaptador do DynamoDB Streams Kinesis Adapter para processar registros de fluxos
• API de baixo nível do DynamoDB Streams: exemplo em Java
• Streams e gatilhos do DynamoDB AWS Lambda

Endpoints para DynamoDB Streams

AWS mantém endpoints separados para o DynamoDB e o DynamoDB Streams. Para trabalhar com índices e tabelas de banco de dados, sua aplicação precisa acessar um endpoint do DynamoDB. Para ler e processar registros do DynamoDB Streams, sua aplicação precisa acessar um endpoint do DynamoDB Streams na mesma região.

A convenção de nomenclatura dos endpoints do DynamoDB Streams é streams.dynamodb.<region>.amazonaws.com. Por exemplo, se você usasse o endpoint dynamodb.us-west-2.amazonaws.com para acessar o DynamoDB, usaria o endpoint streams.dynamodb.us-west-2.amazonaws.com para acessar o DynamoDB Streams.

nota

Para obter uma lista completa de regiões e endpoints do DynamoDB e do DynamoDB Streams, consulte Regiões e endpoints na Referência geral da AWS.

Os AWS SDKs fornecem clientes separados para o DynamoDB e o DynamoDB Streams. Dependendo das suas necessidades, sua aplicação pode acessar um endpoint do DynamoDB, um endpoint do DynamoDB Streams ou ambos ao mesmo tempo. Para conectar aos dois endpoints, a aplicação precisa instanciar dois clientes, um para o DynamoDB e outro para o DynamoDB Streams.

Habilitar um fluxo

Você pode ativar um stream em uma nova tabela ao criá-la usando o AWS SDKs AWS CLI ou um deles. Também pode habilitar ou desabilitar um stream em uma tabela existente ou alterar as configurações de um stream. O DynamoDB Streams opera de forma assíncrona e, portanto, não haverá impacto sobre a performance de uma tabela se você habilitar um stream.

A maneira mais fácil de gerenciar o DynamoDB Streams é usar o AWS Management Console.

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

2. No painel do console do DynamoDB, escolha Tables (Tabelas) e selecione uma tabela existente.

3. Escolha a guia Exports and streams (Exportações e fluxos).

4. Na seção de detalhes do stream do DynamoDB, escolha Ativar.

5. Na página Ativar o stream do DynamoDB, escolha as informações que serão gravadas no stream sempre que os dados na tabela forem modificados:

   • Key attributes only (Somente atributos de chaves): somente os atributos de chaves do item modificado.

   • New image (Nova imagem): o item inteiro como é exibido depois de modificado.

   • Old image (Imagem antiga): o item inteiro como era exibido antes de modificado.

   • New and old images (Imagens nova e antiga): as imagens nova e antiga do item.

   Quando as configurações estiverem como você deseja, escolha Ativar transmissão.

6. (Opcional) Para desativar um stream existente, escolha Desativar em Detalhes do stream do DynamoDB.

Você também pode usar as operações da API CreateTable ou UpdateTable para habilitar ou modificar um fluxo. O parâmetro StreamSpecification determina como o fluxo é configurado:

• StreamEnabled: especifica se um fluxo está habilitado (true) ou desabilitado (false) para a tabela.

• StreamViewType: especifica as informações que serão gravadas no fluxo sempre que os dados na tabela forem modificados:

  • KEYS_ONLY: somente os atributos de chaves do item modificado.

  • NEW_IMAGE: o item inteiro como é exibido depois de ser modificado.

  • OLD_IMAGE: o item inteiro como era exibido antes de ser modificado.

  • NEW_AND_OLD_IMAGES: as imagens nova e antiga do item.

É possível habilitar ou desabilitar um fluxo a qualquer momento. No entanto, você receberá uma ResourceInUseException se tentar habilitar um fluxo em uma tabela que já tenha um fluxo. Você receberá uma ValidationException se tentar habilitar um fluxo em uma tabela que já tenha um fluxo.

Quando você define StreamEnabled como true, o DynamoDB cria um novo fluxo com um descritor de streaming exclusivo atribuído a ele. Se você desabilitar e reabilitar um fluxo na tabela, será criado um fluxo com um descritor diferente.

Cada fluxo é identificado exclusivamente por um nome do recurso da Amazon (ARN). Veja a seguir um ARN de exemplo para um fluxo em uma tabela do DynamoDB chamada TestTable.

arn:aws:dynamodb:us-west-2:111122223333:table/TestTable/stream/2015-05-11T21:21:33.291

Para determinar o descritor de streaming mais recente de uma tabela, emita uma solicitação DescribeTable do DynamoDB e procure o elemento LatestStreamArn na resposta.

nota

Não é possível editar um StreamViewType após a configuração de um fluxo. Se você precisar fazer alterações em um fluxo depois que ele tiver sido configurado, será necessário desativar o fluxo atual e criar outro.

Ler e processar um fluxo

Para ler e processar um fluxo, sua aplicação deve se conectar a um endpoint do DynamoDB Streams e emitir solicitações de API.

Um fluxo consiste em registros de fluxo. Cada registro de stream representa uma única modificação de dados na tabela do DynamoDB à qual o fluxo pertence. Cada registro de fluxo recebe um número de sequência, refletindo a ordem em que ele foi publicado no fluxo.

Os registros de fluxo estão organizados em grupos ou fragmentos. Cada fragmento atua como um contêiner para vários registros de fluxo e contém informações necessárias para acessar esses registros e fazer iterações neles. Os registros de fluxo em um fragmento são removidos automaticamente depois de 24 horas.

Fragmentos são efêmeros: eles são criados e excluídos automaticamente, conforme necessário. Qualquer fragmento também pode ser dividido em vários novos fragmentos, o que também ocorre automaticamente. (Também é possível que um fragmento pai tenha apenas um fragmento filho.) Um fragmento pode ser dividido em resposta a altos níveis de atividades de gravação em sua tabela principal e, portanto, as aplicações podem processar registros de vários fragmentos em paralelo.

Se você desabilitar um fluxo, todos os fragmentos que estiverem abertos serão fechados. Os dados no stream continuarão legíveis por 24 horas.

Como fragmentos têm uma linhagem (pai e filhos), uma aplicação sempre deverá processar um fragmento pai antes de um fragmento filho. Isso ajuda a garantir que os registros de fluxo também sejam processados na ordem correta. (Se você usa o DynamoDB Streams Kinesis Adapter, isso será feito para você. Sua aplicação processará os fragmentos e os registros de fluxo na ordem correta. Ela manipulará automaticamente fragmentos novos ou expirados, bem como fragmentos que são divididos enquanto a aplicação está em execução. Para obter mais informações, consulte Usar o adaptador do DynamoDB Streams Kinesis Adapter para processar registros de fluxos.)

O diagrama a seguir mostra a relação entre um fluxo, os fragmentos nesse fluxo e os registros de fluxo nesses fragmentos.

nota

Se você executar uma operação PutItem ou UpdateItem que não altere nenhum dado em um item, o DynamoDB Streams não gravará um registro de fluxo para essa operação.

Para acessar um fluxo e processar os registros de fluxo dentro dele, você deve fazer o seguinte:

• Determinar o ARN exclusivo do fluxo que deseja acessar.

• Determinar quais fragmentos no fluxo contêm os registros de fluxo desejados.

• Acessar os fragmentos e recuperar os registros de fluxo desejados.

nota

No máximo dois processos devem estar lendo simultaneamente do mesmo fragmento de fluxo. Ter mais de dois leitores por fragmento pode resultar em controle de utilização.

A API do DynamoDB Streams fornece as seguintes ações para uso por programas de aplicações:

• ListStreams: retorna uma lista de descritores de fluxos para a conta e o endpoint atuais. Opcionalmente, você pode solicitar apenas os descritores de fluxo de um nome de tabela específico.

• DescribeStream: retorna informações detalhadas sobre um determinado fluxo. A saída inclui uma lista de fragmentos associados ao fluxo, incluindo os IDs desses fragmentos.

• GetShardIterator: retorna um iterador de fragmentos que descreve um local dentro de um fragmento. Você pode solicitar que o iterador forneça acesso ao ponto mais antigo, o ponto mais novo ou um ponto específico no fluxo.

• GetRecords: retorna os registros do fluxo de um determinado fragmento. Você deve fornecer o iterador de fragmentos retornado de uma solicitação GetShardIterator.

Para obter descrições completas dessas operações da API, incluindo solicitações e respostas de exemplo, consulte a Referência da API do Amazon DynamoDB Streams.

Limite de retenção de dados para o DynamoDB Streams

Todos os dados no DynamoDB Streams estão sujeitos a um tempo de vida de 24 horas. É possível recuperar e analisar as atividades das últimas 24 horas de qualquer tabela. No entanto, os dados mais antigos que 24 horas estão suscetíveis a remoção a qualquer momento.

Se você desabilitar um fluxo em uma tabela, os dados nesse fluxo continuarão legíveis por 24 horas. Depois desse tempo, os dados expirarão, e os registros de fluxo serão excluídos automaticamente. Não há nenhum mecanismo para excluir manualmente um fluxo existente. Aguarde até que o limite de retenção expire (24 horas), e todos os registros do fluxo sejam excluídos.