As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Desenvolver produtores usando a Amazon Kinesis Producer Library (KPL)
Um produtor do Amazon Kinesis Data Streams é uma aplicação que coloca registros de dados de usuários em um fluxo de dados do Kinesis (o que também é chamado de *ingestão de dados*). A Amazon Kinesis Producer Library (KPL) simplifica o desenvolvimento de aplicações de produção, permitindo que os desenvolvedores atinjam alto throughput de gravação para um fluxo de dados do Kinesis.
Você pode monitorar o KPL com a Amazon CloudWatch. Para obter mais informações, consulte [Monitore a Kinesis Producer Library com a Amazon CloudWatch](monitoring-with-kpl.md).
**Topics**
+ [Analisar a função da KPL](#developing-producers-with-kpl-role)
+ [Perceber as vantagens de usar a KPL](#developing-producers-with-kpl-advantage)
+ [Entender quando não usar a KPL](#developing-producers-with-kpl-when)
+ [Instalar a KPL](kinesis-kpl-dl-install.md)
+ [Migrar da KPL 0.x para a KPL 1.x](kpl-migration-1x.md)
+ [Transição para certificados Amazon Trust Services (ATS) para a KPL](kinesis-kpl-upgrades.md)
+ [Plataformas compatíveis com a KPL](kinesis-kpl-supported-plats.md)
+ [Principais conceitos da KPL](kinesis-kpl-concepts.md)
+ [Integrar a KPL com o código de produtor](kinesis-kpl-integration.md)
+ [Gravar no fluxo de dados do Kinesis usando a KPL](kinesis-kpl-writing.md)
+ [Configurar a Amazon Kinesis Producer Library](kinesis-kpl-config.md)
+ [Implementar a desagregação de consumidores](kinesis-kpl-consumer-deaggregation.md)
+ [Usar a KPL com o Amazon Data Firehose](kpl-with-firehose.md)
+ [Use o KPL com o Registro do AWS Glue Esquema](kpl-with-schemaregistry.md)
+ [Definir a configuração do proxy da KPL](kpl-proxy-configuration.md)
+ [Política de ciclo de vida da versão da KPL](kpl-version-lifecycle-policy.md)
**nota**
Recomendamos a atualização para a versão mais recente da KPL. A KPL é atualizada regularmente em versões que incluem os patches de dependência e segurança e as correções de bugs mais recentes, além de novos recursos compatíveis com versões anteriores. Para obter mais informações, consulte [https://github.com/awslabs/amazon-kinesis-producer/releases/](https://github.com/awslabs/amazon-kinesis-producer/releases/).
## Analisar a função da KPL
A KPL é uma easy-to-use biblioteca altamente configurável que ajuda você a gravar em um stream de dados do Kinesis. Ela atua como um intermediário entre o código da aplicação de produção e as ações das APIs do Kinesis Data Streams. A KPL executa as seguintes tarefas principais:
+ Grava em um ou mais fluxos de dados do Kinesis com um mecanismo automático e configurável de novas tentativas
+ Coleta registros e usa `PutRecords` para gravar vários registros em vários fragmentos por solicitação
+ Agrega registros de usuário para aumentar o tamanho da carga útil e melhorar o throughput
+ Integra-se perfeitamente à [Kinesis Client Library](https://docs.aws.amazon.com/kinesis/latest/dev/developing-consumers-with-kcl.html) (KCL) para desagregar registros em lote no consumidor
+ Envia CloudWatch métricas da Amazon em seu nome para fornecer visibilidade sobre o desempenho do produtor
Observe que o KPL é diferente da API Kinesis Data Streams que está disponível no. [AWS SDKs](https://aws.amazon.com/tools/) A API do Kinesis Data Streams ajuda a gerenciar vários aspectos do Kinesis Data Streams (incluindo a criação de fluxos, a refragmentação e a colocação e obtenção de registros), enquanto a KPL fornece uma camada de abstração especificamente para a ingestão de dados. Para obter informações sobre a API do Kinesis Data Streams, consulte a [Referência de APIs do Amazon Kinesis](https://docs.aws.amazon.com/kinesis/latest/APIReference/).
## Perceber as vantagens de usar a KPL
A lista a seguir apresenta algumas das principais vantagens no uso da KPL para desenvolver produtores do Kinesis Data Streams.
A KPL pode ser usada em casos de uso síncronos ou assíncronos. Recomenda-se a interface assíncrona, que possui maior desempenho, a menos que haja um motivo específico para usar o comportamento síncrono. Para obter mais informações sobre esses dois casos de uso e o código de exemplo, consulte [Gravar no fluxo de dados do Kinesis usando a KPL](kinesis-kpl-writing.md).
**Benefícios de desempenho**
A KPL pode ajudar a criar produtores de alta performance. Considere uma situação em que suas instâncias do Amazon EC2 atuam como proxy para coletar eventos de 100 bytes de centenas ou milhares de dispositivos de baixa potência e gravar registros em um fluxo de dados do Kinesis. Cada instância do EC2 precisa gravar milhares de eventos por segundo no fluxo de dados. Para alcançar o throughput necessário, os produtores precisam implementar uma lógica complexa, como agrupamento em lotes ou multithreading, lógica de retentativa e desagregação de registros no lado do consumidor. A KPL executa todas essas tarefas.
**Facilidade de uso do lado do consumidor**
No caso de desenvolvedores no lado do consumidor usando a KCL em Java, a integração da KPL não requer esforço adicional. Ao recuperar um registro agregado do Kinesis Data Streams que consiste em vários registros de usuário da KPL, a KCL chama automaticamente a KPL para extrair registros do usuário individual e retorná-los ao mesmo usuário.
Desenvolvedores no lado do conusmidor que não usam a KCL, mas usam a operação `GetRecords` da API diretamente, contam com uma biblioteca de Java da KPL disponível para extrair registros do usuário individual e retorná-los ao mesmo usuário.
**Monitoramento de produtor**
Você pode coletar, monitorar e analisar seus produtores do Kinesis Data Streams usando a CloudWatch Amazon e a KPL. O KPL emite taxa de transferência, erro e outras métricas CloudWatch em seu nome e é configurável para ser monitorado no nível de stream, fragmento ou produtor.
**Arquitetura assíncrona**
Como pode armazenar registros em buffer antes de enviá-los ao Kinesis Data Streams, a KPL não força a aplicação chamadora a bloquear e aguardar confirmação de que o registro chegou ao servidor antes de continuar o runtime. Uma chamada para colocar um registro na KPL sempre retorna imediatamente, sem esperar o registro ser enviado ou uma resposta ser recebida do servidor. Em vez disso, é criado um objeto `Future` que posteriormente recebe o resultado do envio do registro ao Kinesis Data Streams. Esse é o mesmo comportamento dos clientes assíncronos no SDK. AWS
## Entender quando não usar a KPL
A KPL pode ter um atraso por processamento adicional de até `RecordMaxBufferedTime` dentro da biblioteca (configurável pelo usuário). Valores maiores que `RecordMaxBufferedTime` geram maiores eficiências de empacotamento e melhor desempenho. Aplicações que não toleram esse atraso adicional podem precisar usar o SDK da AWS diretamente. Para obter mais informações sobre como usar o AWS SDK com o Kinesis Data Streams, consulte. [Desenvolva produtores usando a API Amazon Kinesis Data Streams com o AWS SDK para Java](developing-producers-with-sdk.md) Para obter mais informações sobre `RecordMaxBufferedTime` e outras propriedades configuráveis pelo usuário da KPL, consulte [Configurar a Amazon Kinesis Producer Library](kinesis-kpl-config.md).
# Instalar a KPL
A Amazon fornece binários pré-compilados da Amazon Kinesis Producer Library (KPL) de C\$1\$1 para macOS, Windows e distribuições recentes do Linux (para obter detalhes das plataformas com suporte, consulte a próxima seção). Esses binários, empacotados como parte dos arquivos .jar do Java, são invocados e usados automaticamente ao usar o Maven para instalar o pacote. Para localizar as versões mais recentes da KPL e da KCL, use os seguintes links de pesquisa do Maven:
+ [KPL](https://search.maven.org/#search|ga|1|amazon-kinesis-producer)
+ [KCL](https://search.maven.org/#search|ga|1|amazon-kinesis-client)
O binários do Linux foram compilados com GNU Compiler Collection (GCC) e vinculados estaticamente à libstdc\$1\$1 no Linux. Espera-se que eles funcionem em qualquer distribuição do Linux de 64 bits que inclua um glibc versão 2.5 ou superior.
Usuários de distribuições Linux anteriores podem criar o KPL usando as instruções de compilação fornecidas junto com o código-fonte ativado. GitHub Para baixar o KPL de GitHub, consulte a [Amazon Kinesis](https://github.com/awslabs/amazon-kinesis-producer) Producer Library.
**Importante**
A Amazon Kinesis Producer Library (KPL) 0.x chegará em 30 de end-of-support janeiro de 2026. É **altamente recomendável** que você migre suas aplicações da KPL que usam a versão 0.x para a versão mais recente da KPL antes de 30 de janeiro de 2026. Para saber a versão mais recente da KPL, consulte a [página da KPL no Github](https://github.com/awslabs/amazon-kinesis-producer). Para ter mais informações sobre como migrar da KPL 0.x para a KPL 1.x, consulte [Migrar da KPL 0.x para a KPL 1.x](kpl-migration-1x.md).
# Migrar da KPL 0.x para a KPL 1.x
Este tópico fornece step-by-step instruções para migrar seu consumidor do KPL 0.x para o KPL 1.x. O KPL 1.x introduz suporte para o AWS SDK para Java 2.x, mantendo a compatibilidade da interface com as versões anteriores. Não é necessário atualizar sua lógica de processamento dos dados principais para migrar para a KPL 1.x.
1. **É necessário atender aos seguintes pré-requisitos:**
+ Java Development Kit (JDK) 8 ou posterior
+ AWS SDK para Java 2. x
+ Maven ou Gradle para gerenciamento de dependências
1. **Adicionar dependências**
Se estiver usando Maven, adicione a dependência a seguir ao arquivo pom.xml. Atualize groupid de `com.amazonaws` para `software.amazon.kinesis` e a versão `1.x.x` para a versão mais recente da KPL.
```
software.amazon.kinesis
amazon-kinesis-producer
1.x.x
```
Se você estiver usando Gradle, adicione o seguinte ao seu arquivo `build.gradle`. Substitua `1.x.x` pela versão mais recente da KPL.
```
implementation 'software.amazon.kinesis:amazon-kinesis-producer:1.x.x'
```
A versão mais recente da KPL pode ser obtida no [Repositório central do Maven](https://central.sonatype.com/search?q=amazon-kinesis-producer).
1. **Atualizar as instruções de importação para a KPL**
O KPL 1.x usa o AWS SDK para Java 2.x e usa um nome de pacote atualizado que começa com`software.amazon.kinesis`, em comparação com o nome do pacote no KPL anterior que começa com. `com.amazonaws.services.kinesis`
Substitua a importação de `com.amazonaws.services.kinesis` por `software.amazon.kinesis`. A tabela a seguir relaciona as importações que precisam ser substituídas.
**Substituições de importações**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/streams/latest/dev/kpl-migration-1x.html)
1. **Atualizar declarações de importação para classes de provedores AWS de credenciais**
Ao migrar para o KPL 1.x, você deve atualizar pacotes e classes em suas importações no código do aplicativo KPL que são baseados no AWS SDK para Java 1.x para os correspondentes com base no 2.x. AWS SDK para Java As importações comuns na aplicação KPL são classes de provedores de credenciais. Consulte [Alterações no provedor de credenciais](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-client-credentials.html) na documentação do guia de migração AWS SDK para Java 2.x para ver a lista completa de alterações no provedor de credenciais. Aqui está a alteração comum de importação que talvez você precise fazer em suas aplicações KPL.
**Importação na KPL 0.x**
```
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
```
**Importação na KPL 1.x**
```
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
```
Se você importar outros provedores de credenciais com base no AWS SDK para Java 1.x, deverá atualizá-los para os equivalentes ao AWS SDK para Java 2.x. Se você não importou nada classes/packages do AWS SDK para Java 1.x, pode ignorar essa etapa.
1. **Atualize a configuração do provedor de credenciais na configuração da KPL**
A configuração do provedor de credenciais na KPL 1.x requer os provedores de credenciais do AWS SDK para Java 2.x. Se você estiver passando provedores de credenciais para o AWS SDK para Java 1.x no `KinesisProducerConfiguration` substituindo o provedor de credenciais padrão, você deverá atualizá-lo com os AWS SDK para Java provedores de credenciais 2.x. Consulte [Alterações no provedor de credenciais](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-client-credentials.html) na documentação do guia de migração AWS SDK para Java 2.x para ver a lista completa de alterações no provedor de credenciais. Se não substituiu o provedor de credenciais padrão na configuração da KPL, você pode ignorar essa etapa.
Por exemplo, se você estiver substituindo o provedor de credenciais padrão da KPL com o seguinte código:
```
KinesisProducerConfiguration config = new KinesisProducerConfiguration();
// SDK v1 default credentials provider
config.setCredentialsProvider(new DefaultAWSCredentialsProviderChain());
```
É necessário atualizá-lo com o código a seguir para usar o provedor de credenciais do AWS SDK para Java 2.x:
```
KinesisProducerConfiguration config = new KinesisProducerConfiguration();
// New SDK v2 default credentials provider
config.setCredentialsProvider(DefaultCredentialsProvider.create());
```
# Transição para certificados Amazon Trust Services (ATS) para a KPL
Em 9 de fevereiro de 2018, às 9:00, horário do Pacífico, o Amazon Kinesis Data Streams instalou os certificados do ATS. Para poder continuar a gravar registros no Kinesis Data Streams usando a Amazon Kinesis Producer Library (KPL), é necessário atualizar a instalação da KPL para a [versão 0.12.6](http://search.maven.org/#artifactdetails|com.amazonaws|amazon-kinesis-producer|0.12.6|jar) ou posterior. Essa mudança afeta todas as AWS regiões.
Para obter informações sobre a mudança para o ATS, consulte [Como se preparar para AWS a mudança para sua própria autoridade de certificação](https://aws.amazon.com/blogs/security/how-to-prepare-for-aws-move-to-its-own-certificate-authority/).
Se encontrar problemas e precisar de suporte técnico, [abra um caso](https://console.aws.amazon.com/support/v1#/case/create) na central de suporte da AWS .
# Plataformas compatíveis com a KPL
A Amazon Kinesis Producer Library (KPL) é escrita em C\$1\$1 e executada como um processo secundário do processo principal do usuário. Binários nativos pré-compilados de 64 bits são fornecidos com a versão do Java e gerenciados pelo wrapper Java.
O pacote Java é executado sem a necessidade de instalar qualquer biblioteca adicional nos seguintes sistemas operacionais:
+ Distribuições do Linux com kernel 2.6.18 (setembro de 2006) e posterior
+ Apple iOS X 10.9 e posterior
+ Windows Server 2008 e posterior
**Importante**
O Windows Server 2008 e posterior é compatível com todas as versões do KPL até a versão 0.14.0.
A plataforma Windows NÃO é compatível a partir da versão KPL 0.14.0 ou superior.
Observe que a KPL é de 64 bits apenas.
## Código-fonte
Se os binários fornecidos na instalação da KPL não forem suficientes para seu ambiente, o núcleo da KPL é escrito como um módulo C\$1\$1. O código-fonte do módulo C\$1\$1 e da interface Java é lançado sob a Amazon Public License e está disponível GitHub na [Amazon Kinesis](https://github.com/awslabs/amazon-kinesis-producer) Producer Library. Embora seja possível usar a KPL em qualquer plataforma para a qual haja disponibilidade de JRE e um compilador C\$1\$1 compatível com padrões recentes, a Amazon não oferece suporte oficial a nenhuma plataforma que não esteja na lista de plataformas compatíveis.
# Principais conceitos da KPL
As seções a seguir contêm os conceitos e a terminologia necessários para entender e aproveitar a Amazon Kinesis Producer Library (KPL).
**Topics**
+ [Registros](#kinesis-kpl-concepts-records)
+ [Agrupamento em lotes](#kinesis-kpl-concepts-batching)
+ [Agregação](#kinesis-kpl-concepts-aggretation)
+ [Coleta](#kinesis-kpl-concepts-collection)
## Registros
Neste guia, há uma distinção entre *registros de usuário da KPL* e *registros do Kinesis Data Streams*. O termo *registro* sem um qualificador refere-se a um *registro de usuário da KPL*. Um registro do Kinesis Data Streams será explicitamente chamado de *registro do Kinesis Data Streams*.
Um registro de usuário da KPL é um blob de dados com um significado específico para o usuário. Os exemplos incluem um blob JSON que representa um evento de interface do usuário em um site ou uma entrada de log proveniente de um servidor da web.
Um registro do Kinesis Data Streams é uma instância da estrutura de dados de `Record` definida pela API do serviço Kinesis Data Streams. Ele contém uma chave de partição, um número sequencial e um blob de dados.
## Agrupamento em lotes
*Envio em lotes* refere-se à execução de uma única ação em vários itens, em vez de executar a ação repetidamente em cada item.
Nesse contexto, o “item” é um registro, e a ação é seu envio ao Kinesis Data Streams. Em uma situação sem envio em lotes, cada registro é colocado em um registro separado do Kinesis Data Streams e faz uma única solicitação HTTP para enviá-lo ao Kinesis Data Streams. Com o agrupamento em lotes, cada solicitação HTTP pode carregar vários registros, em vez de apenas um.
A KPL aceita dois tipos de agrupamento em lotes:
+ *Agregação*: armazenamento de vários registros em um único registro do Kinesis Data Streams.
+ *Coleta*: uso da operação `PutRecords` da API para enviar vários registros do Kinesis Data Streams a um ou mais fragmentos no fluxo de dados do Kinesis.
Os dois tipos de agrupamento em lotes da KPL são projetados para coexistir e podem ser ativados ou desativados de forma independente. Por padrão, ambos são ativados.
## Agregação
A *agregação* refere-se ao armazenamento de vários registros em um registro do Kinesis Data Streams. A agregação permite que os clientes aumentem o número de registros enviados por chamada de API, o que aumenta efetivamente o throughput do produtor.
Os fragmentos do Kinesis Data Streams oferecem suporte a até 1.000 registros do Kinesis Data Streams por segundo, ou um throughput de 1 MB. O limite de registros por segundo do Kinesis Data Streams restringe clientes com registros menores que 1 KB. A agregação de registros permite aos clientes combinar vários registros em um único registro do Kinesis Data Streams. Isso permite que os clientes melhorem o próprio throughput por fragmento.
Considere o caso de um fragmento na região us-east-1 que está atualmente em execução à taxa constante de 1.000 registros por segundo, com registros de 512 bytes cada. Com a agregação da KPL, é possível empacotar 1.000 registros em apenas 10 registros do Kinesis Data Streams reduzindo o número de registros por segundo para 10 (a 50 KB cada).
## Coleta
*Coleta* refere-se ao agrupamento de vários registros do Kinesis Data Streams em um lote, que é enviado em uma única solicitação HTTP com uma chamada à operação `PutRecords` da API, em vez de enviar cada registro do Kinesis Data Streams em uma solicitação HTTP própria.
Isso aumenta o throughput em comparação com a não utilização de coleções, pois reduz a sobrecarga de fazer muitas solicitações HTTP separadas. Na verdade, `PutRecords`, por si só, foi projetado especificamente para essa finalidade.
A coleta difere da agregação porque opera com grupos de registros do Kinesis Data Streams. Os registros do Kinesis Data Streams coletados ainda podem conter vários registros do usuário. O relacionamento pode ser visualizado da seguinte maneira:
```
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 a KPL com o código de produtor
A Amazon Kinesis Producer Library (KPL) é executada em um processo separado e se comunica com o processo principal do usuário usando IPC. Essa arquitetura, às vezes chamada de [microsserviço](http://en.wikipedia.org/wiki/Microservices), é escolhida por dois motivos principais:
**1) O processo do usuário não falhará mesmo que a KPL falhe**
O processo pode ter tarefas não relacionadas ao Kinesis Data Streams e continuar em operação mesmo que a KPL falhe. Além disso, o processo de usuário pai pode reiniciar a KPL e recuperar um estado totalmente funcional (essa funcionalidade está nos wrappers oficiais).
Um exemplo é um servidor Web que envia métricas ao Kinesis Data Streams. O servidor pode continuar entregando páginas mesmo que a parte do Kinesis Data Streams tenha parado de funcionar. Portanto, causar uma falha em todo o servidor devido a um erro na KPL seria uma interrupção desnecessária.
**2) Clientes arbitrários podem ser aceitos**
Há sempre clientes que usam linguagens diferentes das oficialmente aceitas. Esses clientes também devem ser capazes de usar a KPL facilmente.
## Matriz de uso recomendado
A matriz de uso a seguir lista as configurações recomendadas para diferentes usuários e indica se e como a KPL deve ser usada. Lembre-se de que, se a agregação estiver habilitada, será preciso usar a desagregação para extrair seus registros no lado do consumidor.
| Linguagem do lado do produtor | Linguagem do lado do consumidor | Versão da KCL | Lógica do ponto de verificação | A KPL pode ser usada? | Advertências |
| --- | --- | --- | --- | --- | --- |
| Tudo menos Java | \$1 | \$1 | \$1 | Não | N/D |
| Java | Java | Usa o Java SDK diretamente | N/D | Sim | Se a agregação for usada, será necessário usar a biblioteca de desagregação fornecida após as chamadas a GetRecords. |
| Java | Tudo menos Java | Usa o SDK diretamente | N/D | Sim | É preciso desabilitar a agregação. |
| Java | Java | 1.3.x | N/D | Sim | É preciso desabilitar a agregação. |
| Java | Java | 1.4.x | Chama o ponto de verificação sem nenhum argumento | Sim | Nenhum |
| Java | Java | 1.4.x | Chama o ponto de verificação com um número sequencial explícito | Sim | Desative a agregação ou altere o código para usar números sequenciais estendidos para definir pontos de verificação. |
| Java | Tudo menos Java | 1.3.x \$1 daemon de várias linguagens \$1 wrapper específico de linguagem | N/D | Sim | É preciso desabilitar a agregação. |
# Gravar no fluxo de dados do Kinesis usando a KPL
As seções a seguir mostram o código de exemplo em uma progressão desde o produtor mais básico até o código totalmente assíncrono.
## Código barebone de produtor
O código a seguir é todo o necessário para escrever um produtor minimamente funcional. Os registros de usuário da Amazon Kinesis Producer Library (KPL) são processados em 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 aos resultados de forma síncrona
No exemplo anterior, o código não verificou se os registros do usuário da KPL foram bem-sucedidos. A KPL faz todas as novas tentativas necessárias para dar conta das falhas. No entanto, para verificar os resultados, é possível utilizar os objetos `Future` que são retornados de `addUserRecord`, como no exemplo a seguir (exemplo anterior mostrado para fins de 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 aos resultados de forma assíncrona
O exemplo anterior está chamando `get()` em um objeto `Future`, o que bloqueia o runtime. Se não quiser bloquear o runtime, você pode usar callback assíncrono, como mostrado no exemplo a seguir:
```
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 a Amazon Kinesis Producer Library
Embora as configurações padrão devam funcionar bem para a maioria dos casos de uso, talvez convenha alterar algumas configurações padrão para ajustar o comportamento do `KinesisProducer` às suas necessidades. Para isso, uma instância da classe `KinesisProducerConfiguration` pode ser passada ao construtor `KinesisProducer`, por exemplo:
```
KinesisProducerConfiguration config = new KinesisProducerConfiguration()
.setRecordMaxBufferedTime(3000)
.setMaxConnections(1)
.setRequestTimeout(60000)
.setRegion("us-west-1");
final KinesisProducer kinesisProducer = new KinesisProducer(config);
```
Também é possível pode carregar uma configuração de um arquivo de propriedades:
```
KinesisProducerConfiguration config = KinesisProducerConfiguration.fromPropertiesFile("default_config.properties");
```
É possível substituir qualquer caminho e nome de arquivo a que o processo de usuário tem acesso. Também é possível chamar métodos definidos para a instância de `KinesisProducerConfiguration` criada dessa forma para personalizar a configuração.
O arquivo de propriedades deve especificar parâmetros usando seus nomes em PascalCase. Os nomes correspondem aos usados nos métodos definidos na classe `KinesisProducerConfiguration`. Por exemplo:
```
RecordMaxBufferedTime = 100
MaxConnections = 4
RequestTimeout = 6000
Region = us-west-1
```
Para obter mais informações sobre regras de uso de parâmetros de configuração e limites de valor, consulte o [arquivo de exemplo de propriedades de configuração em GitHub](https://github.com/awslabs/amazon-kinesis-producer/blob/master/java/amazon-kinesis-producer-sample/default_config.properties).
Observe que, depois que o `KinesisProducer` é inicializado, alterar a instância de `KinesisProducerConfiguration` que foi usada não tem mais efeito. No momento, o `KinesisProducer` não oferece suporte à reconfiguração dinâmica.
# Implementar a desagregação de consumidores
A partir da versão 1.4.0, a KCL oferece suporte à desagregação automática dos registros de usuário da KPL. O código da aplicação de consumo escrito com versões anteriores da KCL será compilado sem qualquer modificação após a atualziação da KCL. No entanto, se a agregação da KPL estiver sendo usada no lado do produtor, haverá uma sutileza envolvendo a definição de pontos de verificação: como todos os sub-registros dentro de um registro agregado têm o mesmo número de sequência, os dados adicionais precisarão ser armazenados com o ponto de verificação, se for preciso distinguir os sub-registros. Esses dados adicionais são chamados de *números de subsequência*.
**Topics**
+ [Migrar de versões anteriores da KCL](#kinesis-kpl-consumer-deaggregation-migration)
+ [Usar extensões da KCL para desagregação da KPL](#kinesis-kpl-consumer-deaggregation-extensions)
+ [Use GetRecords diretamente](#kinesis-kpl-consumer-deaggregation-getrecords)
## Migrar de versões anteriores da KCL
Não é necessário alterar as chamadas existentes para que definam pontos de verificação com a agregação. A recuperação bem-sucedida de todos os registros armazenados no Kinesis Data Streams ainda é garantida. A KCL agora oferece duas novas operações de ponto de verificação para suporte a casos de uso específicos, descritos abaixo.
Caso seu código existente tenha sido escrito para uma versão da KCL anterior ao suporte à KPL e a operação de ponto de verificação seja chamada sem argumentos, isso será equivalente a definir o ponto de verificação do número de sequência do último registro de usuário da KPL no lote. Se a operação de ponto de verificação é chamada com uma string de número sequencial, isso equivale a definir o ponto de verificação do número sequencial do lote conhecido junto com o número 0 (zero) da subsequência implícita.
Chamar a nova operação de ponto de verificação `checkpoint()` da KCL sem argumentos é semanticamente equivalente a definir o ponto de verificação do número de sequência da última chamada a `Record` no lote com o número 0 (zero) de subsequência implícito.
Chamar a nova operação de ponto de verificação `checkpoint(Record record)` da KCL é semanticamente equivalente a definir o ponto de verificação do número de sequência do `Record` conhecido com o número 0 (zero) de subsequência implícito. Se a chamada a `Record` é na verdade um `UserRecord`, o número de sequencial e subsequencial de `UserRecord` será definido.
Chamar a nova operação de ponto de verificação `checkpoint(String sequenceNumber, long subSequenceNumber)` da KCL explicitamente define o ponto de verificação do número de sequência conhecido com o número de subsequência conhecido.
Em qualquer desses casos, depois que o ponto de verificação é armazenado na tabela de pontos de verificação do Amazon DynamoDB, a KCL pode retomar corretamente a recuperação de registros, mesmo quando a aplicação falha e reinicia. Se houver mais registros contidos na sequência, a recuperação ocorrerá a partir do próximo registro de número subsequencial dentro do registro com o número sequencial cujo ponto de verificação foi definido mais recentemente. Se o ponto de verificação mais recente inclui o último número subsequencial do registro de número sequencial anterior, a recuperação ocorrerá a partir do registro com o próximo número sequencial.
A próxima seção discute detalhes de definição do ponto de verificação de sequência e subsequência para consumidores que precisam evitar a omissão e a duplicação de registros. Se a omissão (ou duplicação) de registros ao parar e reiniciar o processamento de registros do consumidor não é importante, é possível executar seu código existente sem modificação.
## Usar extensões da KCL para desagregação da KPL
A desagregação da KPL pode envolver a definição de um ponto de verificação de subsequência. Para facilitar a definição do ponto de verificação de subsequência, uma classe `UserRecord` foi adicionada à 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 */
}
}
```
Essa classe agora é usada em vez de `Record`. Ela não interrompe o código existente por ser uma subclasse de `Record`. A classe `UserRecord` representa os sub-registros reais e os registros padrão não agregados. Os registros não agregados podem ser considerados como registros agregadas com exatamente um sub-registro.
Além disso, duas operações novas são adicionadas a `IRecordProcessorCheckpointer`:
```
public void checkpoint(Record record);
public void checkpoint(String sequenceNumber, long subSequenceNumber);
```
Para começar a usar a definição de ponto de verificação de número subsequencial, é possível executar a seguinte conversão. Altere o seguinte código de formulário:
```
checkpointer.checkpoint(record.getSequenceNumber());
```
Novo código de formulário:
```
checkpointer.checkpoint(record);
```
Recomendamos usar o formulário `checkpoint(Record record)` para definição de ponto de verificação de subsequência. No entanto, se `sequenceNumbers` já estiverem sendo armazenados em strings para usar na definição de pontos de verificação, agora deve-se também armazenar `subSequenceNumber`, como mostrado no exemplo a seguir:
```
String sequenceNumber = record.getSequenceNumber();
long subSequenceNumber = ((UserRecord) record).getSubSequenceNumber(); // ... do other processing
checkpointer.checkpoint(sequenceNumber, subSequenceNumber);
```
A transmissão de `Record` para `UserRecord` sempre é bem-sucedida porque a implementação sempre usa `UserRecord`. A menos que haja uma necessidade de executar aritmética nos números sequenciais, essa abordagem não é recomendada.
Durante o processamento de registros de usuário da KPL, a KCL grava o número de subsequência no Amazon DynamoDB como um campo extra para cada linha. As versões anteriores da KCL usavam `AFTER_SEQUENCE_NUMBER` para obter registros ao retomar os pontos de verificação. Em vez disso, a KCL atual com suporte à KPL, usa `AT_SEQUENCE_NUMBER`. Quando é recuperado o registro no número sequencial para o qual foi definido o ponto de verificação, esse número é verificado e os sub-registros são descartados conforme apropriado (que podem ser todos eles, se o último sub-registro é aquele verificado). Novamente, os registros não agregados podem ser considerados como registros agregados com um único sub-registro. Portanto, o mesmo algoritmo funciona para os registros agregados e não agregados.
## Use GetRecords diretamente
Em vez de usar a KCL, pode-se optar por invocar a operação de API `GetRecords` diretamente para recuperar os registros do Kinesis Data Streams. Para desempacotar os registros recuperados nos registros de usuário originais da KPL, chame uma das seguintes operações estáticas em `UserRecord.java`:
```
public static List deaggregate(List records)
public static List deaggregate(List records, BigInteger startingHashKey, BigInteger endingHashKey)
```
A primeira operação usa o valor `0` (zero) padrão para `startingHashKey` e o valor `2^128 -1` padrão para `endingHashKey`.
Cada uma dessas operações desagrega a lista de registros conhecidos do Kinesis Data Streams em uma lista de registros de usuário da KPL. Qualquer registro de usuário da KPL com uma chave de hash explícita ou chave de partição fora do intervalo de `startingHashKey` (inclusive) e de `endingHashKey` (inclusive) é descartado da lista de registros retornados.
# Usar a KPL com o Amazon Data Firehose
Ao usar a Kinesis Producer Library (KPL) para gravar dados em um fluxo de dados do Kinesis, é possível usar agregação para combinar os registros gravados. Ao usar esse fluxo de dados como origem para o fluxo de entrega do Firehose, O Firehose desagregará os registros antes de entregá-los ao destino. Quando o fluxo de entrega é configurado para transformar os dados, o Firehose desagregará os registros antes de entregá-los ao AWS Lambda. Para obter mais informações, consulte [Gravando no Amazon Firehose Usando o Kinesis Data Streams](https://docs.aws.amazon.com/firehose/latest/dev/writing-with-kinesis-streams.html).
# Use o KPL com o Registro do AWS Glue Esquema
Você pode integrar seus streams de dados do Kinesis com o AWS Glue Schema Registry. O registro de esquemas do AWS Glue permite detectar, controlar e evoluir esquemas centralmente, ao mesmo tempo que garante que os dados produzidos sejam validados continuamente por um esquema registrado. O esquema define a estrutura e o formato de um registro de dados. Um esquema é uma especificação versionada para publicação, consumo ou datastore confiáveis. O AWS Glue Schema Registry permite que você melhore a qualidade end-to-end dos dados e a governança de dados em seus aplicativos de streaming. Para obter mais informações, consulte [Registro de esquemas do AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html). Uma das formas de configurar essa integração é usar as bibliotecas KPL e Kinesis Client Library (KCL) em Java.
**Importante**
Atualmente, a integração do Kinesis Data AWS Glue Streams e do registro de esquemas só é compatível com os streams de dados do Kinesis que usam produtores de KPL implementados em Java. Não há suporte para múltiplas linguagens.
Para obter instruções detalhadas sobre como configurar a integração do Kinesis Data Streams com o Schema Registry usando o KPL, consulte a [seção “Interagindo com dados KPL/KCL usando as bibliotecas” em Caso de uso: integração do Amazon Kinesis Data Streams](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-integrations.html#schema-registry-integrations-kds) com o Glue Schema Registry. AWS
# Definir a configuração do proxy da KPL
Para aplicativos que não podem se conectar diretamente à Internet, todos os clientes do AWS SDK oferecem suporte ao uso de proxies HTTP ou HTTPS. Em um ambiente empresarial típico, todo o tráfego de saída da rede precisa passar por servidores proxy. Se seu aplicativo usa a Kinesis Producer Library (KPL) para coletar e enviar dados AWS em um ambiente que usa servidores proxy, seu aplicativo exigirá a configuração do proxy KPL. A KPL é uma biblioteca de alto nível criada com base no SDK do AWS Kinesis. Ele é dividido em um processo nativo e um wrapper. O processo nativo executa todas as tarefas de processamento e envio de registros, enquanto o wrapper gerencia o processo nativo e se comunica com ele. Para obter mais informações, consulte [Implementar Produtores Eficientes e Confiáveis com a Amazon Kinesis Producer Library](https://aws.amazon.com/blogs/big-data/implementing-efficient-and-reliable-producers-with-the-amazon-kinesis-producer-library/).
O wrapper é escrito em Java e o processo nativo é escrito em C\$1\$1 com o uso do SDK do Kinesis. A KPL versão 0.14.7 ou superior é compatível com a configuração de proxy no wrapper Java, que pode passar todas as configurações de proxy para o processo nativo. Para obter mais informações, consulte [https://github.com/awslabs/amazon-kinesis-producer/releases/tag/v0.14.7](https://github.com/awslabs/amazon-kinesis-producer/releases/tag/v0.14.7).
É possível usar o código a seguir para adicionar configurações de proxy às aplicações da 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 da versão da KPL
Este tópico descreve a política de ciclo de vida da versão para a Amazon Kinesis Producer Library (KPL). AWS fornece regularmente novos lançamentos para as versões do KPL para oferecer suporte a novos recursos e aprimoramentos, correções de erros, patches de segurança e atualizações de dependências. Recomendamos que você continue up-to-date com as versões do KPL para acompanhar os recursos, as atualizações de segurança e as dependências subjacentes mais recentes. **Não** recomendamos o uso contínuo de uma versão não compatível da KPL.
O ciclo de vida das principais versões da KPL consiste nas três fases a seguir:
+ **Disponibilidade geral (GA)** — Durante essa fase, a versão principal é totalmente suportada. AWS fornece lançamentos regulares de versões secundárias e de patches que incluem suporte para novos recursos ou atualizações de API para o Kinesis Data Streams, bem como correções de bugs e segurança.
+ **Modo de manutenção** — AWS limita os lançamentos da versão do patch para tratar apenas de correções críticas de bugs e problemas de segurança. A versão principal não receberá atualizações dos novos recursos ou APIs do Kinesis Data Streams.
+ **E nd-of-support** — A versão principal não receberá mais atualizações ou lançamentos. As versões publicadas anteriormente continuarão disponíveis por meio de gerenciadores de pacotes públicos e o código permanecerá ativado GitHub. O uso de uma versão que chegou end-of-support é feito a critério do usuário. Recomendamos que você faça a atualização para a versão principal mais recente.
| Versão principal | Fase atual | Data de lançamento | Data do modo de manutenção | End-of-support encontro |
| --- | --- | --- | --- | --- |
| KPL 0.x | Modo de manutenção | 2015-06-02 | 2025-04-17 | 2026-01-30 |
| KPL 1.x | Disponibilidade geral | 2024-12-15 | -- | -- |