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á.
# 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.