Modos de feed de alterações no Azure Cosmos DB

APLICA-SE A: NoSQL

O Azure Cosmos DB oferece dois modos de feed de alterações. Cada modo oferece a mesma funcionalidade principal. As diferenças incluem as operações capturadas no feed, os metadados disponíveis para cada alteração e o período de retenção das alterações. Você pode consumir o feed de alterações em modos diferentes entre vários aplicativos do mesmo contêiner do Azure Cosmos DB para atender aos requisitos de cada carga de trabalho. Cada aplicativo de feed de alterações individual só pode ser configurado para fazer a leitura do feed de alterações em um modo. O consumo do feed de alterações em um modo não o proíbe de consumir o feed de alterações em outro modo em um aplicativo diferente.

Observação

Você tem algum comentário sobre os modos de feed de alterações? Queremos saber sua opinião! Sinta-se à vontade para compartilhar comentários diretamente com a equipe de engenharia do Azure Cosmos DB: cosmoschangefeed@microsoft.com.

Modo de feed de alterações de versão mais recente

O modo de versão mais recente é um registro persistente de alterações feitas em itens com base em criações e atualizações. Você obtém a versão mais recente de cada item no contêiner. Por exemplo, se um item for criado e atualizado antes de você ler o feed de alterações, somente a versão atualizada será exibida no feed de alterações. As exclusões não são capturadas como alterações e, quando um item é excluído, ele não fica mais disponível no feed. O modo de feed de alterações da versão mais recente é habilitado por padrão e é compatível com todas as contas do Azure Cosmos DB, exceto a API para Tabela e a API para PostgreSQL. Esse modo era anteriormente a maneira padrão de consumir o feed de alterações.

Todas as versões e exclusões do modo de feed de alterações (versão prévia)

O modo Todas as versões e exclusões (versão prévia) é um registro persistente de todas as alterações em itens com base em operações de criação, atualização e exclusão. Você obtém um registro de cada alteração em itens na ordem em que ocorreu, incluindo alterações intermediárias em um item entre as leituras do feed de alterações. Por exemplo, se um item for criado e atualizado antes de você ler o feed de alterações, as versões Criar e Atualizar do item aparecerão no feed de alterações. Para ler no feed de alterações em todas as versões e modos de exclusão, você precisará ter backups contínuos configurados para sua conta do Azure Cosmos DB. A ativação de backups contínuos cria o feed de alterações Todas as versões e exclusões. Você só pode ler as alterações que ocorreram dentro do período de backup contínuo ao usa esse modo de feed de alterações. Esse modo só é compatível com contas do Azure Cosmos DB for NoSQL. Saiba mais sobre como se inscrever para a versão prévia.

Casos de uso de feed de alterações

Modo de versão mais recente

O modo de versão mais recente fornece uma maneira fácil de processar alterações históricas e em tempo real em itens em um contêiner com a capacidade de voltar para as alterações desde o início do contêiner.

Veja abaixo cenários adequados para esse modo:

• Migrações de um contêiner inteiro para um local secundário.

• Capacidade de reprocessar alterações desde o início do contêiner.

• Processamento em tempo real de alterações em itens em um contêiner resultantes de operações de criação e atualização.

• Cargas de trabalho que não precisam capturar exclusões ou alterações intermediárias entre leituras.

Modo Todas as versões e exclusões (versão prévia)

O modo de feed de alterações Todas as versões e exclusões permite novos cenários para o feed de alterações e simplifica outras. Você pode ler todas as alterações que ocorreram em itens (mesmo nos casos em que várias alterações ocorreram entre leituras do feed de alterações), identificar o tipo de operação de alterações que estão sendo processadas e obter alterações resultantes de exclusões.

Alguns cenários comuns que esse modo habilita e aprimora são:

• Transferência em tempo real de dados entre dois locais sem implementar uma exclusão temporária.

• Acionamento de lógica com base em alterações incrementais quando várias operações de alteração de determinado item forem esperadas entre pesquisas de feed de alterações.

• Acionamento de alertas em operações de exclusão, como em cenários de auditoria.

