Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Sviluppa produttori utilizzando Amazon Kinesis Producer Library (KPL)
Un producer del flusso di dati Amazon Kinesis è qualsiasi applicazione che inserisce record di dati utente in un flusso di dati Kinesis (anche detto *importazione dei dati*). Amazon Kinesis Producer Library (KPL) semplifica lo sviluppo di applicazioni di produzione, permettendo agli sviluppatori di ottenere un throughput di scrittura elevato su un flusso di dati Kinesis.
Puoi monitorare il KPL con Amazon CloudWatch. Per ulteriori informazioni, consulta [Monitora la libreria Kinesis Producer con Amazon CloudWatch](monitoring-with-kpl.md).
**Topics**
+ [Rivedi il ruolo del KPL](#developing-producers-with-kpl-role)
+ [Scopri i vantaggi dell'utilizzo di KPL](#developing-producers-with-kpl-advantage)
+ [Comprendi quando non usare KPL](#developing-producers-with-kpl-when)
+ [Installa KPL](kinesis-kpl-dl-install.md)
+ [Esegui la migrazione da KPL 0.x a KPL 1.x](kpl-migration-1x.md)
+ [Transizione ai certificati Amazon Trust Services (ATS) per la KPL](kinesis-kpl-upgrades.md)
+ [Piattaforme supportate da KPL](kinesis-kpl-supported-plats.md)
+ [Concetti chiave di KPL](kinesis-kpl-concepts.md)
+ [Integra KPL con il codice del produttore](kinesis-kpl-integration.md)
+ [Scrivi nel tuo flusso di dati Kinesis utilizzando KPL](kinesis-kpl-writing.md)
+ [Configurazione della libreria Amazon Kinesis Producer](kinesis-kpl-config.md)
+ [Implementa la deaggregazione dei consumatori](kinesis-kpl-consumer-deaggregation.md)
+ [Usa KPL con Amazon Data Firehose](kpl-with-firehose.md)
+ [Utilizzate il KPL con lo Schema Registry AWS Glue](kpl-with-schemaregistry.md)
+ [Configura la configurazione del proxy KPL](kpl-proxy-configuration.md)
+ [Politica del ciclo di vita della versione KPL](kpl-version-lifecycle-policy.md)
**Nota**
Consigliamo di eseguire l'aggiornamento alla versione KPL più recente. La KCL viene regolarmente aggiornata con versioni più recenti che includono le ultime patch di dipendenza e sicurezza, correzioni di bug e nuove funzionalità retrocompatibili. Per maggiori informazioni, consulta [https://github.com/awslabs/amazon-kinesis-producer/releases/](https://github.com/awslabs/amazon-kinesis-producer/releases/).
## Rivedi il ruolo del KPL
KPL è una easy-to-use libreria altamente configurabile che ti aiuta a scrivere su un flusso di dati Kinesis. Funge da intermediario tra il codice dell'applicazione producer e le operazioni API del flusso di dati Kinesis. La KPL esegue le seguenti attività primarie:
+ Scrive su uno o più flussi di dati Kinesis con un meccanismo di tentativi automatico e configurabile
+ Raccoglie record e utilizza `PutRecords` per scrivere più record in più shard per richiesta
+ Unisce i record degli utenti per aumentare la dimensione del payload e migliorare il throughput
+ Si integra perfettamente con la [Kinesis Client Library](https://docs.aws.amazon.com/kinesis/latest/dev/developing-consumers-with-kcl.html) (KCL) per disaggregare i record raggruppati nel consumer
+ Invia i CloudWatch parametri di Amazon per tuo conto per fornire visibilità sulle prestazioni dei produttori
Tieni presente che KPL è diverso dall'API Kinesis Data Streams disponibile in. [AWS SDKs](https://aws.amazon.com/tools/) L'API del flusso di dati Kinesis consente di gestire molti aspetti del flusso di dati Kinesis (inclusa la creazione di flussi, il ripartizionamento e l'inserimento e l'estrazione di record), mentre la KPL fornisce un livello di astrazione specificamente per l'importazione dei dati. Per ulteriori informazioni sulle API del flusso di dati Kinesis, consulta la [Documentazione di riferimento delle API di Amazon Kinesis](https://docs.aws.amazon.com/kinesis/latest/APIReference/).
## Scopri i vantaggi dell'utilizzo di KPL
L'elenco seguente rappresenta alcuni dei principali vantaggi dell'utilizzo della KPL per lo sviluppo di producer del flusso di dati Kinesis.
La KPL può essere utilizzata in casi di utilizzo sincroni o asincroni. Suggeriamo di utilizzare le prestazioni più elevate dell'interfaccia asincrona, a meno che non vi sia un motivo specifico per l'utilizzo del comportamento sincrono. Per ulteriori informazioni su questi due casi d'uso e sul codice di esempio, consulta [Scrivi nel tuo flusso di dati Kinesis utilizzando KPL](kinesis-kpl-writing.md).
**Vantaggi in termini di prestazioni**
La KPL può aiutare a creare producer ad alte prestazioni. Considera una situazione in cui le istanze Amazon EC2 servono come proxy per la raccolta di eventi a 100 byte provenienti da centinaia o migliaia di dispositivi a bassa potenza e record di scrittura in un flusso di dati Kinesis. Queste istanze EC2 devono scrivere migliaia di eventi al secondo ciascuna per il flusso di dati. Per ottenere il throughput necessario, i produttori devono implementare una logica complicata, ad esempio esecuzione di batch o multithreading, in aggiunta al tentativo di disaggregare la logica e i record da parte del consumer. La KPL esegue tutte queste attività per tuo conto.
**Consumer-Side Ease of Use (Facilità utilizzo lato consumer)**
Per gli sviluppatori lato consumer che utilizzano la KCL in Java, la KPL si integra senza sforzo aggiuntivo. Quando la KCL recupera un record del flusso di dati Kinesis aggregato composto da più record utente della KPL, automaticamente richiama la KPL per estrarre i record utente individuali prima di restituirli all'utente.
Per gli sviluppatori lato consumer che non utilizzano la KCL ma invece utilizzano l'operazione API `GetRecords` direttamente, una libreria Java della KPL è disponibile per estrarre i record utente individuali prima di restituirli all'utente.
**Monitoraggio producer**
Puoi raccogliere, monitorare e analizzare i tuoi produttori di Kinesis Data Streams utilizzando CloudWatch Amazon e KPL. Il KPL emette velocità effettiva, errori e altre metriche per tuo CloudWatch conto ed è configurabile per il monitoraggio a livello di stream, shard o produttore.
**Asynchronous Architecture (Architettura asincrona)**
Poiché il KPL può memorizzare nel buffer i record prima di inviarli a Kinesis Data Streams, non impone all'applicazione chiamante di bloccarsi e attendere la conferma che il record è arrivato al server prima di continuare l'esecuzione. Una chiamata per inserire un record nella KPL restituisce sempre immediatamente e non attende l'invio del record né di ricevere una risposta dal server. Al contrario, viene creato un oggetto `Future` che riceve il risultato di inviare il record al flusso di dati Kinesis in un secondo momento. Questo è lo stesso comportamento dei client asincroni nell'SDK. AWS
## Comprendi quando non usare KPL
La KPL può subire un ulteriore ritardo di elaborazione fino a `RecordMaxBufferedTime` all'interno della libreria (configurabile dall'utente). Valori più elevati di `RecordMaxBufferedTime` risultano in creazione di pacchetti più veloce e prestazioni migliori. Le applicazioni che non possono tollerare questo ritardo aggiuntivo potrebbero dover utilizzare direttamente l' AWS SDK. Per ulteriori informazioni sull'utilizzo dell' AWS SDK con Kinesis Data Streams, consulta. [Sviluppa i produttori utilizzando l'API Amazon Kinesis Data Streams con AWS SDK per Java](developing-producers-with-sdk.md) Per ulteriori informazioni su `RecordMaxBufferedTime` e altre proprietà configurabili dall'utente della KPL, consulta [Configurazione della libreria Amazon Kinesis Producer](kinesis-kpl-config.md).
# Installa KPL
Amazon fornisce file binari predefiniti della Amazon Kinesis Producer Library (KPL) C\$1\$1 per macOS, Windows e distribuzioni Linux recenti (per i dettagli sulla piattaforma supportata, consulta la sezione successiva). Questi file binari vengono confezionati come parte dei file.jar Java e vengono automaticamente richiamati e utilizzati se utilizzi Maven per installare il pacchetto. Per individuare le versioni più recenti della KPL e della KCL, utilizza i seguenti collegamenti di ricerca Maven:
+ [KPL](https://search.maven.org/#search|ga|1|amazon-kinesis-producer)
+ [KCL](https://search.maven.org/#search|ga|1|amazon-kinesis-client)
I file binari Linux sono stati compilati con GNU Compiler Collection (GCC) e collegati staticamente a libstdc\$1\$1 su Linux. Dovrebbero funzionare su qualsiasi distribuzione Linux a 64 bit, che include una versione glibc 2.5 o successiva.
Gli utenti di distribuzioni Linux precedenti possono creare il KPL utilizzando le istruzioni di compilazione fornite insieme al codice sorgente. GitHub Per scaricare il KPL da GitHub, consulta [Amazon Kinesis](https://github.com/awslabs/amazon-kinesis-producer) Producer Library.
**Importante**
Amazon Kinesis Producer Library (KPL) 0.x sarà disponibile il 30 end-of-support gennaio 2026. **Ti consigliamo vivamente di** migrare le tue applicazioni KPL utilizzando la versione 0.x all'ultima versione KPL prima del 30 gennaio 2026. [Per trovare la versione KPL più recente, consulta la pagina KPL su Github.](https://github.com/awslabs/amazon-kinesis-producer) Per informazioni sulla migrazione da KPL 0.x a KPL 1.x, consulta. [Esegui la migrazione da KPL 0.x a KPL 1.x](kpl-migration-1x.md)
# Esegui la migrazione da KPL 0.x a KPL 1.x
Questo argomento fornisce step-by-step istruzioni per migrare il consumatore da KPL 0.x a KPL 1.x. KPL 1.x introduce il supporto per la versione AWS SDK per Java 2.x pur mantenendo la compatibilità dell'interfaccia con le versioni precedenti. Non è necessario aggiornare la logica di elaborazione dei dati di base per migrare a KPL 1.x.
1. **Assicurati di avere i seguenti prerequisiti:**
+ Java Development Kit (JDK) 8 o versione successiva
+ AWS SDK per Java 2.x
+ Maven o Gradle per la gestione delle dipendenze
1. **Aggiungi dipendenze**
Se utilizzi Maven, aggiungi la seguente dipendenza al tuo file pom.xml. Assicurati di aver aggiornato GroupId `com.amazonaws` da `software.amazon.kinesis` a e la `1.x.x` versione all'ultima versione KPL.
```
software.amazon.kinesis
amazon-kinesis-producer
1.x.x
```
Se stai usando Gradle, aggiungi quanto segue al tuo file. `build.gradle` Assicurati di sostituirlo `1.x.x` con l'ultima versione di KPL.
```
implementation 'software.amazon.kinesis:amazon-kinesis-producer:1.x.x'
```
Puoi verificare la versione più recente di KPL sul [Maven](https://central.sonatype.com/search?q=amazon-kinesis-producer) Central Repository.
1. **Aggiorna le dichiarazioni di importazione per KPL**
KPL 1.x utilizza la versione AWS SDK per Java 2.x e utilizza un nome di pacchetto aggiornato che inizia con`software.amazon.kinesis`, rispetto al nome del pacchetto nel KPL precedente che inizia con. `com.amazonaws.services.kinesis`
Sostituisci l'importazione per con. `com.amazonaws.services.kinesis` `software.amazon.kinesis` La tabella seguente elenca le importazioni che è necessario sostituire.
**Importa sostituzioni**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/streams/latest/dev/kpl-migration-1x.html)
1. **Aggiorna le dichiarazioni di importazione per le classi del fornitore di credenziali AWS **
Durante la migrazione a KPL 1.x, è necessario aggiornare i pacchetti e le classi importati nel codice dell'applicazione KPL basati sulla versione AWS SDK per Java 1.x con quelli corrispondenti basati sulla 2.x. AWS SDK per Java Le importazioni comuni nell'applicazione KPL sono le classi di fornitori di credenziali. Consulta [le modifiche al provider di credenziali](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-client-credentials.html) nella documentazione della guida alla migrazione AWS SDK per Java 2.x per l'elenco completo delle modifiche al provider di credenziali. Ecco le comuni modifiche di importazione che potresti dover apportare alle tue applicazioni KPL.
**Importa in KPL 0.x**
```
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
```
**Importazione in KPL 1.x**
```
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
```
Se importi altri provider di credenziali basati sulla versione AWS SDK per Java 1.x, devi aggiornarli con quelli equivalenti alla AWS SDK per Java versione 2.x. Se non ne hai importato nessuno classes/packages dalla versione AWS SDK per Java 1.x, puoi ignorare questo passaggio.
1. **Aggiorna la configurazione del provider di credenziali nella configurazione KPL**
La configurazione del provider di credenziali in KPL 1.x richiede i provider di credenziali 2.x. AWS SDK per Java Se stai passando i provider di credenziali per la versione AWS SDK per Java 1.x `KinesisProducerConfiguration` sovrascrivendo il provider di credenziali predefinito, devi aggiornarlo con i provider di credenziali 2.x. AWS SDK per Java Vedi Modifiche al [provider di credenziali nella documentazione della guida alla migrazione AWS SDK per Java 2.x per l'elenco completo delle modifiche](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-client-credentials.html) al provider di credenziali. Se non hai sovrascritto il provider di credenziali predefinito nella configurazione KPL, puoi ignorare questo passaggio.
Ad esempio, se stai sovrascrivendo il provider di credenziali predefinito per KPL con il codice seguente:
```
KinesisProducerConfiguration config = new KinesisProducerConfiguration();
// SDK v1 default credentials provider
config.setCredentialsProvider(new DefaultAWSCredentialsProviderChain());
```
È necessario aggiornarli con il codice seguente per utilizzare il provider di credenziali AWS SDK per Java 2.x:
```
KinesisProducerConfiguration config = new KinesisProducerConfiguration();
// New SDK v2 default credentials provider
config.setCredentialsProvider(DefaultCredentialsProvider.create());
```
# Transizione ai certificati Amazon Trust Services (ATS) per la KPL
Il 9 febbraio 2018, alle 9.00 PST, Flusso di dati Amazon Kinesis ha installato i certificati ATS. [Per continuare a scrivere record su Kinesis Data Streams utilizzando Amazon Kinesis Producer Library (KPL), è necessario aggiornare l'installazione di KPL alla versione 0.12.6 o successiva.](http://search.maven.org/#artifactdetails|com.amazonaws|amazon-kinesis-producer|0.12.6|jar) Questa modifica riguarda tutte le regioni. AWS
Per informazioni sul passaggio ad ATS, consulta [How to Prepare for AWS's Move to Its Own Certificate Authority](https://aws.amazon.com/blogs/security/how-to-prepare-for-aws-move-to-its-own-certificate-authority/).
In caso di problemi e se hai bisogno di supporto tecnico, [crea un caso](https://console.aws.amazon.com/support/v1#/case/create) utilizzando il Centro di supporto AWS .
# Piattaforme supportate da KPL
Amazon Kinesis Producer Library (KPL) è scritta in C\$1\$1 e viene eseguita come processo secondario rispetto al processo utente principale. I file binari nativi precompilati a 64 bit sono nel rilascio di Java e sono gestiti dal wrapper Java.
Il pacchetto Java viene eseguito senza la necessità di installare librerie aggiuntive per i seguenti sistemi operativi:
+ Distribuzioni Linux con kernel 2.6.18 (settembre 2006) e versioni successive
+ Apple iOS X 10.9 e versioni successive
+ Windows Server 2008 e versione successiva
**Importante**
Windows Server 2008 e versioni successive è supportato per tutte le versioni KPL fino alla versione 0.14.0.
La piattaforma Windows NON è supportata a partire dalla versione KPL 0.14.0 o successiva.
Tenere presente che la KPL è solo a 64 bit.
## Codice sorgente
Se i file binari forniti nell'installazione della KPL non sono sufficienti per l'ambiente, il core della KPL sarà scritto come modulo C\$1\$1. Il codice sorgente per il modulo C\$1\$1 e l'interfaccia Java sono rilasciati con Amazon Public License e sono disponibili GitHub presso [Amazon Kinesis](https://github.com/awslabs/amazon-kinesis-producer) Producer Library. Sebbene la KPL possa essere utilizzata su qualsiasi piattaforma per la quale sono disponibili un compilatore C\$1\$1 conforme agli standard e JRE, Amazon non supporta ufficialmente alcuna piattaforma che non si trova nell'elenco delle piattaforme supportate.
# Concetti chiave di KPL
Le seguenti sezioni contengono i concetti e la terminologia necessari per comprendere e sfruttare la Amazon Kinesis Producer Library (KPL).
**Topics**
+ [Registri](#kinesis-kpl-concepts-records)
+ [Batching](#kinesis-kpl-concepts-batching)
+ [Aggregazione](#kinesis-kpl-concepts-aggretation)
+ [Raccolta](#kinesis-kpl-concepts-collection)
## Registri
In questa guida, si distingue tra *record utente della KPL* e *record del flusso di dati Kinesis*. Quando utilizziamo il termine *record* senza un qualificatore, ci riferiamo a un *record utente dell KPL*. Quando facciamo riferimento a un record del flusso di dati Kinesis, diciamo esplicitamente *record del flusso di dati Kinesis*.
Un record utente della KPL è un blob di dati che ha un significato particolare per l'utente. Alcuni esempi includono un blob JSON che rappresenta un evento di interfaccia utente su un sito Web o una voce di log da un server Web.
Un record del flusso di dati Kinesis è un'istanza della struttura dati `Record` definita dall'API del servizio del flusso di dati Kinesis. Contiene una chiave di partizione, un numero di sequenza e un blob di dati.
## Batching
*Batching* si riferisce all'esecuzione di una singola operazione su più elementi anziché eseguire ripetutamente l'operazione su ogni singolo elemento.
In questo contesto, un "elemento" è un record e l'operazione è inviarlo al flusso di dati Kinesis. In una situazione non di batching, è necessario posizionare ogni record in un record del flusso di dati Kinesis separato ed effettuare una richiesta HTTP per inviarlo al flusso di dati Kinesis. Con batching, ogni richiesta HTTP è in grado di eseguire più record invece di uno solo.
La KPL supporta due tipi di batching:
+ *Aggregazione*: l'archiviazione di più record in un singolo record del flusso di dati Kinesis.
+ *Raccolta*: l'utilizzo dell'operazione API `PutRecords` per inviare più record del flusso di dati Kinesis a una o più partizioni nel flusso di dati Kinesis.
I due tipi di batching KPL sono stati progettati per coesistere e possono essere attivati o disattivati in modo indipendente. Come impostazione predefinita, entrambi sono abilitati.
## Aggregazione
*Aggregazione* si riferisce all'archiviazione di più record in un record del flusso di dati Kinesis. L'aggregazione consente ai clienti di aumentare il numero di record inviati per chiamata API e ciò aumenta anche il throughput producer.
Le partizioni del flusso di dati Kinesis supportano fino a 1.000 record del flusso di dati Kinesis al secondo o 1 MB di velocità di trasmissione effettiva. I record al secondo del flusso di dati Kinesis vincola i clienti a record di dimensioni inferiori a 1 KB. L'aggregazione dei record consente ai clienti di combinare più record in un singolo record del flusso di dati Kinesis. Questo consente ai clienti di migliorare il loro throughput per shard.
Si consideri il caso di uno shard nella regione us-east-1 attualmente in esecuzione a una velocità costante di 1.000 record al secondo, con record di 512 byte ciascuno. Con l'aggregazione della KPL, è possibile impacchettare 1.000 record in soli 10 record del flusso di dati Kinesis, riducendo le richieste al secondo (RPS) a 10 (a 50 KB ognuna).
## Raccolta
*Raccolta* si riferisce alla creazione di batch di più record del flusso di dati Kinesis e al loro invio in una singola richiesta HTTP con una chiamata all'operazione API `PutRecords`, invece che inviare ogni record del flusso di dati Kinesis nella propria richiesta HTTP.
Questo aumenta il throughput rispetto all'utilizzo di nessuna raccolta perché riduce i costi di molte richieste HTTP separate. Infatti, `PutRecords` è stato specificamente progettato per questo scopo.
La raccolta differisce dall'aggregazione in quanto lavora con gruppi di record del flusso di dati Kinesis. I record del flusso di dati Kinesis raccolti possono comunque contenere più record da parte dell'utente. La relazione può essere visualizzata come segue:
```
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--|
```
# Integra KPL con il codice del produttore
Amazon Kinesis Producer Library (KPL) viene eseguita in un processo separato e comunica con il processo utente principale tramite IPC. Questa architettura talvolta viene definita un [microservizio](http://en.wikipedia.org/wiki/Microservices) ed è scelta per due motivi:
**1) Il processo utente non si interrompe anche se la KPL riporta un arresto anomalo**
Il processo può avere attività non correlate al flusso di dati Kinesis e può essere in grado di continuare l'operazione anche se la KPL si arresta in maniera anomala. È anche possibile che il processo dell'utente principale riavvi la KPL e passi a uno stato di funzionamento completo (questa funzionalità è nei wrapper ufficiali).
Un esempio è un server Web che invia i parametri al flusso di dati Kinesis; il server può continuare a servire le pagine anche se la parte del flusso di dati Kinesis ha smesso di funzionare. Interrompere l'intero server a causa di un bug nella KPL provocherebbe interruzioni inutili.
**2) I client arbitrari possono essere supportati**
Ci sono sempre clienti che utilizzano linguaggi diversi da quelli ufficialmente supportati. Questi clienti dovrebbero essere in grado di utilizzare facilmente la KPL.
## Matrice di utilizzo consigliata
La seguente matrice di utilizzo elenca le impostazioni consigliate per i diversi utenti e consiglia se e come utilizzare il KPL. Ricorda che se l'aggregazione è abilitata, la disaggregazione deve essere utilizzata per estrarre i record nel lato consumer.
| Linguaggio lato producer | Linguaggio lato consumer | Versione della KCL | Logica di checkpoint | Puoi utilizzare la KPL? | Avvertenze |
| --- | --- | --- | --- | --- | --- |
| Tutto tranne Java | \$1 | \$1 | \$1 | No | N/D |
| Java | Java | Utilizza Java SDK direttamente | N/D | Sì | Se l'aggregazione viene utilizzata, è necessario utilizzare la libreria di disaggregazione fornita dopo le chiamate GetRecords. |
| Java | Tutto tranne Java | Utilizza SDK direttamente | N/D | Sì | È necessario disabilitare l'aggregazione. |
| Java | Java | 1.3.x | N/D | Sì | È necessario disabilitare l'aggregazione. |
| Java | Java | 1.4.x | Chiama il checkpoint senza alcun argomento | Sì | Nessuno |
| Java | Java | 1.4.x | Chiama il checkpoint con un numero di sequenza esplicito | Sì | Disabilita l'aggregazione o modifica il codice per utilizzare numeri di sequenza estesi per il checkpoint. |
| Java | Tutto tranne Java | 1.3.x \$1 daemon multilingua \$1 wrapper specifici della lingua | N/D | Sì | È necessario disabilitare l'aggregazione. |
# Scrivi nel tuo flusso di dati Kinesis utilizzando KPL
Le sezioni seguenti mostrano un esempio di codice in una progressione dal produttore più semplice al codice completamente asincrono.
## Codice del produttore Barebones
Il codice seguente è tutto quello che serve per scrivere un producer che lavora al minimo. I record utente di Amazon Kinesis Producer Library (KPL) vengono elaborati in background.
```
// 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 ...
```
## Rispondi ai risultati in modo sincrono
Nell'esempio precedente, il codice non ha controllato se i record utente della KPL sono riusciti. La KPL esegue qualsiasi tentativo necessario per tenere conto degli errori. Tuttavia, se desideri controllare i risultati, puoi esaminarli utilizzando gli oggetti `Future` restituiti da `addUserRecord`, come nell'esempio seguente (esempio precedente mostrato per contesto):
```
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
}
}
}
```
## Rispondi ai risultati in modo asincrono
L'esempio precedente è la chiamata `get()` a un `Future` oggetto, che blocca il runtime. Se non vuoi bloccare il runtime, puoi usare un callback asincrono, come mostrato nell'esempio seguente:
```
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);
}
```
# Configurazione della libreria Amazon Kinesis Producer
Nonostante le impostazioni predefinite dovrebbero funzionare perfettamente per la maggior parte dei casi d'uso, è consigliabile modificare alcune delle impostazioni predefinite per adattare il comportamento di `KinesisProducer` alle proprie esigenze. Un'istanza di classe `KinesisProducerConfiguration` può essere passata al costruttore `KinesisProducer` per fare ciò, per esempio:
```
KinesisProducerConfiguration config = new KinesisProducerConfiguration()
.setRecordMaxBufferedTime(3000)
.setMaxConnections(1)
.setRequestTimeout(60000)
.setRegion("us-west-1");
final KinesisProducer kinesisProducer = new KinesisProducer(config);
```
Puoi anche caricare una configurazione da un file proprietà:
```
KinesisProducerConfiguration config = KinesisProducerConfiguration.fromPropertiesFile("default_config.properties");
```
Puoi sostituire qualsiasi percorso e nome di file al quale ha accesso il processo utente. Inoltre puoi chiamare metodi impostati sull'istanza `KinesisProducerConfiguration` creata in questo modo per personalizzare la configurazione.
Il file delle proprietà deve specificare i parametri usando i loro nomi in PascalCase. I nomi corrispondono a quelli utilizzati nei metodi impostati nella classe `KinesisProducerConfiguration`. Esempio:
```
RecordMaxBufferedTime = 100
MaxConnections = 4
RequestTimeout = 6000
Region = us-west-1
```
Per ulteriori informazioni sulle regole di utilizzo dei parametri di configurazione e sui limiti di valore, vedere il [file di esempio delle proprietà di configurazione su GitHub](https://github.com/awslabs/amazon-kinesis-producer/blob/master/java/amazon-kinesis-producer-sample/default_config.properties).
Nota che dopo che `KinesisProducer` è stato inizializzato, modificare l'istanza `KinesisProducerConfiguration` che è stata utilizzata non ha un effetto ulteriore. `KinesisProducer` non supporta al momento la riconfigurazione automatica.
# Implementa la deaggregazione dei consumatori
A partire dalla versione 1.4.0, la KCL supporta la disaggregazione automatica di record utente della KPL. Il codice dell'applicazione consumer scritto con versioni precedenti della KCL verrà compilato senza alcuna modifica dopo l'aggiornamento della KCL. Tuttavia, se l'aggregazione della KPL viene utilizzata nel lato producer, bisogna tenere conto di quanto segue riguardo i checkpoint: tutti i sottorecord in un record aggregato hanno lo stesso numero di sequenza, quindi i dati aggiuntivi devono essere memorizzati nel checkpoint se è necessario distinguere tra sottorecord. Questi dati supplementari vengono definiti come *numero sottosuccessione*.
**Topics**
+ [Esegui la migrazione dalle versioni precedenti di KCL](#kinesis-kpl-consumer-deaggregation-migration)
+ [Usa le estensioni KCL per la disaggregazione KPL](#kinesis-kpl-consumer-deaggregation-extensions)
+ [Usa direttamente GetRecords](#kinesis-kpl-consumer-deaggregation-getrecords)
## Esegui la migrazione dalle versioni precedenti di KCL
Non è necessario modificare le chiamate esistenti per eseguire il checkpoint con aggregazione. È comunque garantito che è possibile recuperare tutti i record archiviati nel flusso di dati Kinesis. Il KCL offre ora due nuove operazioni di checkpoint per supportare casi d'uso particolari, descritti di seguito.
Se il codice esistente è stato scritto per KCL prima del supporto KPL e l'operazione di checkpoint viene chiamata senza argomenti, equivale a controllare il numero di sequenza dell'ultimo record utente KPL del batch. Se l'operazione di checkpoint viene chiamata con una stringa di numero di sequenza, è equivalente all'esecuzione del checkpoint nel numero di sequenza del batch fornito assieme al numero di sottosuccessione 0 (zero).
Chiamare la nuova operazione di checkpoint della KCL `checkpoint()` senza alcun argomento è equivalente dal punto di vista semantico all'esecuzione di checkpoint nel numero di sequenza dell'ultima chiamata `Record` nel batch, assieme al numero di sottosuccessione implicito 0 (zero).
Chiamare la nuova operazione di checkpoint della KCL `checkpoint(Record record)` è equivalente dal punto di vista semantico all'esecuzione di checkpoint nel numero di sequenza del `Record` fornito, assieme al numero di sottosuccessione implicito 0 (zero). Se la chiamata `Record` è effettivamente un `UserRecord`, sul numero di sequenza `UserRecord` e sul numero di sottosuccessione viene eseguito il checkpoint.
Se si richiama la nuova operazione checkpoint della KCL `checkpoint(String sequenceNumber, long subSequenceNumber)` sul numero di sequenza assieme al numero fornito di sottosuccessione viene eseguito il checkpoint.
In questi casi, dopo che il checkpoint è stato memorizzato nella tabella di checkpoint di Amazon DynamoDB, la KCL può riprendere correttamente i record di recupero anche quando l'applicazione si interrompe e riavvia. Se più record sono contenuti nella sequenza, il recupero viene eseguito a partire dal prossimo record di numero di sottosuccessione nel record con la sequenza sulla quale è stato eseguito il checkpoint più recentemente. Se il checkpoint più recente includeva l'ultimo record di numero di sottosuccessione del precedente record di numero di sequenza, il recupero parte con il record con il prossimo numero di sequenza.
La sezione successiva illustra i dettagli del checkpoint di sequenza e sequenza per i consumatori, che devono evitare di saltare e duplicare i record. Se il salto (o duplicazione) di record quando interrompi e riavvii l'elaborazione del record del consumer non è importante, puoi eseguire il codice esistente senza alcuna modifica.
## Usa le estensioni KCL per la disaggregazione KPL
La disaggregazione KPL può comportare il checkpoint di sottosequenza. Per facilitare l'utilizzo del checkpoint della sottosuccessione, una classe `UserRecord` è stata aggiunta alla 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 */
}
}
```
Questa classe viene ora utilizzata invece di `Record`. Questo non interrompe il codice esistente perché è una sottoclasse di `Record`. La classe `UserRecord` rappresenta entrambi i sottorecord effettivi e i record standard, non aggregati. I record non aggregati non possono essere considerati come record aggregati con un solo sottorecord.
Inoltre, due operazioni nuove vengono aggiunte a `IRecordProcessorCheckpointer`:
```
public void checkpoint(Record record);
public void checkpoint(String sequenceNumber, long subSequenceNumber);
```
Per iniziare a utilizzare il checkpoint del numero di sottosuccessione, puoi eseguire la seguente conversione. Modifica il seguente codice di modulo:
```
checkpointer.checkpoint(record.getSequenceNumber());
```
Nuovo codice di modulo:
```
checkpointer.checkpoint(record);
```
È consigliabile utilizzare il modulo `checkpoint(Record record)` per il checkpoint della sottosuccessione. Tuttavia, se stai già memorizzando `sequenceNumbers` in stringhe da utilizzare per il checkpoint, devi anche memorizzare `subSequenceNumber`, come nell'esempio seguente:
```
String sequenceNumber = record.getSequenceNumber();
long subSequenceNumber = ((UserRecord) record).getSubSequenceNumber(); // ... do other processing
checkpointer.checkpoint(sequenceNumber, subSequenceNumber);
```
Il cast from to ha `UserRecord` sempre successo `Record` perché l'implementazione utilizza sempre. `UserRecord` Se non è necessario eseguire calcoli aritmetici sui numeri di sequenza, questo approccio non è consigliato.
Durante l'elaborazione dei record utente della KPL, la KCL scrive il numero di sottosequenza in Amazon DynamoDB come un campo extra per ogni riga. Le versioni precedenti della KCL hanno utilizzato `AFTER_SEQUENCE_NUMBER` per recuperare record durante la ripresa dei checkpoint. L'attuale KCL con il supporto KPL utilizza invece `AT_SEQUENCE_NUMBER`. Quando viene recuperato al numero di sequenza sul quale è stato eseguito il checkpoint, viene controllato il numero di sequenza sul quale è stato eseguito il checkpoint e i sottorecord vengono interrotti, in base alle esigenze (potenzialmente tutti se l'ultimo sottorecord è quello sul quale è stato eseguito il checkpoint). I record non aggregati possono essere considerati come record non aggregati con un sottorecord singolo, perciò lo stesso algoritmo funziona sia per i record aggregati sia non aggregati.
## Usa direttamente GetRecords
Puoi anche scegliere di non utilizzare la KCL, ma invece richiamare l'operazione API `GetRecords` direttamente per recuperare i record del flusso di dati Kinesis. Per decomprimere questi record recuperati nei record utente della KPL originali, richiama una delle seguenti operazioni statiche in `UserRecord.java`:
```
public static List deaggregate(List records)
public static List deaggregate(List records, BigInteger startingHashKey, BigInteger endingHashKey)
```
La prima operazione utilizza il valore predefinito `0` (zero) per `startingHashKey` e il valore predefinito `2^128 -1` per `endingHashKey`.
Ognuna di queste operazioni disaggrega l'elenco fornito di record del flusso di dati Kinesis in un elenco di record utente della KPL. Qualsiasi record utente KPL la cui chiave hash esplicita o chiave di partizione non rientra nell'intervallo di `startingHashKey` (incluso) e `endingHashKey`(incluso) viene eliminato dalla lista dei record restituiti.
# Usa KPL con Amazon Data Firehose
Se utilizzi la Kinesis Producer Library (KPL) per scrivere i dati su un flusso di dati Kinesis, puoi utilizzare l'aggregazione per abbinare i record che scrivi al flusso di dati Kinesis. Se poi utilizzate quel flusso di dati come fonte per il flusso di distribuzione Firehose, Firehose disaggrega i record prima di consegnarli alla destinazione. Se configuri il flusso di distribuzione per trasformare i dati, Firehose disaggrega i record prima di inviarli a. AWS Lambda Per ulteriori informazioni, consulta [Scrittura su Amazon Firehose tramite il flusso di dati Kinesis](https://docs.aws.amazon.com/firehose/latest/dev/writing-with-kinesis-streams.html).
# Utilizzate il KPL con lo Schema Registry AWS Glue
Puoi integrare i tuoi flussi di dati Kinesis con lo Schema Registry. AWS Glue Lo AWS Glue Schema Registry ti consente di scoprire, controllare ed evolvere centralmente gli schemi, garantendo al contempo che i dati prodotti siano convalidati continuamente da uno schema registrato. Uno schema definisce la struttura e il formato di un registro di dati. Uno schema è una specifica con versioni per la pubblicazione, il consumo o l'archiviazione dei dati in modo affidabile. Lo AWS Glue Schema Registry consente di migliorare la qualità e la governance end-to-end dei dati all'interno delle applicazioni di streaming. Per ulteriori informazioni, consulta [Registro degli schemi di AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html). Uno dei modi per configurare questa integrazione è utilizzare le librerie KPL e Kinesis Client Library (KCL) in Java.
**Importante**
Attualmente, l'integrazione di Kinesis Data AWS Glue Streams e del registro dello schema è supportata solo per i flussi di dati Kinesis che utilizzano produttori KPL implementati in Java. Il supporto multilingue non viene fornito.
Per istruzioni dettagliate su come configurare l'integrazione di Kinesis Data Streams con Schema Registry utilizzando KPL, consulta la [sezione «Interazione con i dati KPL/KCL utilizzando le librerie» in Caso d'uso: integrazione di Amazon Kinesis Data Streams](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-integrations.html#schema-registry-integrations-kds) con il registro dello schema Glue. AWS
# Configura la configurazione del proxy KPL
Per le applicazioni che non possono connettersi direttamente a Internet, tutti i client AWS SDK supportano l'uso di proxy HTTP o HTTPS. In un ambiente aziendale tipico, tutto il traffico di rete in uscita deve passare attraverso server proxy. Se l'applicazione utilizza Kinesis Producer Library (KPL) per raccogliere e inviare dati AWS in un ambiente che utilizza server proxy, l'applicazione richiederà la configurazione del proxy KPL. KPL è una libreria di alto livello basata sull'SDK AWS Kinesis. È suddivisa in un processo nativo e un wrapper. Il processo nativo esegue tutti i processi di elaborazione e invio dei record, mentre il wrapper gestisce il processo nativo e comunica con esso. Per ulteriori informazioni, consulta [Implementazione di producer efficienti e affidabili con la Amazon Kinesis Producer Library](https://aws.amazon.com/blogs/big-data/implementing-efficient-and-reliable-producers-with-the-amazon-kinesis-producer-library/).
Il wrapper è scritto in Java e il processo nativo è scritto in C\$1\$1 con l'uso dell'SDK Kinesis. La versione 0.14.7 e successive della KPL ora supportano la configurazione proxy nel wrapper Java, che può passare tutte le configurazioni proxy al processo nativo. [Per ulteriori informazioni, consulta https://github.com/awslabs/amazon-kinesis-producer/0.14.7. releases/tag/v](https://github.com/awslabs/amazon-kinesis-producer/releases/tag/v0.14.7)
Puoi utilizzare il codice seguente per aggiungere configurazioni proxy alle applicazioni 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);
```
# Politica del ciclo di vita della versione KPL
Questo argomento descrive la politica del ciclo di vita delle versioni per Amazon Kinesis Producer Library (KPL). AWS fornisce regolarmente nuove versioni per le versioni KPL per supportare nuove funzionalità e miglioramenti, correzioni di bug, patch di sicurezza e aggiornamenti delle dipendenze. Ti consigliamo di rimanere up-to-date con le versioni KPL per stare al passo con le funzionalità più recenti, gli aggiornamenti di sicurezza e le dipendenze sottostanti. **Non** consigliamo l'uso continuato di una versione KPL non supportata.
Il ciclo di vita delle principali versioni KPL è costituito dalle tre fasi seguenti:
+ **Disponibilità generale (GA)**: durante questa fase, la versione principale è completamente supportata. AWS fornisce regolarmente versioni secondarie e patch che includono il supporto per nuove funzionalità o aggiornamenti delle API per Kinesis Data Streams, oltre a correzioni di bug e sicurezza.
+ **Modalità di manutenzione**: AWS limita il rilascio delle versioni delle patch per risolvere solo le correzioni di bug critici e i problemi di sicurezza. La versione principale non riceverà aggiornamenti per le nuove funzionalità o APIs per Kinesis Data Streams.
+ **E nd-of-support** — La versione principale non riceverà più aggiornamenti o versioni. Le versioni pubblicate in precedenza continueranno a essere disponibili tramite gestori di pacchetti pubblici e il codice rimarrà attivo GitHub. L'uso di una versione raggiunta end-of-support viene effettuato a discrezione dell'utente. Ti consigliamo di eseguire l'aggiornamento alla versione principale più recente.
| Versione principale | Fase attuale | Data di rilascio | Data della modalità di manutenzione | End-of-support data |
| --- | --- | --- | --- | --- |
| KPL 0.x | modalità di manutenzione | 2015-06-02 | 2025-04-17 | 2026-01-30 |
| KPL 1.x | Disponibilità generale | 2024-12-15 | -- | -- |