Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Développez des producteurs à l'aide de la bibliothèque Amazon Kinesis Producer Library (KPL)
Un producteur Amazon Kinesis Data Streams est une application qui place des enregistrements de données utilisateur dans un flux de données Kinesis (également appelé *ingestion de données*). L'Amazon Kinesis Producer Library (KPL) simplifie le développement des applications destinées aux producteurs, en permettant aux développeurs d'atteindre un débit d'écriture élevé dans un flux de données Kinesis.
Vous pouvez surveiller le KPL avec Amazon CloudWatch. Pour de plus amples informations, veuillez consulter [Surveillez la bibliothèque Kinesis Producer avec Amazon CloudWatch](monitoring-with-kpl.md).
**Topics**
+ [Revoir le rôle du KPL](#developing-producers-with-kpl-role)
+ [Découvrez les avantages de l'utilisation du KPL](#developing-producers-with-kpl-advantage)
+ [Sachez quand ne pas utiliser le KPL](#developing-producers-with-kpl-when)
+ [Installez le KPL](kinesis-kpl-dl-install.md)
+ [Migrer de KPL 0.x vers KPL 1.x](kpl-migration-1x.md)
+ [Transition vers les certificats Amazon Trust Services (ATS) pour le KPL](kinesis-kpl-upgrades.md)
+ [Plateformes prises en charge par KPL](kinesis-kpl-supported-plats.md)
+ [Concepts clés du KPL](kinesis-kpl-concepts.md)
+ [Intégrer le KPL au code du producteur](kinesis-kpl-integration.md)
+ [Écrivez dans votre flux de données Kinesis à l'aide du KPL](kinesis-kpl-writing.md)
+ [Configuration de la bibliothèque Amazon Kinesis Producer](kinesis-kpl-config.md)
+ [Mettre en œuvre la désagrégation des consommateurs](kinesis-kpl-consumer-deaggregation.md)
+ [Utiliser le KPL avec Amazon Data Firehose](kpl-with-firehose.md)
+ [Utiliser le KPL avec le registre des AWS Glue schémas](kpl-with-schemaregistry.md)
+ [Configurer la configuration du proxy KPL](kpl-proxy-configuration.md)
+ [Politique de cycle de vie des versions KPL](kpl-version-lifecycle-policy.md)
**Note**
Il est recommandé de passer à la dernière version de KPL. La KPL est régulièrement mise à jour avec de nouvelles versions qui incluent les derniers correctifs de dépendance et de sécurité, des corrections de bogues et de nouvelles fonctionnalités rétrocompatibles. Pour plus d'informations, consultez [https://github.com/awslabs/amazon-kinesis-producer/releases/](https://github.com/awslabs/amazon-kinesis-producer/releases/).
## Revoir le rôle du KPL
Le KPL est une easy-to-use bibliothèque hautement configurable qui vous permet d'écrire dans un flux de données Kinesis. Elle sert d'intermédiaire entre le code de votre application producteur et les actions d'API Kinesis Data Streams. La KPL effectue les tâches principales suivantes :
+ Ecrit dans un ou plusieurs flux de données Kinesis avec un mécanisme de nouvelle tentative configurable
+ Collecte les enregistrements et utilise `PutRecords` pour écrire plusieurs enregistrements dans plusieurs partitions par demande
+ Regroupe les enregistrements d'utilisateur pour accroître la taille de la charge utile et améliorer le débit
+ S'intègre de façon transparente avec la [bibliothèque client Kinesis](https://docs.aws.amazon.com/kinesis/latest/dev/developing-consumers-with-kcl.html) (KCL) pour dégrouper les enregistrements en lot sur l'application producteur
+ Soumet CloudWatch les statistiques Amazon en votre nom afin de fournir une visibilité sur les performances des producteurs
Notez que le KPL est différent de l'API Kinesis Data Streams disponible dans le. [AWS SDKs](https://aws.amazon.com/tools/) L'API Kinesis Data Streams vous permet de gérer de nombreux aspects de Kinesis Data Streams (notamment la création de flux, le repartitionnement, le placement et l'extraction des enregistrements), tandis que la KPL fournit une couche d'abstraction spécifiquement pour l'ingestion de données. Pour plus d'informations sur l'API Kinesis Data Streams, consultez la [Référence d'API Amazon Kinesis](https://docs.aws.amazon.com/kinesis/latest/APIReference/) (français non garanti).
## Découvrez les avantages de l'utilisation du KPL
La liste suivante présente certains des principaux avantages liés à l'utilisation de la KPL pour le développement des applications producteur Kinesis Data Streams.
La KPL peut servir aussi bien dans les deux cas d'utilisation synchrones qu'asynchrones. Nous recommandons d'utiliser les meilleures performances de l'interface asynchrone, à moins d'avoir une raison précise d'utiliser le comportement synchrone. Pour plus d'informations sur ces deux cas d'utilisation et l'exemple de code, consultez la page [Écrivez dans votre flux de données Kinesis à l'aide du KPL](kinesis-kpl-writing.md).
**Avantages en termes de performances**
La KPL peut aider à créer des applications producteur hautes performances. Imaginez une situation où vos instances Amazon EC2 servent de proxy pour la collecte des événements de 100 octets sur des centaines ou milliers d'appareils de faible puissance et pour l'écriture des enregistrements dans un flux de données Kinesis. Ces instances EC2 doivent écrire chacune des milliers d'événements par seconde dans votre flux de données. Pour atteindre le débit nécessaire, les applications producteur doivent mettre en œuvre une logique complexe, telle que le traitement par lots ou multithreading, en plus d'une logique de nouvelle tentative et du dégroupement des enregistrements du côté consommateur. La KPL effectue toutes ces tâches à votre place.
**Facilité d'utilisation côté consommateur**
Pour les développeurs côté consommateur qui utilisent la KCL en Java, la KPL s'intègre sans effort supplémentaire. Lorsque la KCL extrait un enregistrement Kinesis Data Streams groupé, composé de plusieurs enregistrements d'utilisateur KPL, elle appelle automatiquement la KPL pour extraire les différents enregistrements d'utilisateur avant de les renvoyer à l'utilisateur.
Pour les développeurs côté consommateur qui n'utilisent pas la KCL, mais directement l'opération d'API `GetRecords`, une bibliothèque KPL Java est disponible pour extraire les différents enregistrements d'utilisateur avant de les renvoyer à l'utilisateur.
**Surveillance d'une application producteur**
Vous pouvez collecter, surveiller et analyser vos producteurs de Kinesis Data Streams à l'aide d' CloudWatch Amazon et du KPL. Le KPL émet des indicateurs de débit, d'erreur et d'autres indicateurs en votre CloudWatch nom, et est configurable pour être surveillé au niveau du flux, de la partition ou du producteur.
**Architecture asynchrone**
Comme le KPL peut mettre en mémoire tampon les enregistrements avant de les envoyer à Kinesis Data Streams, il n'oblige pas l'application appelant à bloquer et à attendre la confirmation que l'enregistrement est arrivé sur le serveur avant de poursuivre l'exécution. Un appel pour placer un enregistrement dans la KPL renvoie toujours immédiatement une réponse et n'attend pas l'envoi de l'enregistrement ou une réponse reçue du serveur. En revanche, un objet `Future` est créé, qui reçoit le résultat de l'envoi ultérieur de l'enregistrement à Kinesis Data Streams. Ce comportement est identique à celui des clients asynchrones dans le AWS SDK.
## Sachez quand ne pas utiliser le KPL
La KPL peut subir un délai de traitement supplémentaire allant jusqu'à `RecordMaxBufferedTime` dans la bibliothèque (configurable par l'utilisateur). Les valeurs élevées de `RecordMaxBufferedTime` se traduisent par une efficacité de compression supérieure et de meilleures performances. Les applications qui ne tolèrent pas ce délai supplémentaire peuvent avoir besoin d'utiliser directement le AWS SDK. Pour plus d'informations sur l'utilisation du AWS SDK avec Kinesis Data Streams, consultez. [Développez des producteurs à l'aide de l'API Amazon Kinesis Data Streams avec le AWS SDK pour Java](developing-producers-with-sdk.md) Pour plus d'informations sur `RecordMaxBufferedTime` et les autres propriétés configurables par l'utilisateur de la KPL, consultez [Configuration de la bibliothèque Amazon Kinesis Producer](kinesis-kpl-config.md).
# Installez le KPL
Amazon fournit des fichiers binaires prédéfinis de la bibliothèque Amazon Kinesis Producer (KPL) en C\$1\$1 pour macOS, Windows et les distributions Linux récentes (pour plus d'informations sur les plateformes prises en charge, consultez la section suivante). Ces fichiers binaires sont packagés sous forme de fichiers .jar Java et sont appelés automatiquement et utilisés si vous utilisez Maven pour installer le package. Pour rechercher les dernières versions de la KPL et de la KCL, utilisez les liens de recherche Maven suivants :
+ [KPL](https://search.maven.org/#search|ga|1|amazon-kinesis-producer)
+ [KCL](https://search.maven.org/#search|ga|1|amazon-kinesis-client)
Les fichiers binaires Linux ont été compilés avec GCC (GNU Compiler Collection) et liés statiquement avec libstdc\$1\$1 sous Linux. Ils sont censés fonctionner sur toutes les distributions Linux 64 bits qui incluent une glibc version 2.5 ou ultérieure.
Les utilisateurs des anciennes distributions Linux peuvent créer le KPL en utilisant les instructions de compilation fournies avec le code source activé GitHub. Pour télécharger le KPL depuis GitHub, consultez la bibliothèque [Amazon Kinesis](https://github.com/awslabs/amazon-kinesis-producer) Producer.
**Important**
La version 0.x d'Amazon Kinesis Producer Library (KPL) sera disponible le 30 end-of-support janvier 2026. Nous vous **recommandons vivement** de migrer vos applications KPL à l'aide de la version 0.x vers la dernière version de KPL avant le 30 janvier 2026. Pour trouver la dernière version de KPL, consultez la [page KPL sur](https://github.com/awslabs/amazon-kinesis-producer) Github. Pour plus d'informations sur la migration de KPL 0.x vers KPL 1.x, consultez. [Migrer de KPL 0.x vers KPL 1.x](kpl-migration-1x.md)
# Migrer de KPL 0.x vers KPL 1.x
Cette rubrique fournit des step-by-step instructions pour faire migrer votre client de KPL 0.x vers KPL 1.x. KPL 1.x introduit le support de la version AWS SDK pour Java 2.x tout en maintenant la compatibilité de l'interface avec les versions précédentes. Il n'est pas nécessaire de mettre à jour votre logique de traitement des données de base pour migrer vers KPL 1.x.
1. **Assurez-vous de remplir les conditions préalables suivantes :**
+ Kit de développement Java (JDK) 8 ou version ultérieure
+ AWS SDK pour Java 2. x
+ Maven ou Gradle pour la gestion des dépendances
1. **Ajouter des dépendances**
Si vous utilisez Maven, ajoutez la dépendance suivante à votre fichier pom.xml. Assurez-vous d'avoir mis à jour le GroupId de `com.amazonaws` vers `software.amazon.kinesis` et la version `1.x.x` vers la dernière version de KPL.
```
software.amazon.kinesis
amazon-kinesis-producer
1.x.x
```
Si vous utilisez Gradle, ajoutez ce qui suit à votre `build.gradle` fichier. Assurez-vous de le remplacer `1.x.x` par la dernière version de KPL.
```
implementation 'software.amazon.kinesis:amazon-kinesis-producer:1.x.x'
```
Vous pouvez vérifier la dernière version du KPL sur le référentiel [central Maven](https://central.sonatype.com/search?q=amazon-kinesis-producer).
1. **Mettre à jour les déclarations d'importation pour KPL**
Le KPL 1.x utilise le AWS SDK pour Java 2.x et utilise un nom de package mis à jour qui commence par`software.amazon.kinesis`, par rapport au nom du package dans le KPL précédent qui commence par. `com.amazonaws.services.kinesis`
Remplacez l'import pour `com.amazonaws.services.kinesis` par`software.amazon.kinesis`. Le tableau suivant répertorie les importations que vous devez remplacer.
**Importer des pièces de rechange**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/streams/latest/dev/kpl-migration-1x.html)
1. **Mettre à jour les instructions d'importation pour les classes de fournisseurs AWS d'identifiants**
Lors de la migration vers KPL 1.x, vous devez mettre à jour les packages et les classes de vos importations dans le code de votre application KPL basés sur la version AWS SDK pour Java 1.x vers les packages correspondants basés sur la version 2.x. AWS SDK pour Java Les importations courantes dans l'application KPL sont les classes de fournisseurs d'informations d'identification. Consultez la section [Modifications du fournisseur d'informations d'identification](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-client-credentials.html) dans la documentation du guide de migration AWS SDK pour Java 2.x pour obtenir la liste complète des modifications apportées au fournisseur d'informations d'identification. Voici la modification d'importation courante que vous devrez peut-être apporter à vos applications KPL.
**Importer dans KPL 0.x**
```
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
```
**Importer dans KPL 1.x**
```
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
```
Si vous importez d'autres fournisseurs d'informations d'identification basés sur la AWS SDK pour Java version 1.x, vous devez les mettre à jour vers les fournisseurs équivalents AWS SDK pour Java 2.x. Si vous n'en avez importé aucune classes/packages depuis la version AWS SDK pour Java 1.x, vous pouvez ignorer cette étape.
1. **Mettre à jour la configuration du fournisseur d'informations d'identification dans la configuration KPL**
La configuration du fournisseur d'informations d'identification dans KPL 1.x nécessite les fournisseurs d'informations d'identification AWS SDK pour Java 2.x. Si vous transmettez des fournisseurs d'informations d'identification pour la AWS SDK pour Java version 1.x en remplaçant le fournisseur d'informations d'identification `KinesisProducerConfiguration` par défaut, vous devez le mettre à jour avec les fournisseurs d'informations d'identification AWS SDK pour Java 2.x. Consultez la section [Modifications du fournisseur d'informations d'identification](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-client-credentials.html) dans la documentation du guide de migration AWS SDK pour Java 2.x pour obtenir la liste complète des modifications apportées au fournisseur d'informations d'identification. Si vous n'avez pas remplacé le fournisseur d'informations d'identification par défaut dans la configuration KPL, vous pouvez ignorer cette étape.
Par exemple, si vous remplacez le fournisseur d'informations d'identification par défaut pour le KPL par le code suivant :
```
KinesisProducerConfiguration config = new KinesisProducerConfiguration();
// SDK v1 default credentials provider
config.setCredentialsProvider(new DefaultAWSCredentialsProviderChain());
```
Vous devez les mettre à jour avec le code suivant pour utiliser le fournisseur d'informations d'identification AWS SDK pour Java 2.x :
```
KinesisProducerConfiguration config = new KinesisProducerConfiguration();
// New SDK v2 default credentials provider
config.setCredentialsProvider(DefaultCredentialsProvider.create());
```
# Transition vers les certificats Amazon Trust Services (ATS) pour le KPL
Le 9 février 2018, à 9 h PST, Amazon Kinesis Data Streams a installé les certificats ATS. Pour continuer à écrire des enregistrements dans Kinesis Data Streams à l'aide de la bibliothèque Amazon Kinesis Producer (KPL), vous devez mettre à niveau votre installation de la KPL vers la version 0.12.6 [ou](http://search.maven.org/#artifactdetails|com.amazonaws|amazon-kinesis-producer|0.12.6|jar) ultérieure. Ce changement concerne toutes les AWS régions.
Pour plus d'informations sur le passage à ATS, voir [Comment préparer AWS le passage à sa propre autorité de certification](https://aws.amazon.com/blogs/security/how-to-prepare-for-aws-move-to-its-own-certificate-authority/).
Si vous rencontrez des problèmes et que vous avez besoin d'une assistance technique, [créez une demande](https://console.aws.amazon.com/support/v1#/case/create) auprès du centre de support AWS .
# Plateformes prises en charge par KPL
La bibliothèque Amazon Kinesis Producer (KPL) est écrite en C\$1\$1 et s'exécute en tant que processus secondaire du processus utilisateur principal. Des fichiers binaires natifs 64 bits précompilés sont regroupés avec la version Java et sont gérés par le wrapper Java.
Le package Java s'exécute sans avoir besoin d'installer les bibliothèques supplémentaires sur les systèmes d'exploitation suivants :
+ Distributions Linux avec le noyau 2.6.18 (septembre 2006) et ultérieur
+ Apple iOS X 10.9 et versions ultérieures
+ Windows Server 2008 et version ultérieure
**Important**
Windows Server 2008 ou version ultérieure est pris en charge pour toutes les versions de KPL jusqu'à la version 0.14.0.
La plateforme Windows n'est pas prise en charge à partir de la version 0.14.0 de KPL.
Notez que la bibliothèque KPL est en 64 bits uniquement.
## Code source
Si les fichiers binaires fournis dans l'installation KPL ne sont pas suffisants pour votre environnement, la base de la KPL est écrite sous forme d'un module C\$1\$1. Le code source du module C\$1\$1 et de l'interface Java est publié sous licence publique Amazon et est disponible sur la bibliothèque GitHub [Amazon Kinesis Producer](https://github.com/awslabs/amazon-kinesis-producer). Bien que la bibliothèque KPL puisse être utilisée sur n'importe quelle plateforme équipée d'un compilateur C\$1\$1 récent en conformité et d'un JRE, Amazon ne prend pas officiellement en charge celles qui ne figurent pas sur la liste des plateformes prises en charge.
# Concepts clés du KPL
Les sections suivantes contiennent les concepts et la terminologie nécessaires pour comprendre et tirer parti de l'Amazon Kinesis Producer Library (KPL).
**Topics**
+ [Enregistrements](#kinesis-kpl-concepts-records)
+ [Traitement par lot](#kinesis-kpl-concepts-batching)
+ [Agrégation](#kinesis-kpl-concepts-aggretation)
+ [Collection](#kinesis-kpl-concepts-collection)
## Enregistrements
Dans ce guide, nous différencions les *enregistrements utilisateur KPL* et les *enregistrements Kinesis Data Streams*. Lorsque nous utilisons le terme *enregistrement* sans identificateur, nous faisons référence à un *enregistrement utilisateur KPL*. Lorsque nous faisons référence à un enregistrement Kinesis Data Streams, il est explicitement question d'enregistrement *Kinesis Data Streams*.
Un enregistrement utilisateur KPL est un blob de données qui a une signification particulière pour l'utilisateur. Les exemples incluent un blob JSON représentant un événement de l'interface utilisateur sur un site Web, ou une entrée de journal issue d'un serveur Web.
Un enregistrement Kinesis Data Streams est une instance de la structure de données `Record` définie par l'API du service Kinesis Data Streams. Il contient une clé de partition, un numéro de séquence et un blob de données.
## Traitement par lot
Le *traitement par lot* consiste à exécuter une action sur plusieurs éléments au lieu d'exécuter cette action à plusieurs reprises sur chaque élément individuel.
Dans ce contexte, l'« élément » est un enregistrement et l'action est l'envoi de cet enregistrement à Kinesis Data Streams. Dans une situation sans traitement par lot, vous placez chaque enregistrement dans un enregistrement Kinesis Data Streams distinct et effectuez une seule demande HTTP pour envoyer l'enregistrement à Kinesis Data Streams. Avec le traitement par lot, chaque demande HTTP peut exécuter plusieurs enregistrements au lieu d'un seul.
La KPL prend en charge deux types de traitement par lot :
+ *Regroupement* : stockage de plusieurs enregistrements dans un seul enregistrement Kinesis Data Streams.
+ *Collecte* : utilisation de l'opération d'API `PutRecords` pour envoyer plusieurs enregistrements Kinesis Data Streams dans une ou plusieurs partitions de votre flux de données Kinesis.
Les deux types de traitement par lot KPL sont conçus pour co-exister et peuvent être activés ou désactivés indépendamment l'un de l'autre. Par défaut, les deux types sont activés.
## Agrégation
Le *regroupement* consiste à stocker plusieurs enregistrements dans un enregistrement Kinesis Data Streams. Le regroupement permet aux clients d'augmenter le nombre d'enregistrements envoyés par appel d'API, ce qui augmente efficacement le lent e documents envoyés par l'appel d'API, ce qui augmente efficacement le débit de l'application producteur.
Les partitions Kinesis Data Streams acceptent jusqu'à 1 000 enregistrements Kinesis Data Streams par seconde, soit un débit de 1 Mo. Le nombre limite d'enregistrements Kinesis Data Streams par seconde force les clients à avoir des enregistrements inférieurs à 1 Ko. Le regroupement des enregistrements permet aux clients de combiner plusieurs enregistrements en un seul enregistrement Kinesis Data Streams. Cela permet aux clients d'améliorer leur débit par partition.
Prenons le cas d'une partition de la région us-east-1 qui fonctionne actuellement à un rythme constant de 1 000 enregistrements par seconde, avec des enregistrements de 512 octets chacun. Avec le regroupement KPL, vous pouvez compresser 1 000 enregistrements en seulement 10 enregistrements Kinesis Data Streams, ce qui réduit le RPS à 10 (de 50 Ko chacun).
## Collection
La *collecte* consiste à traiter par lot plusieurs enregistrements Kinesis Data Streams et à les envoyer dans une seule demande HTTP avec un appel d'opération API `PutRecords`, au lieu d'envoyer chaque enregistrement Kinesis Data Streams dans sa propre demande HTTP.
Cela augmente le débit en réduisant le coût lié aux nombreuses demandes HTTP distinctes. En fait, l'API `PutRecords` elle-même a été spécifiquement conçue à cet effet.
La collecte est différente du regroupement en cela qu'elle utilise des groupes d'enregistrements Kinesis Data Streams. Les enregistrements Kinesis Data Streams collectés peuvent encore contenir plusieurs enregistrements provenant de l'utilisateur. La relation peut être visualisée comme suit :
```
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--|
```
# Intégrer le KPL au code du producteur
La bibliothèque Amazon Kinesis Producer (KPL) s'exécute dans le cadre d'un processus distinct et communique avec votre processus utilisateur parent à l'aide d'IPC. Cette architecture est parfois appelée un [microservice](http://en.wikipedia.org/wiki/Microservices) et est choisie pour deux raisons principales :
**1) Votre processus utilisateur ne se bloque pas même si la KPL se bloque**
Votre processus peut avoir des tâches non liées à Kinesis Data Streams et peuvent être en mesure de poursuivre l'opération même si la KPL se bloque. Votre processus utilisateur parent peut redémarrer la KPL et redevenir entièrement opérationnel (cette fonctionnalité existe dans les encapsuleurs officiels).
Prenons l'exemple d'un serveur Web qui envoie des métriques à Kinesis Data Streams. Le serveur peut continuer à servir des pages même si la partie Kinesis Data Streams a cessé de fonctionner. Le blocage du serveur entier suite à un bogue dans la KPL provoque donc une panne inutile.
**2) Les clients arbitraires peuvent être pris en charge**
Il y a toujours des clients qui utilisent des langages autres que ceux qui sont officiellement pris en charge. Ces clients doivent également pouvoir utiliser la KPL facilement.
## Matrice d'utilisation recommandée
La matrice d'utilisation suivante répertorie les paramètres recommandés pour les différents utilisateurs et vous indique si et comment vous devez utiliser le KPL. N'oubliez pas que si le regroupement est activé, le dégroupement doit aussi être utilisé pour extraire vos enregistrements du côté consommateur.
| Langage côté producteur | Langage côté consommateur | Version de la KCL | Logique de contrôle | Pouvez-vous utiliser la KPL ? | Mises en garde |
| --- | --- | --- | --- | --- | --- |
| Tout sauf Java | \$1 | \$1 | \$1 | Non | N/A |
| Java | Java | Utilise le SDK Java directement | N/A | Oui | Si le regroupement est utilisé, vous devez utiliser la bibliothèque de regroupement fournie après les appels de GetRecords. |
| Java | Tout sauf Java | Utilise le SDK directement | N/A | Oui | Désactiver obligatoirement le regroupement. |
| Java | Java | 1.3.x | N/A | Oui | Désactiver obligatoirement le regroupement. |
| Java | Java | 1.4.x | Appelle le contrôle sans argument | Oui | Aucune |
| Java | Java | 1.4.x | Appelle le contrôle avec un numéro de séquence explicite | Oui | Désactiver le regroupement ou modifier le code pour utiliser des numéros de séquence étendus pour le contrôle. |
| Java | Tout sauf Java | 1.3.x \$1 démon multilingue \$1 wrapper propre au langage | N/A | Oui | Désactiver obligatoirement le regroupement. |
# Écrivez dans votre flux de données Kinesis à l'aide du KPL
Les sections suivantes présentent des exemples de code dans une progression allant du code de production le plus élémentaire au code entièrement asynchrone.
## Code du producteur Barebones
Le code suivant contient tous les éléments nécessaires pour écrire une application producteur convenable minimale. Les enregistrements utilisateur de l'Amazon Kinesis Producer Library (KPL) sont traités en arrière-plan.
```
// 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 ...
```
## Réagir aux résultats de manière synchrone
Dans l'exemple précédent, le code n'a pas vérifié si les enregistrements KPL utilisateur ont abouti. La KPL effectue toutes les tentatives nécessaires pour tenir compte des défaillances. Si vous voulez vérifier les résultats, vous pouvez les examiner à l'aide des objets `Future` renvoyés par `addUserRecord`, comme dans l'exemple suivant (exemple précédent indiqué pour le contexte) :
```
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
}
}
}
```
## Répondre aux résultats de manière asynchrone
L'exemple précédent fait appel `get()` à un `Future` objet qui bloque l'exécution. Si vous ne souhaitez pas bloquer l'exécution, vous pouvez utiliser un rappel asynchrone, comme illustré dans l'exemple suivant :
```
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);
}
```
# Configuration de la bibliothèque Amazon Kinesis Producer
Bien que les paramètres par défaut fonctionnent en principe bien pour la plupart des cas d'utilisation, vous pouvez en modifier certains paramètres par défaut pour adapter le comportement de `KinesisProducer` à vos besoins. Pour cela, une instance de la classe `KinesisProducerConfiguration` peut être passée au constructeur `KinesisProducer`, par exemple :
```
KinesisProducerConfiguration config = new KinesisProducerConfiguration()
.setRecordMaxBufferedTime(3000)
.setMaxConnections(1)
.setRequestTimeout(60000)
.setRegion("us-west-1");
final KinesisProducer kinesisProducer = new KinesisProducer(config);
```
Vous pouvez également charger une configuration à partir d'un fichier de propriétés :
```
KinesisProducerConfiguration config = KinesisProducerConfiguration.fromPropertiesFile("default_config.properties");
```
Vous pouvez remplacer un chemin d'accès et un nom de fichier auxquels le processus de l'utilisateur peut accéder. Vous pouvez aussi appeler les méthodes set sur l'instance `KinesisProducerConfiguration` créée de cette façon afin de personnaliser la configuration.
Le fichier de propriétés doit spécifier les paramètres en utilisant leur nom dans PascalCase. Les noms correspondent à ceux qui sont utilisés dans les méthodes set de la classe `KinesisProducerConfiguration`. Par exemple :
```
RecordMaxBufferedTime = 100
MaxConnections = 4
RequestTimeout = 6000
Region = us-west-1
```
Pour plus d'informations sur les règles d'utilisation des paramètres de configuration et les limites de valeurs, consultez l'[exemple de fichier de propriétés de configuration sur GitHub](https://github.com/awslabs/amazon-kinesis-producer/blob/master/java/amazon-kinesis-producer-sample/default_config.properties).
Notez que, une fois que `KinesisProducer` est initialisé, la modification de l'instance `KinesisProducerConfiguration` qui a été utilisée n'a aucun autre effet. `KinesisProducer` ne soutient pas actuellement la reconfiguration dynamique.
# Mettre en œuvre la désagrégation des consommateurs
À partir de la version 1.4.0, la KCL prend en charge le dégroupement automatique des enregistrements utilisateur KPL. Le code de l'application consommateur écrit avec les versions antérieures de la KCL sera compilé sans aucune modification lorsque vous aurez mis à jour la KCL. Toutefois, si la fonctionnalité de regroupement KPL est utilisée côté producteur, le contrôle comporte une subtilité : tous les sous-enregistrements figurant dans un enregistrement ont le même numéro de séquence si bien que des données supplémentaires doivent être stockées avec le point de contrôle si vous avez besoin de différencier les sous-enregistrements. Ces données supplémentaires s'appellent le *numéro de sous-séquence*.
**Topics**
+ [Migrer depuis les versions précédentes de la KCL](#kinesis-kpl-consumer-deaggregation-migration)
+ [Utiliser les extensions KCL pour la désagrégation KPL](#kinesis-kpl-consumer-deaggregation-extensions)
+ [Utiliser GetRecords directement](#kinesis-kpl-consumer-deaggregation-getrecords)
## Migrer depuis les versions précédentes de la KCL
Vous n'êtes pas obligé de modifier vos appels existants pour effectuer des points de contrôle avec agrégation. L'extraction de tous les enregistrements stockés avec succès dans Kinesis Data Streams demeure garantie. La KCL propose désormais deux nouvelles opérations de point de contrôle pour prendre en charge des cas d'utilisation particuliers, décrits ci-dessous.
Si votre code existant a été écrit pour la KCL avant le support KPL et que votre opération de point de contrôle est appelée sans arguments, cela revient à vérifier le numéro de séquence du dernier enregistrement utilisateur KPL du lot. Si votre opération de contrôle est appelée avec une chaîne de numéro de séquence, cela équivaut à contrôler le numéro de séquence donné du lot ainsi que le numéro de sous-séquence implicite 0 (zéro).
L'appel de la nouvelle opération de contrôle KCL `checkpoint()` sans argument est équivalent sémantiquement au contrôle du numéro de séquence du dernier appel `Record` du lot, accompagné du numéro de sous-séquence implicite 0 (zéro).
L'appel de la nouvelle opération de contrôle KCL `checkpoint(Record record)` est équivalent sémantiquement au contrôle du numéro de séquence donné du `Record`, accompagné du numéro de sous-séquence implicite 0 (zéro). Si l'appel `Record` est en fait un `UserRecord`, le numéro de séquence et le numéro de sous-séquence `UserRecord` sont contrôlés.
L'appel de la nouvelle opération de contrôle KCL `checkpoint(String sequenceNumber, long subSequenceNumber)` contrôle explicitement le numéro de séquence donné ainsi que le numéro de sous-séquence donné.
Dans chacun de ces cas, une fois que le point de contrôle est stocké dans la table de point de contrôle Amazon DynamoDB, la KCL peut correctement reprendre l'extraction des enregistrements même lorsque l'application se bloque et redémarre. Si la séquence contient plusieurs enregistrements, l'extraction commence par l'enregistrement ayant le numéro de sous-séquence suivant dans l'enregistrement ayant le numéro de séquence contrôlé le plus récemment. Si le dernier contrôle incluait le tout dernier numéro de sous-séquence de l'enregistrement ayant le numéro de séquence précédent, l'extraction commence par l'enregistrement avec le numéro de séquence suivant.
La section suivante décrit en détail les points de contrôle des séquences et des sous-séquences pour les consommateurs, qui doivent éviter de sauter ou de dupliquer des enregistrements. S'il importe peu que des enregistrements soient sautés (ou dupliqués) lors de l'arrêt ou du redémarrage du traitement des enregistrements du consommateur, vous pouvez exécuter votre code existant sans modification.
## Utiliser les extensions KCL pour la désagrégation KPL
La désagrégation KPL peut impliquer un point de contrôle des sous-séquences. Pour faciliter l'utilisation du contrôle de sous-séquence, une classe `UserRecord` a été ajoutée à la 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 */
}
}
```
Cette classe est maintenant utilisée à la place de `Record`. Elle ne casse pas le code existant, car c'est une sous-classe de `Record`. La classe `UserRecord` représente à la fois les sous-enregistrements réels et les enregistrements non regroupés standard. Les enregistrements non regroupés peuvent être considérés comme des enregistrements regroupés contenant un seul sous-enregistrement.
En outre, deux nouvelles opérations ont été ajoutées à `IRecordProcessorCheckpointer` :
```
public void checkpoint(Record record);
public void checkpoint(String sequenceNumber, long subSequenceNumber);
```
Pour commencer à utiliser le contrôle du numéro de sous-séquence, vous pouvez effectuer la conversion ci-dessous. Modifiez le code de formulaire suivant :
```
checkpointer.checkpoint(record.getSequenceNumber());
```
Nouveau code de formulaire :
```
checkpointer.checkpoint(record);
```
Nous vous recommandons d'utiliser le formulaire `checkpoint(Record record)` pour le contrôle de sous-séquence. Toutefois, si vous stockez déjà `sequenceNumbers` dans les chaînes à utiliser pour les points de contrôle, vous devez désormais stocker aussi `subSequenceNumber`, comme l'illustre l'exemple suivant :
```
String sequenceNumber = record.getSequenceNumber();
long subSequenceNumber = ((UserRecord) record).getSubSequenceNumber(); // ... do other processing
checkpointer.checkpoint(sequenceNumber, subSequenceNumber);
```
Le cast from `Record` to réussit `UserRecord` toujours car l'implémentation utilise `UserRecord` toujours. À moins qu'il ne soit nécessaire d'effectuer des opérations arithmétiques sur les numéros de séquence, cette approche n'est pas recommandée.
Lors du traitement des enregistrements utilisateur KPL, la KCL écrit le numéro de sous-séquence dans Amazon DynamoDB sous la forme d'un champ supplémentaire pour chaque ligne. Les versions antérieures de la KCL utilisaient `AFTER_SEQUENCE_NUMBER` pour extraire les enregistrements lors de la reprise des points de contrôle. La KCL actuelle avec prise en charge KPL utilise `AT_SEQUENCE_NUMBER` à la place. Lorsque l'enregistrement situé au numéro de séquence contrôlé est extrait, le numéro de sous-séquence contrôlé est vérifié, et les sous-enregistrements sont abandonnés le cas échéant (ce peut être tous si le dernier sous-enregistrement est celui qui est contrôlé). Encore, les enregistrements non regroupés peuvent être considérés comme des enregistrements regroupés contenant un seul sous-enregistrement, si bien que le même algorithme fonctionne aussi bien pour les enregistrements regroupés que pour les enregistrements non regroupés.
## Utiliser GetRecords directement
Vous pouvez également choisir de ne pas utiliser la KCL, mais d'invoquer directement l'opération d'API `GetRecords` pour extraire les enregistrements Kinesis Data Streams. Pour décompresser ces enregistrements dans vos enregistrements utilisateur KPL initiaux, appelez l'une des opérations statiques suivantes figurant dans `UserRecord.java` :
```
public static List deaggregate(List records)
public static List deaggregate(List records, BigInteger startingHashKey, BigInteger endingHashKey)
```
La première opération utilise la valeur par défaut `0` (zéro) pour `startingHashKey` et la valeur par défaut `2^128 -1` pour `endingHashKey`.
Chacune de ces opérations dégroupe la liste des enregistrements Kinesis Data Streams dans une liste d'enregistrements utilisateur KPL. Tout enregistrement utilisateur KPL dont la clé de hachage ou la clé de partition explicite n'est pas comprise dans la plage de `startingHashKey` (inclus) et de `endingHashKey` (inclus) est supprimé de la liste d'enregistrements renvoyée.
# Utiliser le KPL avec Amazon Data Firehose
Si vous utilisez la bibliothèque producteur Kinesis (KPL) pour écrire des données dans un flux de données Kinesis, vous pouvez utiliser un regroupement pour combiner ces enregistrements Kinesis. Si vous utilisez ensuite ce flux de données comme source pour votre flux de diffusion Firehose, Firehose désagrège les enregistrements avant de les livrer à destination. Si vous configurez votre flux de diffusion pour transformer les données, Firehose désagrège les enregistrements avant de les transmettre. AWS Lambda Pour plus d'informations, consultez [Écriture de données à Amazon Kinesis Firehose à l'aide de flux de données Kinesis](https://docs.aws.amazon.com/firehose/latest/dev/writing-with-kinesis-streams.html) (français non garanti).
# Utiliser le KPL avec le registre des AWS Glue schémas
Vous pouvez intégrer vos flux de données Kinesis au registre des AWS Glue schémas. Le registre des AWS Glue schémas vous permet de découvrir, de contrôler et de faire évoluer les schémas de manière centralisée, tout en garantissant que les données produites sont continuellement validées par un schéma enregistré. Un schéma définit la structure et le format d'un enregistrement de données. Un schéma est une spécification versionnée pour la publication, la consommation ou le stockage des données fiables. Le registre des AWS Glue schémas vous permet d'améliorer la qualité end-to-end des données et la gouvernance des données au sein de vos applications de streaming. Pour plus d'informations, consultez le registre [AWS Glue Schema](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html) (français non garanti). Vous pouvez notamment configurer cette intégration via les bibliothèques KPL et KCL en Java.
**Important**
Actuellement, l'intégration de Kinesis Data Streams AWS Glue et de registres de schémas n'est prise en charge que pour les flux de données Kinesis qui utilisent des producteurs KPL implémentés en Java. La prise en charge multilingue n'est pas fournie.
Pour obtenir des instructions détaillées sur la façon de configurer l'intégration de Kinesis Data Streams à Schema Registry à l'aide du KPL, consultez la section « Interaction avec les données à KPL/KCL l'aide des bibliothèques » [dans Use Case : Integrating Amazon Kinesis Data Streams with AWS the](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-integrations.html#schema-registry-integrations-kds) Glue Schema Registry.
# Configurer la configuration du proxy KPL
Pour les applications qui ne peuvent pas se connecter directement à Internet, tous les clients du AWS SDK prennent en charge l'utilisation de proxys HTTP ou HTTPS. Au sein d'un environnement d'entreprise classique, tout le trafic réseau sortant doit passer par des serveurs proxy. Si votre application utilise la Kinesis Producer Library (KPL) pour collecter et envoyer des données AWS dans un environnement qui utilise des serveurs proxy, elle doit être configurée en tant que proxy KPL. KPL est une bibliothèque de haut niveau basée sur le SDK AWS Kinesis. Elle est divisée en un processus natif et un encapsuleur. Le processus natif exécute toutes les tâches de traitement et d'envoi des enregistrements, tandis que l'encapsuleur gère le processus natif et communique avec lui. Pour obtenir plus d'informations, consultez [Implémentation de producteurs efficaces et fiables avec la bibliothèque producteur Amazon Kinesis](https://aws.amazon.com/blogs/big-data/implementing-efficient-and-reliable-producers-with-the-amazon-kinesis-producer-library/) (français non garanti).
L'encapsuleur est écrit en Java et le processus natif est écrit en C\$1\$1 à l'aide du SDK Kinesis. Les versions 0.14.7 et supérieures de la KPL prennent désormais en charge la configuration de proxy dans l'encapsuleur Java qui peut transmettre toutes les configurations de proxy au processus natif. Pour plus d'informations, consultez [https://github.com/awslabs/amazon-kinesis-producer/releases/tag/v0.14.7](https://github.com/awslabs/amazon-kinesis-producer/releases/tag/v0.14.7).
Utilisez le code suivant pour ajouter des configurations de proxy à vos applications 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);
```
# Politique de cycle de vie des versions KPL
Cette rubrique décrit la politique de cycle de vie des versions pour Amazon Kinesis Producer Library (KPL). AWS fournit régulièrement de nouvelles versions pour les versions de KPL afin de prendre en charge les nouvelles fonctionnalités et améliorations, les corrections de bogues, les correctifs de sécurité et les mises à jour de dépendances. Nous vous recommandons de vous en tenir up-to-date aux versions de KPL pour vous tenir au courant des dernières fonctionnalités, des mises à jour de sécurité et des dépendances sous-jacentes. Nous **ne recommandons pas** de continuer à utiliser une version de KPL non prise en charge.
Le cycle de vie des principales versions de KPL comprend les trois phases suivantes :
+ **Disponibilité générale (GA)** — Au cours de cette phase, la version majeure est entièrement prise en charge. AWS fournit régulièrement des versions mineures et des correctifs qui incluent la prise en charge de nouvelles fonctionnalités ou des mises à jour d'API pour Kinesis Data Streams, ainsi que des correctifs de bogues et de sécurité.
+ **Mode maintenance** : AWS limite les versions de correctifs publiées uniquement pour résoudre les corrections de bogues critiques et les problèmes de sécurité. La version majeure ne recevra pas de mises à jour relatives aux nouvelles fonctionnalités ou APIs à Kinesis Data Streams.
+ **E nd-of-support** — La version majeure ne recevra plus de mises à jour ni de versions. Les versions précédemment publiées continueront d'être disponibles via les gestionnaires de packages publics et le code restera activé GitHub. L'utilisation d'une version atteinte se end-of-support fait à la discrétion de l'utilisateur. Nous vous recommandons de passer à la dernière version majeure.
| Version majeure | Phase en cours | Date de publication | Date du mode de maintenance | End-of-support date |
| --- | --- | --- | --- | --- |
| KPL 0.x | Mode de maintenance | 02/06/2015 | 17/04/2025 | 30-01-2026/ |
| KPL 1.x | Disponibilité générale | 15/12/2024 | -- | -- |