• A capacidade de processar o item cria, atualiza e exclui de forma diferente com base no tipo de operação.

Recursos de cada modo

Além dos recursos comuns em todos os modos de feed de alterações, o modo de feed de alterações tem as seguintes características:

Modo de versão mais recente

• O feed de alterações inclui inserções e operações de atualização feitas em itens no contêiner.

• Esse modo de feed de alterações não registra exclusões em log. Você pode capturar exclusões com a definição de sinalizador “exclusão reversível” nos seus itens em vez de excluí-los diretamente. Por exemplo, você pode adicionar um atributo no item chamado deleted com o valor true e definir uma TTL (vida útil) no item. O feed de alterações o captura como uma atualização e o item é excluído automaticamente quando o TTL expira. Como alternativa, é possível definir um período de expiração finito para seus itens usando a funcionalidade TTL. Com essa solução, é necessário processar alterações em um intervalo de tempo menor do que o período de expiração da TTL.

• Somente a alteração mais recente para um item específico está incluída no feed de alterações. As alterações intermediárias podem não estar disponíveis.

• Quando um item é excluído, ele não fica mais disponível no feed de alterações.

• As alterações podem ser sincronizadas de qualquer ponto no tempo e não há nenhum período de retenção de dados fixo para o qual haja alterações disponíveis.

• Não é possível filtrar o feed de alterações para um tipo específico de operação. Uma alternativa possível é adicionar um "marcador flexível" ao item para atualizações e filtrar com base no marcador quando você processar itens no feed de alterações.

• O ponto de partida para ler o feed de alterações pode ser desde o início do contêiner, de um ponto no tempo, de "agora" ou de um ponto de verificação específico. A precisão da hora de início é de aproximadamente cinco segundos.

Modo Todas as versões e exclusões (versão prévia)

• O feed de alterações inclui operações de inserção, atualização e exclusão feitas em itens dentro do contêiner. Exclusões por expirações de TTL também são capturadas.

• Os metadados são fornecidos para determinar o tipo de alteração, incluindo se uma exclusão foi devido a uma expiração de TTL.

• Os itens do feed de alterações são organizados na ordem da hora de modificação. Não há garantia de que as exclusões das expirações de TTL apareçam no feed imediatamente após a expiração do item. Eles aparecem quando o item é limpo do contêiner.

• Todas as alterações que ocorreram dentro da janela de retenção definida para backups contínuos na conta podem ser lidas. A tentativa de ler as alterações que ocorreram fora da janela de retenção resulta em um erro. Por exemplo, se o contêiner tiver sido criado há oito dias e o período de retenção do período de backup contínuo for de sete dias, você só poderá ler as alterações dos últimos sete dias.

• O ponto de partida do feed de alterações pode ser de "agora" ou de um ponto de verificação específico dentro do período de retenção. Você não pode ler as alterações desde o início do contêiner ou de um ponto específico no tempo usando esse modo.

Trabalhar com o feed de alterações

Cada modo é compatível com métodos diferentes para ler o feed de alterações em cada idioma.

Modo de versão mais recente

Você pode usar as seguintes maneiras de consumir alterações do feed de alterações no modo de versão mais recente:

Método para ler o feed de alterações	.NET	Java	Python	Node.js
Modelo de pull do feed de alterações	Sim	Sim	Sim	Yes
Alterar o processador de feed	Sim	Sim	Não	Não
Gatilho do Azure Functions	Yes	Sim	Sim	Yes

Analisar o objeto de resposta

No modo de versão mais recente, o objeto de resposta padrão é uma matriz de itens que foram alterados. Cada item contém os metadados padrão para um item do Azure Cosmos DB, incluindo _etag e _ts, com a adição de uma nova propriedade, _lsn.

O formato _etag é interno e você não deve assumir uma dependência dele, pois ele pode ser alterado a qualquer momento. _ts é um carimbo de data/hora de modificação ou de criação. Use o _ts para uma comparação cronológica. _lsn é uma ID de lote que é adicionada apenas para o feed de alterações e representa a ID da transação. Muitos itens podem ter a mesma _lsn.

