Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Desarrollo de productores con Amazon Kinesis Producer Library (KPL)
Un productor de Amazon Kinesis Data Streams es una aplicación que coloca los registros de datos de usuario en un flujo de datos de Kinesis Data Streams (también denominado *ingesta de datos*). Amazon Kinesis Producer Library (KPL) simplifica el desarrollo de aplicaciones productoras y permite a los desarrolladores alcanzar un mayor rendimiento de escritura en un flujo de datos de Kinesis Data Streams.
Puedes monitorizar la KPL con Amazon CloudWatch. Para obtener más información, consulte [Supervise la biblioteca de Kinesis Producer con Amazon CloudWatch](monitoring-with-kpl.md).
**Topics**
+ [Revisar el rol de KPL](#developing-producers-with-kpl-role)
+ [Descubrir las ventajas del uso de KPL](#developing-producers-with-kpl-advantage)
+ [Comprender cuándo no usar la KPL](#developing-producers-with-kpl-when)
+ [Instalar el KPL](kinesis-kpl-dl-install.md)
+ [Migrar de KPL 0.x a KPL 1.x](kpl-migration-1x.md)
+ [Transicionar a los certificados de Amazon Trust Services (ATS) para la KPL](kinesis-kpl-upgrades.md)
+ [Plataformas compatibles con KPL](kinesis-kpl-supported-plats.md)
+ [Conceptos clave de KPL](kinesis-kpl-concepts.md)
+ [Integrar la KPL con el código de productor](kinesis-kpl-integration.md)
+ [Escribir en Kinesis Data Stream mediante KPL](kinesis-kpl-writing.md)
+ [Configurar Amazon Kinesis Producer Library](kinesis-kpl-config.md)
+ [Implementar la desagregación de consumidores](kinesis-kpl-consumer-deaggregation.md)
+ [Usar KPL con Amazon Data Firehose](kpl-with-firehose.md)
+ [Utilice el KPL con el registro de AWS Glue esquemas](kpl-with-schemaregistry.md)
+ [Configurar la configuración del proxy de KPL](kpl-proxy-configuration.md)
+ [Política de ciclo de vida de la versión de KPL](kpl-version-lifecycle-policy.md)
**nota**
Se recomienda actualizar a la versión más reciente de KPL. KPL se actualiza periódicamente con versiones más recientes que incluyen los últimos parches de dependencia y seguridad, correcciones de errores y nuevas características compatibles con versiones anteriores. Para obtener más información, consulte [https://github.com/awslabs/amazon-kinesis-producer/releases/](https://github.com/awslabs/amazon-kinesis-producer/releases/).
## Revisar el rol de KPL
La KPL es una easy-to-use biblioteca altamente configurable que le ayuda a escribir en una transmisión de datos de Kinesis. Ejerce de intermediaria entre el código de la aplicación de productor y las acciones de la API de Kinesis Data Streams. KPL realiza las siguientes tareas principales:
+ Escribe en uno o varios flujo de datos de Kinesis con un mecanismo de reintento automático y configurable
+ Recopila registros y utiliza `PutRecords` para escribir varios registros en varios fragmentos por solicitud
+ Acumula registros de usuario para aumentar el tamaño de la carga y mejorar el rendimiento
+ Se integra perfectamente con [Kinesis Client Library](https://docs.aws.amazon.com/kinesis/latest/dev/developing-consumers-with-kcl.html) (KCL) para desagrupar registros en lotes en el consumidor
+ Envía las CloudWatch estadísticas de Amazon en tu nombre para proporcionar visibilidad sobre el rendimiento del productor
Tenga en cuenta que la KPL es diferente de la API de Kinesis Data Streams que está disponible en. [AWS SDKs](https://aws.amazon.com/tools/) La API de Kinesis Data Streams ayuda a administrar muchos aspectos de Kinesis Data Streams (como la creación de flujos, el cambio de las particiones de registros, así como la inserción y obtención de estos), mientras que KPL proporciona una capa de abstracción específica para la ingesta de datos. Para obtener información sobre la API de Kinesis Data Streams, consulte [Referencia de la API de Amazon Kinesis](https://docs.aws.amazon.com/kinesis/latest/APIReference/).
## Descubrir las ventajas del uso de KPL
La siguiente lista representa algunas de las ventajas más importantes de utilizar KPL para el desarrollo de productores de Kinesis Data Streams.
KPL puede utilizarse en casos de uso síncronos o asíncronos. Se recomienda utilizar el mayor rendimiento de la interfaz asíncrona a menos que haya una razón específica para utilizar un comportamiento síncrono. Para obtener más información sobre estos dos casos de uso y ver código de muestra, consulte [Escribir en Kinesis Data Stream mediante KPL](kinesis-kpl-writing.md).
**Beneficios de rendimiento**
KPL puede ayudar a crear productores de alto rendimiento. Piense en una situación en la que las instancias de Amazon EC2 sirven como un proxy para recopilar eventos de 100 bytes de cientos o miles de dispositivos de baja potencia y para escribir registros en un flujo de datos de Kinesis. Cada una de estas instancias EC2 debe escribir miles de eventos por segundo en la secuencia de datos. Para conseguir el nivel de rendimiento necesario, los productores deben implementar lógica complicada como, por ejemplo, la creación de lotes o la ejecución de subprocesos, además de lógica de reintento y desagrupación de registros en el lado del consumidor. KPL realiza todas estas tareas.
**Facilidad de uso en el lado del consumidor**
En el caso de los desarrolladores del lado del consumidor que usan KCL en Java, KPL se integra sin mayor esfuerzo. Cuando KCL recupera un registro agregado de Kinesis Data Streams que consta de varios registros de usuario de KPL, llama automáticamente a KPL para que extraiga los registro de usuario individuales antes de devolverlos al usuario.
Para los desarrolladores del lado del consumidor que no utilicen KCL, sino que, en su lugar, utilicen la operación de la API `GetRecords` directamente, hay disponible una biblioteca de Java de KPL que pueden usar para extraer los registros de los usuarios individuales antes de devolverlos al usuario.
**Monitoreo del productor**
Puede recopilar, supervisar y analizar a sus productores de Kinesis Data Streams mediante CloudWatch Amazon y la KPL. El KPL emite el rendimiento, los errores y otras métricas CloudWatch en su nombre, y se puede configurar para supervisarlo a nivel de transmisión, fragmento o productor.
**Arquitectura asíncrona**
Debido a que KPL puede almacenar en búfer los registros antes de enviarlos a Kinesis Data Streams, en la aplicación intermediaria no se fuerza el bloqueo y la espera a la confirmación de que el registro ha llegado al servidor antes de continuar con el tiempo de ejecución. Una llamada para insertar un registro en KPL siempre vuelve inmediatamente, y no se espera a que el registro se envíe o a que se reciba una respuesta desde el servidor. En su lugar, se crea un objeto `Future` que recibe el resultado de enviar el registro a Kinesis Data Streams en un momento posterior. Este comportamiento es el mismo que el de los clientes asíncronos del SDK. AWS
## Comprender cuándo no usar la KPL
KPL puede ocasionar un retraso adicional en el procesamiento de hasta `RecordMaxBufferedTime` en la biblioteca (configurable por el usuario). Los valores más altos de `RecordMaxBufferedTime` ofrecen un mayor eficacia de empaquetamiento y un mejor rendimiento. Es posible que las aplicaciones que no pueden tolerar este retraso tengan que utilizar el SDK de AWS directamente. Para obtener más información sobre el uso del AWS SDK con Kinesis Data Streams, [Desarrolle productores mediante la API Amazon Kinesis Data Streams con AWS SDK para Java](developing-producers-with-sdk.md) consulte. Para más información sobre `RecordMaxBufferedTime` y otras propiedades configurables por el usuario de KPL, consulte [Configurar Amazon Kinesis Producer Library](kinesis-kpl-config.md).
# Instalar el KPL
Amazon proporciona archivos binarios precompilados de Amazon Kinesis Producer Library (KPL) en C\$1\$1 para macOS, Windows y distribuciones recientes de Linux (para información detallada sobre las plataformas compatibles, consulte la siguiente sección). Estos archivos binarios se empaquetan como parte de archivos .jar de Java y se invocan y utilizan automáticamente si se usa Maven para instalar el paquete. Para encontrar las versiones más recientes de KPL y KCL, utilice los siguientes enlaces de búsqueda de Maven:
+ [KPL](https://search.maven.org/#search|ga|1|amazon-kinesis-producer)
+ [KCL](https://search.maven.org/#search|ga|1|amazon-kinesis-client)
Los archivos binarios de Linux han sido compilados con la recopilación del compilador GNU (GCC) y están vinculados estáticamente con libstdc\$1\$1 en Linux. Lo esperable es que funcionen en cualquier distribución de Linux de 64 bits que incluya una versión de glibc 2.5 o superior.
Los usuarios de distribuciones Linux anteriores pueden compilar el KPL siguiendo las instrucciones de compilación incluidas en el código fuente. GitHub Para descargar el KPL GitHub, consulte la biblioteca [Amazon Kinesis](https://github.com/awslabs/amazon-kinesis-producer) Producer Library.
**importante**
Amazon Kinesis Producer Library (KPL) 0.x estará disponible el 30 de end-of-support enero de 2026. **Recomendamos** migrar las aplicaciones de KCL que utilizan la versión 0.x a la versión más reciente de KPL antes del 30 de enero de 2026. Para encontrar la versión más reciente de KPL, consulte la [página de KPL en Github](https://github.com/awslabs/amazon-kinesis-producer). Para obtener información sobre cómo migrar de KCL 0.x a KCL 1.x, consulte [Migrar de KPL 0.x a KPL 1.x](kpl-migration-1x.md).
# Migrar de KPL 0.x a KPL 1.x
En este tema se proporcionan step-by-step instrucciones para migrar a su consumidor de KPL 0.x a KPL 1.x. KPL 1.x introduce la compatibilidad con la versión AWS SDK para Java 2.x y, al mismo tiempo, mantiene la compatibilidad de la interfaz con las versiones anteriores. No es necesario actualizar su lógica principal de procesamiento de datos para migrar a KPL 1.x.
1. **Asegúrese de que tenga los siguientes requisitos previos:**
+ Java Development Kit (JDK) 8 o posterior,
+ AWS SDK para Java 2.x
+ Maven o Gradle para la administración de dependencias.
1. **Añadir dependencias**
Si está utilizando Maven, agregue la siguiente dependencia a su archivo pom.xml. Asegúrese de actualizar groupId de `com.amazonaws` a `software.amazon.kinesis` y la versión `1.x.x` a la versión más reciente de KPL.
```
software.amazon.kinesis
amazon-kinesis-producer
1.x.x
```
Si está utilizando Gradle, agregue lo siguiente a su archivo `build.gradle`. Asegúrese de reemplazar `1.x.x` por la versión más reciente de KPL.
```
implementation 'software.amazon.kinesis:amazon-kinesis-producer:1.x.x'
```
Puede buscar la versión más reciente del KPL en el [Repositorio central de Maven](https://central.sonatype.com/search?q=amazon-kinesis-producer).
1. **Actualizar las declaraciones de importación de KPL**
KPL 1.x usa la versión AWS SDK para Java 2.x y usa un nombre de paquete actualizado que comienza por`software.amazon.kinesis`, en comparación con el nombre de paquete del KPL anterior que comenzaba por. `com.amazonaws.services.kinesis`
Sustituya la importación de `com.amazonaws.services.kinesis` con `software.amazon.kinesis`. En la siguiente tabla se muestran las importaciones que se deben reemplazar.
**Importar reemplazos**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/streams/latest/dev/kpl-migration-1x.html)
1. **Actualice las declaraciones de importación para AWS las clases de proveedores de credenciales**
Al migrar a KPL 1.x, debe actualizar los paquetes y las clases que importe en el código de la aplicación KPL que estén basados en la versión AWS SDK para Java 1.x por los correspondientes basados en la versión 2.x. AWS SDK para Java Las importaciones habituales en la aplicación KPL son las clases de proveedores de credenciales. Consulte los [cambios en el proveedor de credenciales](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-client-credentials.html) en la documentación de la guía de migración de la AWS SDK para Java versión 2.x para ver la lista completa de cambios en el proveedor de credenciales. Este es el cambio de importación habitual que necesitará para realizar en sus aplicaciones de KPL.
**Importar en KPL 0.x**
```
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
```
**Importar en KPL 1.x**
```
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
```
Si importa otros proveedores de credenciales basados en la versión AWS SDK para Java 1.x, debe actualizarlos por los equivalentes a la versión AWS SDK para Java 2.x. Si no has importado ninguno classes/packages de la versión AWS SDK para Java 1.x, puedes ignorar este paso.
1. **Actualice la configuración del proveedor de credenciales en la configuración de KPL**
La configuración del proveedor de credenciales en KPL 1.x requiere los proveedores de credenciales AWS SDK para Java 2.x. Si va a pasar los proveedores de credenciales de la versión AWS SDK para Java 1.x a la `KinesisProducerConfiguration` sustituyendo el proveedor de credenciales predeterminado, debe actualizarlo con los proveedores de credenciales de la versión AWS SDK para Java 2.x. Consulte [los cambios en el proveedor de credenciales](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-client-credentials.html) en la documentación de la guía de migración de la AWS SDK para Java versión 2.x para ver la lista completa de cambios en el proveedor de credenciales. Si no anuló el proveedor de credenciales predeterminado en la configuración de KPL, puede omitir este paso.
Por ejemplo, si va a anular el proveedor de credenciales predeterminado para KPL con el siguiente código:
```
KinesisProducerConfiguration config = new KinesisProducerConfiguration();
// SDK v1 default credentials provider
config.setCredentialsProvider(new DefaultAWSCredentialsProviderChain());
```
Debe actualizarlos con el siguiente código para usar el proveedor de credenciales AWS SDK para Java 2.x:
```
KinesisProducerConfiguration config = new KinesisProducerConfiguration();
// New SDK v2 default credentials provider
config.setCredentialsProvider(DefaultCredentialsProvider.create());
```
# Transicionar a los certificados de Amazon Trust Services (ATS) para la KPL
El 9 de febrero de 2018, a las 9:00 h (PST), Amazon Kinesis Data Streams instaló certificados ATS. Si desea continuar escribiendo registros en Kinesis Data Streams con Amazon Kinesis Producer Library (KPL) debe actualizar la instalación de KPL a la [versión 0.12.6](http://search.maven.org/#artifactdetails|com.amazonaws|amazon-kinesis-producer|0.12.6|jar) o posterior. Este cambio afecta a todas las AWS regiones.
Para obtener información sobre el cambio a ATS, consulte [Cómo prepararse para AWS el traslado a su propia autoridad de certificación](https://aws.amazon.com/blogs/security/how-to-prepare-for-aws-move-to-its-own-certificate-authority/).
Si tiene problemas y necesita soporte técnico, [cree un caso](https://console.aws.amazon.com/support/v1#/case/create) en el Centro de AWS Support.
# Plataformas compatibles con KPL
Amazon Kinesis Producer Library (KPL) está escrito en C\$1\$1 y se ejecuta como un proceso secundario del proceso principal de usuario. Los binarios nativos precompilados de 64 bits se empaquetan con la versión de Java y vuelven a ser administrados por la clase contenedora Java.
El paquete de Java se ejecuta sin necesidad de instalar otras bibliotecas en los siguientes sistemas operativos:
+ Distribuciones de Linux con kernel 2.6.18 (septiembre de 2006) y posteriores
+ Apple iOS X 10.9 y versiones posteriores
+ Windows Server 2008 y posteriores
**importante**
Windows Server 2008 y las versiones posteriores son compatibles con todas las versiones de KPL hasta la versión 0.14.0.
La plataforma Windows NO es compatible a partir de la versión 0.14.0 o superior de KPL.
Tenga en cuenta que KPL solo es compatible con sistemas de 64 bits.
## Código fuente
Si los archivos binarios proporcionados en la instalación de KPL no son suficientes para el entorno, el núcleo de KPL se escribirá como un módulo C\$1\$1. El código fuente del módulo C\$1\$1 y la interfaz Java se publican bajo la licencia pública de Amazon y están disponibles GitHub en la biblioteca de [productores de Amazon Kinesis](https://github.com/awslabs/amazon-kinesis-producer). Aunque KPL se puede utilizar en cualquier plataforma en la que estén disponibles un compilador C\$1\$1 y un JRE que cumplan los estándares recientes, Amazon no admite oficialmente ninguna plataforma que no figure en la lista de plataformas compatibles.
# Conceptos clave de KPL
Las siguientes secciones contienen conceptos y términos necesarios para comprender y utilizar Amazon Kinesis Producer Library (KPL).
**Topics**
+ [Registros](#kinesis-kpl-concepts-records)
+ [Agrupación en lotes](#kinesis-kpl-concepts-batching)
+ [Agregación](#kinesis-kpl-concepts-aggretation)
+ [Recopilación](#kinesis-kpl-concepts-collection)
## Registros
En esta guía, distinguimos entre *registros de usuario de KPL* y *registros de Kinesis Data Streams*. Cuando utilizamos el término *registro* sin ningún calificador, nos referimos a un *registro de usuario de KPL*. Cuando nos referimos a un registro de Kinesis Data Streams, decimos explícitamente *registro de Kinesis Data Streams*.
Un registro de usuario de KPL es un blob de datos que tiene un significado determinado para el usuario. Entre los ejemplos se incluyen un blob JSON que representa un evento de la interfaz de usuario en un sitio web, o una entrada de registro de un servidor web.
Un registro de Kinesis Data Streams es una instancia de la estructura de datos de `Record` definida por la API del servicio Kinesis Data Streams. Contiene una clave de partición, un número secuencial y un blob de datos.
## Agrupación en lotes
La *agrupación en lotes* se refiere a la realización de una sola acción en varios elementos en lugar de realizar la acción repetidamente en cada elemento individual.
En este contexto, el “elemento” es un registro, y la acción es enviarlo a Kinesis Data Streams. En una situación sin agrupación en lotes, cada registro se insertaría en un registro de Kinesis Data Streams independiente y se hará una solicitud HTTP para enviarlo a Kinesis Data Streams. Al agrupar en lotes, cada solicitud HTTP puede tener varios registros en lugar de solo uno.
KPL admite dos tipos de agrupación en lotes:
+ *Agregación*: almacenamiento de varios registros en un único registro de Kinesis Data Streams.
+ *Recopilación*: uso de la operación de la API `PutRecords` para enviar varios registros de Kinesis Data Streams a una o varias particiones del flujo de datos de Kinesis.
Los dos tipos de agrupación en lote de KPL se diseñaron para coexistir y se pueden activar o desactivar de forma independiente entre sí. Ambos están activados de forma predeterminada.
## Agregación
La *agregación* se refiere al almacenamiento de varios registros en un registro de Kinesis Data Streams. La agregación permite a los clientes aumentar el número de registros enviados por cada llamada a la API, lo que aumenta el rendimiento del productor de manera eficaz.
Las particiones de Kinesis Data Streams admiten hasta 1000 registros de Kinesis Data Streams por segundo o un rendimiento de 1 MB. El límite de registros de Kinesis Data Streams por segundo fuerza a los consumidores a usar registros de tamaño inferior a 1 KB. La agregación de registros en lote permite a los clientes combinar varios registros en un único registro de Kinesis Data Streams. Esto permite a los clientes mejorar su rendimiento por fragmento.
Piense en el caso de una partición en la región us-east-1 que se está ejecutando a una velocidad constante de 1000 registros por segundo, con registros de 512 bytes cada uno. Con la agregación de KPL puede empaquetar 1000 registros en solo 10 registros de Kinesis Data Streams, de manera que el número de registros por segundo se reduce a 10 (con 50 KB cada uno).
## Recopilación
La *recopilación* se refiere a agrupar en lote varios registros de Kinesis Data Streams y enviarlos en una única solicitud HTTP con una llamada a la operación de la API `PutRecords`, en lugar de enviar cada registro de Kinesis Data Streams en su propia solicitud HTTP.
Esto aumenta el rendimiento, si lo comparamos con una situación en la que no se use recopilación, ya que reduce la sobrecarga que implica realizar muchas solicitudes de HTTP independientes. De hecho, `PutRecords` en sí se ha diseñado específicamente para este fin.
La recopilación es diferente de la agregación, ya que funciona con grupos de registros de Kinesis Data Streams. Los registros de Kinesis Data Streams que se recopilan pueden contener varios registros del usuario. La relación se puede visualizar así:
```
record 0 --|
record 1 | [ Aggregation ]
... |--> Amazon Kinesis record 0 --|
... | |
record A --| |
|
... ... |
|
record K --| |
record L | | [ Collection ]
... |--> Amazon Kinesis record C --|--> PutRecords Request
... | |
record S --| |
|
... ... |
|
record AA--| |
record BB | |
... |--> Amazon Kinesis record M --|
... |
record ZZ--|
```
# Integrar la KPL con el código de productor
Amazon Kinesis Producer Library (KPL) se ejecuta en un proceso independiente y se comunica con el proceso principal de usuario mediante IPC. Esta arquitectura se denomina a veces [microservicio](http://en.wikipedia.org/wiki/Microservices), y se elige por dos razones principales:
**1) El proceso de usuario no se bloqueará aunque KPL se bloquee**
El proceso podría tener tareas no relacionadas con Kinesis Data Streams y así podría continuar la operación incluso si KPL se bloquea. También es posible que el proceso principal de usuario reinicie KPL y se recupere hasta alcanzar un estado totalmente funcional (esta funcionalidad se encuentra en los contenedores oficiales).
Un ejemplo es un servidor web que envía métricas a Kinesis Data Streams. El servidor puede continuar sirviendo páginas incluso si la parte de Kinesis Data Streams dejó de funcionar. El bloqueo de todo el servidor como consecuencia de un error en KPL provocaría una interrupción innecesaria del servicio.
**2) Compatibilidad con clientes arbitrarios**
Siempre hay consumidores que usan lenguajes diferentes a los que son oficialmente compatibles. Estos usuarios también deberían poder utilizar KPL fácilmente.
## Matriz de uso recomendada
La siguiente matriz de uso enumera la configuración recomendada para diferentes usuarios y le recomienda si utilizar KPL y cómo hacerlo. Tenga en cuenta que si se habilita la agregación, también debe utilizar desagrupación para extraer sus registros en el lado del consumidor.
| Lenguaje del lado del productor | Lenguaje del lado del consumidor | Versión de KCL | Lógica del punto de comprobación | ¿Puede utilizar KPL? | Advertencias |
| --- | --- | --- | --- | --- | --- |
| Cualquiera excepto Java | \$1 | \$1 | \$1 | No | N/A |
| Java | Java | Utiliza el SDK de Java directamente | N/A | Sí | Si se utiliza agregación, deberá usar la biblioteca de desagrupación facilitada tras la llamada de GetRecords. |
| Java | Cualquiera excepto Java | Utiliza SDK directamente | N/A | Sí | Debe deshabilitar la agregación. |
| Java | Java | 1.3.x | N/A | Sí | Debe deshabilitar la agregación. |
| Java | Java | 1.4.x | Llama al punto de comprobación sin argumentos | Sí | Ninguno |
| Java | Java | 1.4.x | Llama al punto de comprobación con un número secuencial explícito | Sí | Desactive la agregación o cambie el código para usar números secuenciales ampliados para la creación de puntos de control. |
| Java | Cualquiera excepto Java | 1.3.x \$1 daemon multilenguaje \$1 contenedor específico del lenguaje | N/A | Sí | Debe deshabilitar la agregación. |
# Escribir en Kinesis Data Stream mediante KPL
En las secciones siguientes, se muestra un código de ejemplo con una progresión que va desde el productor más básico hasta un código completamente asíncrono.
## Código de productor básico
El siguiente código es todo lo que necesita para escribir un productor mínimamente funcional. Los registros de usuario de Amazon Kinesis Producer Library (KPL) se procesan en segundo plano.
```
// KinesisProducer gets credentials automatically like
// DefaultAWSCredentialsProviderChain.
// It also gets region automatically from the EC2 metadata service.
KinesisProducer kinesis = new KinesisProducer();
// Put some records
for (int i = 0; i < 100; ++i) {
ByteBuffer data = ByteBuffer.wrap("myData".getBytes("UTF-8"));
// doesn't block
kinesis.addUserRecord("myStream", "myPartitionKey", data);
}
// Do other stuff ...
```
## Responder a los resultados de manera síncrona
En el ejemplo anterior, el código no comprobó si el procesamiento de registros de usuario de KPL finalizó correctamente. KPL efectúa los reintentos necesarios en caso de error. Sin embargo, si desea comprobar los resultados, puede examinarlos con los objetos `Future` que devuelve `addUserRecord`, como en el siguiente ejemplo (el ejemplo anterior se incluye para aportar contexto):
```
KinesisProducer kinesis = new KinesisProducer();
// Put some records and save the Futures
List> putFutures = new LinkedList>();
for (int i = 0; i < 100; i++) {
ByteBuffer data = ByteBuffer.wrap("myData".getBytes("UTF-8"));
// doesn't block
putFutures.add(
kinesis.addUserRecord("myStream", "myPartitionKey", data));
}
// Wait for puts to finish and check the results
for (Future f : putFutures) {
UserRecordResult result = f.get(); // this does block
if (result.isSuccessful()) {
System.out.println("Put record into shard " +
result.getShardId());
} else {
for (Attempt attempt : result.getAttempts()) {
// Analyze and respond to the failure
}
}
}
```
## Responder a los resultados de manera asíncrona
El ejemplo anterior llama a `get()` en un objeto `Future` que bloquea el tiempo de ejecución. Si no desea bloquear el tiempo de ejecución, puede utilizar una devolución de llamada asíncrona, tal y como se muestra en el ejemplo siguiente:
```
KinesisProducer kinesis = new KinesisProducer();
FutureCallback myCallback = new FutureCallback() {
@Override public void onFailure(Throwable t) {
/* Analyze and respond to the failure */
};
@Override public void onSuccess(UserRecordResult result) {
/* Respond to the success */
};
};
for (int i = 0; i < 100; ++i) {
ByteBuffer data = ByteBuffer.wrap("myData".getBytes("UTF-8"));
ListenableFuture f = kinesis.addUserRecord("myStream", "myPartitionKey", data);
// If the Future is complete by the time we call addCallback, the callback will be invoked immediately.
Futures.addCallback(f, myCallback);
}
```
# Configurar Amazon Kinesis Producer Library
Aunque la configuración predeterminada debería funcionar sin problemas para la mayoría de los casos de uso, es posible que desee cambiar algunos de los ajustes predeterminados para adaptar el comportamiento de `KinesisProducer` a sus necesidades. Para hacerlo, se puede pasar una instancia de la clase `KinesisProducerConfiguration` al constructor `KinesisProducer`, por ejemplo:
```
KinesisProducerConfiguration config = new KinesisProducerConfiguration()
.setRecordMaxBufferedTime(3000)
.setMaxConnections(1)
.setRequestTimeout(60000)
.setRegion("us-west-1");
final KinesisProducer kinesisProducer = new KinesisProducer(config);
```
También puede cargar una configuración desde un archivo de propiedades:
```
KinesisProducerConfiguration config = KinesisProducerConfiguration.fromPropertiesFile("default_config.properties");
```
Puede sustituir la ruta y el nombre de archivo a los que tiene acceso el proceso del usuario. También puede llamar a métodos fijos en la instancia `KinesisProducerConfiguration` que hayan sido creados así para personalizar la configuración.
El archivo de propiedades debe especificar los parámetros con sus nombres en PascalCase. Los nombres han de coincidir con los utilizados en los métodos fijos de la clase `KinesisProducerConfiguration`. Por ejemplo:
```
RecordMaxBufferedTime = 100
MaxConnections = 4
RequestTimeout = 6000
Region = us-west-1
```
Para obtener más información sobre las reglas de uso de los parámetros de configuración y los límites de valores, consulte el [ejemplo del archivo de propiedades de configuración en GitHub](https://github.com/awslabs/amazon-kinesis-producer/blob/master/java/amazon-kinesis-producer-sample/default_config.properties).
Tenga en cuenta que después de inicializar `KinesisProducer`, los cambios en la instancia `KinesisProducerConfiguration` no tienen efecto alguno. Actualmente, `KinesisProducer` no admite la reconfiguración dinámica.
# Implementar la desagregación de consumidores
A partir de la versión 1.4.0, KCL es compatible con la desagrupación automática de registros de usuario de KPL. El código de la aplicación de consumidor escrito con versiones anteriores de KCL se compilará sin ningún tipo de modificación después de actualizar KCL. Sin embargo, si la agregación de KPL se utiliza en el lado del productor, existe un matiz relacionado con la creación de puntos de control: todos los subregistros de un registro agregado tienen el mismo número de secuencia, de modo que los datos adicionales deben almacenarse con el punto de control si es necesario hacer una distinción entre subregistros. Estos datos adicionales se denominan *números subsecuenciales*.
**Topics**
+ [Migrar de versiomrd anteriores de KCL](#kinesis-kpl-consumer-deaggregation-migration)
+ [Usar extensiones de KCL para la desagrupación de KPL](#kinesis-kpl-consumer-deaggregation-extensions)
+ [Úselo GetRecords directamente](#kinesis-kpl-consumer-deaggregation-getrecords)
## Migrar de versiomrd anteriores de KCL
No es necesario cambiar las llamadas existentes para crear puntos de control con la agregación. La recuperación de todos los registros almacenados correctamente en Kinesis Data Streams seguirá estando garantizada. Ahora, KCL ofrece dos nuevas operaciones de puntos de control para casos de uso particulares que se describen a continuación.
Si el código existente se hubiera escrito para KCL antes de que fuera compatible con KPL y se llama a la operación del punto de control sin argumentos, esto equivaldría a la creación de puntos de control para el número de secuencia del último registro de usuario de KPL en el lote. Si la operación de punto de comprobación se llama con una cadena de número secuencial, equivaldrá a la creación de un punto de comprobación para el número secuencial determinado del lote junto con el número subsecuencial implícito 0 (cero).
La llamada a la nueva operación de punto de control de KCL `checkpoint()` sin argumentos equivale semánticamente a hacer un punto de control del número de secuencia de la última llamada de `Record` en el lote, junto con el número subsecuencial implícito 0 (cero).
La llamada a la nueva operación de punto de control de KCL `checkpoint(Record record)` equivale semánticamente a hacer un punto de control del número secuencial del `Record` dado, junto con el número subsecuencial implícito 0 (cero). Si la llamada al `Record` es realmente un `UserRecord`, el número secuencial de `UserRecord` y el número subsecuencial se someten a un punto de comprobación.
La llamada a la nueva operación de punto de control de KCL `checkpoint(String sequenceNumber, long subSequenceNumber)` crea explícitamente un punto de control del número secuencial dado junto con el número subsecuencial dado.
En cualquiera de estos casos, después de que el punto de control se almacene en la tabla de Amazon DynamoDB, KCL puede reanudar correctamente la recuperación de los registros, incluso cuando la aplicación se bloquee y se reinicie. Si la secuencia contiene más registros, la recuperación se produce a partir del registro con el siguiente número subsecuencial dentro del registro con el número secuencial que se haya comprobado más recientemente. Si el punto de comprobación más reciente incluyó el último número subsecuencial del registro con el número secuencial anterior, la recuperación se produce a partir del registro con el siguiente número secuencial.
En la siguiente sección se explican los detalles de la comprobación secuencial y subsecuencial para los consumidores que deban evitar la omisión y la duplicación de registros. Si la omisión (o duplicación) de registros al detener y reiniciar el procesamiento de registros del consumidor no resulta importante, puede ejecutar su código existente sin modificaciones.
## Usar extensiones de KCL para la desagrupación de KPL
La desagrupación de KPL puede implicar la creación de puntos de control subsecuenciales. Para facilitar el uso de la creación de puntos de control subsecuenciales, se ha agregado una clase `UserRecord` a KCL:
```
public class UserRecord extends Record {
public long getSubSequenceNumber() {
/* ... */
}
@Override
public int hashCode() {
/* contract-satisfying implementation */
}
@Override
public boolean equals(Object obj) {
/* contract-satisfying implementation */
}
}
```
Esta categoría es la que se usa ahora en lugar de `Record`. Esto no afecta al código existente, porque es una subclase de `Record`. La clase `UserRecord` representa tanto subregistros reales como registros estándares no agregados. Se pueden describir los registros no agregados como registros agregados con solo un subregistro.
Además, se han añadido dos nuevas operaciones a `IRecordProcessorCheckpointer`:
```
public void checkpoint(Record record);
public void checkpoint(String sequenceNumber, long subSequenceNumber);
```
Para empezar a utilizar la creación de puntos de comprobación de números subsecuenciales, puede realizar la siguiente conversión. Cambie el siguiente código de formulario:
```
checkpointer.checkpoint(record.getSequenceNumber());
```
Nuevo código de formulario:
```
checkpointer.checkpoint(record);
```
Le recomendamos que use el formulario `checkpoint(Record record)` para la generación de puntos de comprobación subsecuenciales. Sin embargo, si ya está almacenando `sequenceNumbers` en cadenas para la creación de puntos de comprobación, ahora también deberá almacenar `subSequenceNumber`, tal y como se muestra en el ejemplo siguiente:
```
String sequenceNumber = record.getSequenceNumber();
long subSequenceNumber = ((UserRecord) record).getSubSequenceNumber(); // ... do other processing
checkpointer.checkpoint(sequenceNumber, subSequenceNumber);
```
La difusión de `Record` a `UserRecord` siempre se realiza correctamente, ya que en la implementación siempre se usa `UserRecord`. A no ser que sea necesario realizar cálculos aritméticos en los números secuenciales, no recomendamos este enfoque.
Al procesar los registros de usuario de KPL, KCL escribe el número subsecuencial en Amazon DynamoDB como un campo adicional para cada fila. Las versiones anteriores de KCL utilizaban `AFTER_SEQUENCE_NUMBER` para obtener los registros al reanudar los puntos de control. KCL actual con compatibilidad con KPL utiliza `AT_SEQUENCE_NUMBER` en su lugar. Cuando se recupera el registro del número secuencial del punto de comprobación, se comprueba el número secuencial sometido al punto de comprobación, y los subregistros se descartan según proceda (podrían ser todos ellos, si el último subregistro es el del punto de comprobación). De nuevo, se pueden entender los registros no agregados como registros agregados con un único subregistro, de modo que el mismo algoritmo funciona tanto para los registros agregados como para los no agregados.
## Úselo GetRecords directamente
También puede optar por no utilizar KCL e invocar en su lugar la operación de la API `GetRecords` directamente para recuperar registros de Kinesis Data Streams. Para desempaquetar estos registros recuperados en el registro de usuario original de KPL, llame a una de las siguientes operaciones estáticas en `UserRecord.java`:
```
public static List deaggregate(List records)
public static List deaggregate(List records, BigInteger startingHashKey, BigInteger endingHashKey)
```
La primera operación utiliza el valor predeterminado `0` (cero) para `startingHashKey` y el valor predeterminado `2^128 -1` para `endingHashKey`.
Cada una de estas operaciones desagrupa la lista de registros de Kinesis Data Streams especificada y genera una lista de registros de usuario de KPL. Cualquier registro de usuario de KPL cuya clave hash explícita o clave de partición quede fuera del rango entre `startingHashKey` (incluida) y `endingHashKey` (incluida) se descarta de la lista de registros devuelta.
# Usar KPL con Amazon Data Firehose
Si utiliza Kinesis Producer Library (KPL) para escribir datos en un flujo de datos de Kinesis, puede utilizar la agregación para combinar los registros que escriba en ese flujo de datos de Kinesis. Si después utiliza ese flujo de datos como origen del flujo de entrega de Firehose, este desagrupa los registros antes de entregarlos en el destino. Si configura el flujo de entrega de modo que transforme los datos, Firehose desagrega los registros antes de entregarlos en AWS Lambda. Para obtener más información, consulte [Escritura en Amazon Firehose mediante Kinesis Data Streams](https://docs.aws.amazon.com/firehose/latest/dev/writing-with-kinesis-streams.html).
# Utilice el KPL con el registro de AWS Glue esquemas
Puede integrar sus flujos de datos de Kinesis con el registro de AWS Glue esquemas. AWS Glue Schema Registry le permite descubrir, controlar y evolucionar de forma centralizada esquemas, además de garantizar que un esquema registrado valide de forma continua los datos generados. Un esquema define la estructura y el formato de un registro de datos. Un esquema es una especificación versionada para publicación, consumo o almacenamiento de confianza de datos. El registro de AWS Glue esquemas le permite mejorar la end-to-end calidad y el gobierno de los datos en sus aplicaciones de streaming. Para obtener más información, consulte [AWS Glue Schema Registry](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html). Una de las maneras de configurar esta integración es a través de las bibliotecas KPL y Kinesis Client Library (KCL) en Java.
**importante**
Actualmente, la integración de Kinesis Data Streams AWS Glue y el registro de esquemas solo se admite para las transmisiones de datos de Kinesis que utilizan productores de KPL implementados en Java. No se proporciona soporte multilingüe.
Para obtener instrucciones detalladas sobre cómo configurar la integración de Kinesis Data Streams con Schema Registry mediante la KPL, consulte la sección «Interacción con los datos mediante KPL/KCL las bibliotecas» [en Caso de uso: integración de Amazon Kinesis Data Streams con AWS el](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-integrations.html#schema-registry-integrations-kds) registro de esquemas de Glue.
# Configurar la configuración del proxy de KPL
En el caso de las aplicaciones que no pueden conectarse directamente a Internet, todos los clientes AWS del SDK admiten el uso de proxies HTTP o HTTPS. En un entorno empresarial típico, todo el tráfico de red saliente tiene que pasar por servidores proxy. Si su aplicación utiliza la biblioteca de productores de Kinesis (KPL) para recopilar y enviar datos AWS en un entorno que utiliza servidores proxy, necesitará una configuración de proxy KPL. KPL es una biblioteca de alto nivel creada sobre el SDK de AWS Kinesis. Se divide en un proceso nativo y un contenedor. El proceso nativo realiza todos los trabajos de procesamiento y envío de registros, mientras que el contenedor administra el proceso nativo y se comunica con este. Para obtener más información, consulte [Implementing Efficient and Reliable Producers with the Amazon Kinesis Producer Library](https://aws.amazon.com/blogs/big-data/implementing-efficient-and-reliable-producers-with-the-amazon-kinesis-producer-library/).
El contenedor está escrito en Java y el proceso nativo está escrito en C\$1\$1 con el uso del SDK de Kinesis. La versión 0.14.7 y posterior de KPL ahora admite la configuración del proxy en el contenedor de Java, que puede transferir todas las configuraciones del proxy al proceso nativo. Para obtener más información, consulte [https://github.com/awslabs/amazon-kinesis-producer/releases/tag/v](https://github.com/awslabs/amazon-kinesis-producer/releases/tag/v0.14.7)0.14.7.
Puede utilizar el código siguiente para agregar las configuraciones del proxy a las aplicaciones de KPL.
```
KinesisProducerConfiguration configuration = new KinesisProducerConfiguration();
// Next 4 lines used to configure proxy
configuration.setProxyHost("10.0.0.0"); // required
configuration.setProxyPort(3128); // default port is set to 443
configuration.setProxyUserName("username"); // no default
configuration.setProxyPassword("password"); // no default
KinesisProducer kinesisProducer = new KinesisProducer(configuration);
```
# Política de ciclo de vida de la versión de KPL
En este tema se describe la política de ciclo de vida de las versiones de Amazon Kinesis Producer Library (KPL). AWS publica periódicamente nuevas versiones de las versiones de KPL para incorporar nuevas funciones y mejoras, correcciones de errores, parches de seguridad y actualizaciones de dependencias. Le recomendamos que utilice las versiones KPL para mantenerse al día con las últimas funciones, actualizaciones de seguridad y dependencias subyacentes. up-to-date **No** recomendamos seguir utilizando una versión de KPL no compatible.
El ciclo de vida de las principales versiones de KPL consta de las siguientes tres fases:
+ **Disponibilidad general (GA)**: durante esta fase, la versión principal es totalmente compatible. AWS proporciona versiones periódicas de versiones secundarias y de parches que incluyen compatibilidad con nuevas funciones o actualizaciones de API para Kinesis Data Streams, así como correcciones de errores y de seguridad.
+ **Modo de mantenimiento**: AWS limita las publicaciones de las versiones de parches para abordar únicamente las correcciones de errores críticos y los problemas de seguridad. La versión principal no recibirá actualizaciones de las nuevas funciones ni APIs de Kinesis Data Streams.
+ **E nd-of-support**: La versión principal ya no recibirá actualizaciones ni versiones. Las versiones publicadas anteriormente seguirán estando disponibles a través de los administradores de paquetes públicos y el código permanecerá activado GitHub. El uso de una versión disponible end-of-support queda a discreción del usuario. Recomendamos que actualice a la versión principal más reciente.
| Versión principal | Fase actual | Fecha de publicación | Fecha del modo de mantenimiento | End-of-support fecha |
| --- | --- | --- | --- | --- |
| KPL 0.x | Modo de mantenimiento | 2015-06-02 | 2025-04-17 | 2026-01-30 |
| KPL 1.x | Disponibilidad general | 2024-12-15 | -- | -- |