Criar e gerenciar fluxos no QLDB

O Amazon QLDB fornece operações de API para criar e gerenciar um fluxo de dados de diário do seu ledger para o Amazon Kinesis Data Streams. O fluxo do QLDB captura todas as revisões de documentos confirmadas no seu diário e as envia para um fluxo de dados do Kinesis.

Você pode usar o AWS Management Console, um AWS SDK ou o AWS Command Line Interface (AWS CLI) para criar um stream de diário. Além disso, você também pode usar um modelo AWS CloudFormation para criar fluxos. Para obter mais informações, consulte o AWS::QLDB::Streamrecurso no Guia AWS CloudFormation do usuário.

Parâmetros de fluxo

Para criar um fluxo de diário do QLDB, você deve fornecer os seguintes parâmetros de configuração:

Nome do ledger

O ledger do QLDB cujos dados de diário você deseja transmitir para o Kinesis Data Streams.

Nome do fluxo

O nome que você deseja atribuir ao stream de diário do QLDB. Os nomes definidos pelo usuário podem ajudar a identificar e indicar a finalidade de um stream.

O nome do fluxo deve ser exclusivo entre outros fluxos ativos em um ledger. Os nomes de fluxos têm as mesmas restrições de nomenclatura que os nomes do ledger, conforme definido em Cotas e limites no Amazon QLDB.

Além do nome do fluxo, o QLDB atribui um ID de fluxo a cada fluxo do QLDB que você cria. O ID do fluxo é exclusivo entre todos os fluxos de um determinado ledger, independentemente de seu status.

Data e hora de início

A data e hora de início a partir das quais iniciar o streaming de dados do diário. Esse valor pode ser qualquer data e hora no passado, mas não no futuro.

Data e hora de encerramento

(Opcional) A data e hora exclusivas que especificam quando o fluxo termina.

Se você criar um fluxo indefinido sem hora de término, deverá cancelá-lo manualmente para finalizar o fluxo. Você também pode cancelar um fluxo ativo e finito que ainda não tenha atingido a data e a hora de término especificadas.

Fluxo de dados do Kinesis de destino

O recurso de destino do Kinesis Data Streams no qual seu fluxo grava os registros de dados. Para saber como criar um fluxo de dados do Kinesis, consulte Criação e atualização de fluxos de dados no Guia do desenvolvedor do Amazon Kinesis Data Streams.

Importante

• Não há suporte para streams entre contas e entre regiões. O fluxo de dados do Kinesis especificado deve estar na mesma Região da AWS conta do seu livro contábil.

• A agregação de registros no Kinesis Data Streams está ativada por padrão. Essa opção permite que o QLDB publique vários registros de dados em um único registro do Kinesis Data Streams, aumentando o número de registros enviados por chamada de API.

  A agregação de registros tem implicações importantes para o processamento de registros e requer desagregação em seu consumidor de stream. Para saber mais, consulte Conceitos-chave de KPL e Desagregação do consumidor no Guia do desenvolvedor do Amazon Kinesis Data Streams.

IAM role (Perfil do IAM)

O perfil do IAM que permite que o QLDB assuma permissões de gravação em seu fluxo de dados do Kinesis. Você pode usar o console do QLDB para criar automaticamente essa função ou criá-la manualmente no IAM. Para saber como criá-la manualmente, consulte Permissões de fluxo.

Para transmitir uma função ao QLDB ao solicitar um fluxo de diário, você deve ter permissões para realizar a ação iam:PassRole no recurso do perfil do IAM.

Stream ARN

Cada fluxo de diário do QLDB é um sub-recurso de um ledger e é identificado exclusivamente por um nome do recurso da Amazon (ARN). A seguir está um exemplo de ARN de um fluxo QLDB com um ID de fluxo IiPT4brpZCqCq3f4MTHbYy de um ledger chamado exampleLedger.

arn:aws:qldb:us-east-1:123456789012:stream/exampleLedger/IiPT4brpZCqCq3f4MTHbYy

A seção a seguir descreve como criar e cancelar um fluxo do QLDB usando o AWS Management Console.

AWS Management Console

Siga estas etapas para criar ou cancelar um fluxo do QLDB usando o console do QLDB.

Para criar um fluxo (console)

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

2. Selecione Streams (Fluxos) no painel de navegação.

3. Escolha Criar fluxo do QLDB.

4. Na página Criar fluxo do QLDB, insira as seguintes configurações:

   • Nome do fluxo – O nome que você deseja atribuir ao fluxo de diário do QLDB.

   • ledger — O ledger cujos dados do diário você deseja transmitir.

   • Data e hora de início - o registro de data e hora inclusivo no Coordinated Universal Time (UTC) a partir do qual iniciar o streaming de dados do diário. O padrão desse timestamp é a data e hora atual. Não pode ser no futuro e deve ser anterior à data e hora de término.

   • Data e hora de término — (Opcional) O carimbo de data/hora exclusivo (UTC) que especifica quando o fluxo termina. Se você deixar esse parâmetro em branco, o fluxo será executado indefinidamente até ser cancelado.

   • Stream de destino — O recurso de destino do Kinesis Data Streams no qual seu fluxo grava os registros de dados. Use o formato de ARN abaixo.

     arn:aws:kinesis:aws-region:account-id:stream/kinesis-stream-name

     Veja um exemplo a seguir.

     arn:aws:kinesis:us-east-1:123456789012:stream/stream-for-qldb

     Não há suporte para streams entre contas e entre regiões. O stream de dados especificado do Kinesis deve estar na mesma conta Região da AWS e na mesma conta do seu livro contábil.

   • Ativar a agregação de registros no Kinesis Data Streams — (ativado por padrão) Permite que o QLDB publique vários registros de dados em um único registro do Kinesis Data Streams, aumentando o número de registros enviados por chamada de API.

   • Acesso ao serviço — o perfil do IAM que concede permissões de gravação do QLDB ao seu fluxo de dados do Kinesis.

     Para transmitir uma função ao QLDB ao solicitar um fluxo de diário, você deve ter permissões para realizar a ação iam:PassRole no recurso do perfil do IAM.

     • Crie e use um novo perfil de serviço — deixe o console criar uma nova função para você com as permissões necessárias para o fluxo de dados do Kinesis especificado.

     • Use um perfil de serviço existente — Para saber como criar essa função manualmente no IAM, consulte Permissões de fluxo.

   • Tags - (Opcional) Adicione metadados ao fluxo anexando tags como pares de chave-valor. Você pode adicionar tags ao seu fluxo para ajudar a organizar e identificá-los. Para ter mais informações, consulte Como marcar recursos do Amazon QLDB.

     Escolha Adicionar tag e, em seguida, insira os pares de valores-chave, conforme apropriado.