O ETag no FeedResponse é diferente do _etag que você vê no item. _etag é um identificador interno e é usado para controle de simultaneidade. A propriedade _etag representa a versão do item, ao passo que a propriedade ETag é usada para sequenciar o feed.

Modo Todas as versões e exclusões (versão prévia)

Durante a versão prévia, os seguintes métodos para ler o feed de alterações estão disponíveis para cada SDK do cliente:

Método para ler o feed de alterações	.NET	Java	Python	Node.js
Modelo de pull do feed de alterações	>= 3.32.0-preview	>= 4.42.0	Não	>= 4.1.0
Alterar o processador de feed	Não	>= 4.42.0	Não	Não
Gatilho do Azure Functions	Não	No	No	Número

Observação

Independentemente do modo de conexão configurado em seu aplicativo, todas as solicitações feitas com o feed de alterações Todas as versões e exclusões usarão o modo Gateway.

Introdução

Para começar a usar o modo de feed de alterações Todas as versões e exclusões, inscreva-se na versão prévia na página Versão prévia do recurso na página de versão geral da sua Assinatura do Azure. Pesquise o recurso AllVersionsAndDeletesChangeFeed e selecione Registrar.

Antes de enviar sua solicitação, verifique se você tem pelo menos uma conta do Azure Cosmos DB na assinatura. Pode ser uma conta nova ou existente que você criou para experimentar a versão prévia do recurso. Se você não tiver contas na assinatura quando a equipe do Azure Cosmos DB receber sua solicitação, a solicitação será recusada porque não há contas para aplicar o recurso.

A equipe do Azure Cosmos DB examina sua solicitação e entra em contato com você por email para confirmar quais contas do Azure Cosmos DB na assinatura você deseja registrar na versão prévia. Para usar a versão prévia, você precisará ter backups contínuos configurados na conta do Azure Cosmos DB. Os backups contínuos podem ser habilitados antes ou depois de serem admitidos na versão prévia, mas os backups contínuos precisam ser habilitados antes de você tentar ler o feed de alterações no modo Todas as versões e exclusões.

Analisar o objeto de resposta

O objeto de resposta é uma matriz de itens que representam cada alteração. A matriz é semelhante ao seguinte exemplo:

[
    {  
        "current": { 
            <The current version of the item that changed. All the properties of your item will appear here. This will be empty for delete operations.>
         },  
        "previous" : { 
            <The previous version of the item that changed. If the change was a delete operation, the item that was deleted will appear here. This will be empty for create and replace operations.>
         },  
        "metadata": {
            "lsn": <A number that represents the batch ID. Many items can have the same lsn.>, 
            "operationType": <The type of change, either 'create', 'replace', or 'delete'.>, 
            "previousImageLSN" : <A number that represents the batch ID of the change prior to this one.>, 
            "timeToLiveExpired" : <For delete changes, it will be 'true' if it was deleted due to a TTL expiration and 'false' if it wasn't.>, 
            "crts": <A number that represents the Conflict Resolved Timestamp. It has the same format as _ts.> 
        } 
    }
]

Limitações

• Com suporte em contas do Azure Cosmos DB for NoSQL. Não há suporte a outros tipos de conta do Azure Cosmos DB.

• Os backups contínuos são necessários para usar esse modo de feed de alterações. As limitações do uso do backup contínuo podem ser encontradas na documentação.

• Não há suporte à leitura de alterações em um contêiner que existia antes da habilitação de backups contínuos na conta.

• No momento, não há suporte à capacidade de começar a ler o feed de alterações desde o início ou para selecionar uma hora de início com base em um carimbo de data/hora anterior. Você pode começar em "agora" ou de uma concessão ou token de continuação anterior.

• O recebimento da versão anterior dos itens que foram atualizados não está disponível no momento.

• Não há suporte às contas que tenham habilitado mesclagem de partições.

Próximas etapas

Para saber mais sobre o feed de alterações, confira os seguintes artigos:

• Visão geral do feed de alterações
• Padrões de design do feed de alterações
• Opções de ler o feed de alterações