Creación y administración de flujos en QLDB

Amazon QLDB proporciona operaciones de API para crear y administrar un flujo de datos de diario desde su libro mayor a Amazon Kinesis Data Streams. El secuencia de QLDB captura cada revisión del documento consignadas a su diario y la envía a un flujo de datos de Kinesis.

Puede usar el AWS Management Console, un AWS SDK o el AWS Command Line Interface (AWS CLI) para crear una transmisión de diario. Además, también puede usar una plantilla AWS CloudFormation para crear flujos. Para obtener más información, consulte el AWS::QLDB::Streamrecurso en la Guía del AWS CloudFormation usuario.

Parámetros de flujo

Para crear una secuencia de diario de QLDB, debe proporcionar los siguientes parámetros de configuración:

Nombre del libro mayor

El libro mayor de QLDB cuyos datos de diario desea transmitir a Kinesis Data Streams.

Nombre de flujo

Nombre que desea asignar al flujo de diario QLDB. Los nombres definidos por el usuario pueden ayudar a identificar e indicar el propósito de un flujo.

El nombre del flujo debe ser único entre otros flujos activos de un libro mayor determinado. Los nombres de los flujos tienen las mismas restricciones de denominación que los nombres de los libros mayores, tal como se definen en Cuotas y límites de Amazon QLDB.

Además del nombre del flujo, QLDB asigna un ID de flujo a cada secuencia de QLDB que cree. El ID de flujo es único entre todos los flujos de un registro determinado, independientemente de su estado.

Fecha y hora de inicio

La fecha y la hora a partir de las cuales se iniciará el flujo de datos del diario. Este valor puede ser cualquier fecha y hora del pasado, pero no puede estar en el futuro.

Fecha y hora de finalización

(Opcional) La fecha y hora exclusivas que especifican cuándo termina el flujo.

Si crea un flujo indefinido sin hora de finalización, debe cancelarlo manualmente para finalizarlo. También puede cancelar un flujo finito y activo que aún no haya alcanzado la fecha y hora de finalización especificadas.

Flujo de datos de Kinesis de destino

El recurso de destino de Kinesis Data Streams en el que el flujo escribe los registros de datos. Para obtener información acerca de la creación de un flujo de datos de Kinesis, consulte Creación y actualización de secuencias de datos en la Guía para desarrolladores de Amazon Kinesis Data Streams.

importante

• No se admite el flujo entre cuentas ni entre regiones. El flujo de datos de Kinesis especificado debe estar en las mismas Región de AWS y cuenta que su libro mayor.

• La agregación de registros en Kinesis Data Streams está habilitada de forma predeterminada. Esta opción permite a QLDB publicar varios registros de datos en un único registro de Kinesis Data Streams, lo que aumenta el número de registros enviados por llamada a la API.

  La agregación de registros tiene importantes implicaciones para el procesamiento de registros y requiere la desagrupación en su consumidor de flujos. Para obtener más información, consulte Conceptos clave de KPL y Desagrupación del consumidor en la Guía para desarrolladores de Amazon Kinesis Data Streams.

Rol de IAM

El rol de IAM que permite a QLDB asumir permisos de escritura en su flujo de datos de Kinesis. Puede usar la consola de QLDB para crear automáticamente este rol o puede crearlo manualmente en IAM. Para aprender a crearlo manualmente, consulte Permisos de secuencia.

Para transferir un rol a QLDB al solicitar una secuencia, debe tener permisos para realizar la acción iam:PassRole en el recurso de rol de IAM.

ARN de flujo

Cada flujo de diario de QLDB es un subrecurso de un libro mayor y se identifica de forma inequívoca mediante un nombre de recurso de Amazon (ARN). El siguiente es un ejemplo de ARN de una secuencia de QLDB con un ID de flujo de IiPT4brpZCqCq3f4MTHbYy para un libro mayor denominado exampleLedger.

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

En la siguiente sección se describe cómo crear y cancelar una secuencia de QLDB mediante AWS Management Console.

AWS Management Console

Siga estos pasos para crear o cancelar una secuencia de QLDB mediante la consola de QLDB.

Creación de una etiqueta (consola)

1. Inicie sesión en la consola AWS Management Console de Amazon QLDB y ábrala en https://console.aws.amazon.com/qldb.

2. Elija Flujos en el panel de navegación.

3. Seleccione Crear la secuencia de QLDB.

4. En la página Crear la secuencia de QLDB, introduzca los siguientes ajustes:

   • Nombre de la secuencia: nombre que desea asignar a la secuencia de diario QLDB.

   • Libro mayor: el libro mayor cuyos datos del diario desea transmitir.

   • Fecha y hora de inicio: marca de tiempo inclusiva en la Hora universal coordinada (UTC) a partir de la cual se iniciará el flujo de datos del diario. Esta marca de hora tiene por defecto la hora y fecha actuales. No puede ser en el futuro y debe ser anterior a la fecha y hora de finalización.

   • Fecha y hora de finalización: (opcional) la marca de tiempo exclusiva (UTC) que especifica cuándo finaliza el flujo. Si no define este parámetro, el flujo se ejecutará indefinidamente hasta que lo cancele.

   • Secuencia de destino: el recurso de destino de Kinesis Data Streams en el que el flujo escribe los registros de datos. Use el siguiente formato ARN.

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

     A continuación, se muestra un ejemplo.

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

     No se admite el flujo entre cuentas ni entre regiones. El flujo de datos de Kinesis especificado debe estar en la misma cuenta Región de AWS y cuenta que su libro mayor.

   • Habilitar la agregación de registros en Kinesis Data Streams: (habilitada de forma predeterminada) permite a QLDB publicar varios registros de datos en un único registro de Kinesis Data Streams, lo que aumenta el número de registros enviados por llamada a la API.

   • Acceso al servicio: el rol de IAM que otorga permisos de escritura de QLDB a su flujo de datos de Kinesis.

     Para transferir un rol a QLDB al solicitar una secuencia, debe tener permisos para realizar la acción iam:PassRole en el recurso de rol de IAM.

     • Cree y utilice un nuevo rol de servicio: deje que la consola cree un nuevo rol para usted con los permisos necesarios para el flujo de datos de Kinesis especificado.

     • Utilizar un rol de servicio existente: para obtener información sobre cómo crear manualmente este rol en IAM, consulte Permisos de secuencia.

   • Etiquetas: (opcional) agregue metadatos al flujo asociando etiquetas como pares de clave-valor. Puede añadir etiquetas a los flujos para facilitar su organización e identificación. Para obtener más información, consulte Etiquetado de recursos de Amazon QLDB.

     Elija Agregar etiqueta y, a continuación, introduzca cualquier par clave-valor según corresponda.