5. Quando estiver satisfeito com as configurações, escolha Criar fluxo de QLDB.

   Se o envio da solicitação for bem-sucedido, o console retornará à página principal de Fluxos e listará seus fluxos do QLDB com o status atual.

6. Depois que seu fluxo estiver ativo, use o Kinesis para processar seus dados de fluxo com um aplicativo de consumidor.

   Abra o console do Kinesis Data Streams em https://console.aws.amazon.com/kinesis.

Para obter mais informações sobre o formato dos registros de dados de fluxo, consulte Registros de fluxo do QLDB no Kinesis.

Para saber como lidar com fluxos que resultam em erro, consulte Tratamento de fluxos prejudicados.

Para cancelar um fluxo (console)

Você não pode reiniciar um fluxo do QLDB depois de cancelá-lo. Para retomar a entrega de seus dados para o Kinesis Data Streams, você pode criar um novo fluxo do QLDB.

1. Abra o console do Amazon QLDB em https://console.aws.amazon.com/qldb.

2. Selecione Streams (Fluxos) no painel de navegação.

3. Na lista de fluxos do QLDB, selecione o fluxo ativo que você deseja cancelar.

4. Escolha Cancelar fluxo. Confirme isso inserindo cancel stream na caixa fornecida.

Para obter informações sobre como usar a API QLDB com AWS um SDK ou para criar e gerenciar AWS CLI fluxos de diários, consulte. Desenvolvendo com fluxos no QLDB

Estados de fluxo

O status de um fluxo do QLDB pode ser um dos seguintes:

• ACTIVE— No momento, está transmitindo ou aguardando para transmitir dados (para um fluxo indefinido sem hora de término).

• COMPLETED— Concluiu com sucesso o streaming de todos os blocos de diário dentro do intervalo de tempo especificado. Este é um estado terminal.

• CANCELED— Foi encerrado por uma solicitação do usuário antes do horário de término especificado e não está mais transmitindo dados ativamente. Este é um estado terminal.

• IMPAIRED— Não é possível gravar registros no Kinesis devido a um erro que exige sua ação. Esse é um estado recuperável e não terminal.

  Se você resolver o erro em uma hora, o stream será automaticamente transferido para o estado ACTIVE. Se o erro continuar sem solução após uma hora, o stream passa automaticamente para o estado FAILED.

• FAILED— Não consegue gravar registros no Kinesis devido a um erro e está em um estado terminal irrecuperável.

O diagrama a seguir ilustra como um recurso de fluxo do QLDB pode fazer a transição entre estados.

Expiração para fluxos terminais

Os recursos de fluxo que estão em um estado terminal (CANCELED, COMPLETED, e FAILED) estão sujeitos a um período de retenção de 7 dias. Eles são excluídos automaticamente após a expiração desse limite.

Depois que um fluxo terminal é excluído, você não pode mais usar o console do QLDB ou a API do QLDB para descrever ou listar o recurso do fluxo.

Tratamento de fluxos prejudicados

Se seu fluxo encontrar um erro, ele será movido para o estado IMPAIRED primeiro. O QLDB continua a repetir os fluxos IMPAIRED por até uma hora.

Se você resolver o erro em uma hora, o stream será automaticamente transferido para o estado ACTIVE. Se o erro continuar sem solução após uma hora, o stream passa automaticamente para o estado FAILED.

Um fluxo danificado ou com falha pode ser uma das seguintes causas de erro:

• KINESIS_STREAM_NOT_FOUND— O recurso Kinesis Data Streams de destino não existe. Verifique se o fluxo de dados do Kinesis que você forneceu em sua solicitação de fluxo do QLDB está correto. Em seguida, acesse Kinesis e crie o fluxo de dados que você especificou.

• IAM_PERMISSION_REVOKED— O QLDB não tem permissões suficientes para gravar registros de dados em seu fluxo de dados do Kinesis especificado. Verifique se você define uma política para o fluxo de dados do Kinesis especificado que conceda ao serviço QLDB (qldb.amazonaws.com) permissões para as seguintes ações:

  • kinesis:PutRecord

  • kinesis:PutRecords

  • kinesis:DescribeStream

  • kinesis:ListShards

Monitorar os fluxos prejudicados

Se um fluxo for prejudicado, o console do QLDB exibirá um banner que mostra detalhes sobre o fluxo e o erro encontrado. Você também pode usar a operação da DescribeJournalKinesisStream API para obter o status de um fluxo e a causa do erro subjacente.

Além disso, você pode usar CloudWatch a Amazon para criar um alarme que monitora a IsImpaired métrica de um stream. Para obter informações sobre o monitoramento de métricas CloudWatch do QLDB com, consulte. Dimensões e métricas do Amazon QLDB