5. Cuando esté conforme con los ajustes, elija Crear secuencia de QLDB.

   Si la solicitud se envía correctamente, la consola vuelve a la página principal de Secuencias y muestra las secuencias QLDB con su estado actual.

6. Una vez que la secuencia esté activa, utilice Kinesis para procesar los datos del flujo con una aplicación para consumidores.

   Abra la consola Kinesis Data Streams en https://console.aws.amazon.com/kinesis.

Para obtener información sobre el formato de los registros de datos de secuencia, consulte Registros de secuencia de QLDB en Kinesis.

Para obtener información sobre cómo administrar las secuencias que provocan un error, consulte Gestión de secuencias dañadas.

Cómo cancelar una etiqueta (consola)

No puede reiniciar una secuencia de QLDB después de cancelarlo. Para reanudar la entrega de sus datos a Kinesis Data Streams, puede crear una nueva secuencia de QLDB.

1. Abra la consola de Amazon QLDB en https://console.aws.amazon.com/qldb.

2. Elija Flujos en el panel de navegación.

3. En la lista de secuencias de QLDB, seleccione la secuencia activa que desea cancelar.

4. Seleccione Cancelar paso. Confirme ingresando cancel stream en el cuadro provisto.

Para obtener información sobre el uso de la API de QLDB con AWS un SDK o AWS CLI para crear y administrar transmisiones de diarios, consulte. Desarrollo con secuencias en QLDB

Estado de la secuencia

El estado de una secuencia de QLDB puede ser uno de los siguientes:

• ACTIVE: está transmitiendo datos actualmente o esperando para transmitirlos (si se trata de una secuencia indefinida sin hora de finalización).

• COMPLETED: ha finalizado correctamente la secuencia de todos los bloques del diario dentro del intervalo de tiempo especificado. Se trata de un estado terminal.

• CANCELED: ha sido finalizada por una solicitud de un usuario antes de la hora de finalización especificada y ya no está transmitiendo datos de forma activa. Se trata de un estado terminal.

• IMPAIRED: no puede escribir registros en Kinesis debido a un error que requiere su acción. Se trata de un estado recuperable y no terminal.

  Si resuelve el error en el plazo de una hora, la secuencia pasará automáticamente al estado ACTIVE. Si el error sigue sin resolverse después de una hora, la secuencia pasa automáticamente al estado FAILED.

• FAILED: no puede escribir registros en Kinesis debido a un error y se encuentra en un estado terminal irrecuperable.

El siguiente diagrama ilustra cómo un recurso de secuencia de QLDB puede realizar la transición entre estados.

Vencimiento de las secuencias terminales

Los recursos de secuencia que se encuentran en un estado terminal (CANCELED, COMPLETED y FAILED) están sujetos a un período de retención de 7 días. Una vez transcurrido este límite, se eliminan automáticamente de forma permanente.

Después de eliminar una secuencia terminal, ya no podrá utilizar la consola de QLDB o la API de QLDB para describir o enumerar el recurso de secuencia.

Gestión de secuencias dañadas

Si la secuencia encuentra un error, pasará primero al estado IMPAIRED. QLDB continúa reintentando las secuencias IMPAIRED durante un máximo de una hora.

Si resuelve el error en el plazo de una hora, la secuencia pasará automáticamente al estado ACTIVE. Si el error sigue sin resolverse después de una hora, la secuencia pasa automáticamente al estado FAILED.

Una secuencia defectuosa o fallida puede tener una de las siguientes causas de error:

• KINESIS_STREAM_NOT_FOUND: el recurso de Kinesis Data Streams de destino no existe. Compruebe que el flujo de datos de Kinesis que proporcionó en su solicitud de secuencia de QLDB sea correcto. A continuación, vaya a Kinesis y cree el flujo de datos que especificó.

• IAM_PERMISSION_REVOKED: QLDB no tiene permisos suficientes para escribir registros de datos en el flujo de datos de Kinesis especificado. Compruebe que ha definido una política para el flujo de datos de Kinesis especificado que conceda al servicio QLDB permisos (qldb.amazonaws.com) para las siguientes acciones:

  • kinesis:PutRecord

  • kinesis:PutRecords

  • kinesis:DescribeStream

  • kinesis:ListShards

Monitorización de secuencias dañadas

Si una secuencia se interrumpe, la consola de QLDB muestra un banner con detalles sobre la secuencia y el error que ha encontrado. También puede utilizar la operación de la API DescribeJournalKinesisStream para obtener el estado de una secuencia y la causa del error subyacente.

Además, puedes usar Amazon CloudWatch para crear una alarma que monitorice la IsImpaired métrica de una transmisión. Para obtener información sobre la supervisión de las métricas CloudWatch de QLDB con, consulte. Dimensiones y métricas de Amazon QLDB