Change feed para Arquivos do Azure (pré-visualização)

O feed de alterações do Arquivos do Azure fornece um log duradouro, ordenado, imutável e somente leitura das alterações em arquivos e diretórios em um compartilhamento de arquivos do Azure. Os aplicativos podem processar o feed em modo de streaming ou em lote para identificar mudanças sem fazer a varredura repetidamente em toda a pasta compartilhada.

Use o feed de alterações dos Arquivos do Azure para criar soluções que:

• Faça cópia de segurança incremental e recuperação de desastres.
• Mantenha um índice de busca, cache ou catálogo.
• Sincronizar os dados para outro armazenamento ou sistema de arquivos local.
• Auditar e analisar alterações em arquivos e diretórios.
• Conduza pipelines que processam conteúdo alterado.

Como o feed de alterações funciona

Ativar o feed de mudanças é uma operação em duas etapas. Primeiro, ative a funcionalidade na conta de armazenamento. Depois, ative o feed de alterações em cada compartilhamento de arquivos que você deseja acompanhar. Esse escopo difere do feed de mudanças do Armazenamento de Blobs, que você habilita uma vez para toda a conta.

Cada alteração de dados ou metadados com suporte em um compartilhamento rastreado é registrada como um evento em um log do Apache Avro somente de acréscimo. O serviço armazena o log de cada compartilhamento em um contêiner de blob do sistema na mesma conta de armazenamento.

O feed de mudança possui as seguintes características:

• Ordenados e imutáveis: Eventos são agrupados em janelas de tempo chamadas segmentos. Depois que um segmento é finalizado, ele não muda, então as leituras são repetíveis e o consumidor pode reiniciar a partir de uma posição salva.
• Assíncrono: os eventos ficam disponíveis logo após a conclusão da operação que os produziu. Feed de alterações não é um mecanismo de notificação síncrono.
• Retomável: Os consumidores podem persistir os tokens de continuação e retomar após uma interrupção.
• Retenção configurável: O serviço remove automaticamente os eventos após o período de retenção configurado no compartilhamento.
• Consumidores independentes: Cada aplicação lê e faz checkpoint do log de forma independente.

O registro começa depois que você ativa o feed de alterações. O serviço não registra as alterações feitas antes de você ativar o feed de mudança ou enquanto o feed está desativado.

Suporte de funcionalidades

Habilitar e configurar o change feed

A configuração do feed de alterações usa o plano de controle. Você não pode ativar, desativar ou reconfigurar o feed de alterações por meio da API REST de Arquivos, SMB ou NFS. O plano de dados informa as configurações atuais e a localização do log para que os consumidores possam encontrar o feed.

Ativar o feed de mudanças na conta de armazenamento

PATCH https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>?api-version=2026-04-01
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "properties": {
    "enableFilesChangeFeed": true
  }
}

Quando você ativa essa propriedade, o serviço provisiona um endpoint de Armazenamento de Blobs na conta porque armazena os logs do feed de alterações como blobs.

Habilitar o feed de alterações em um compartilhamento de arquivo

PATCH https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/fileServices/default/shares/<file-share>?api-version=2026-04-01
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "properties": {
    "changeFeedEnabled": true,
    "changeFeedRetentionInDays": 7
  }
}

Se você ativar o feed de alterações sem especificar retenção, o padrão é de sete dias. Os valores válidos de retenção são de 1 a 365 dias. Aumentar a retenção não recupera registros que o serviço já havia deletado.

Verificar a configuração

Um consumidor pode descobrir o log chamando Obter Propriedades do Compartilhamento com a versão 2026-02-06 do Serviço de arquivos ou posterior:

GET https://<storage-account>.file.core.windows.net/<file-share>?restype=share
x-ms-version: 2026-02-06
Authorization: Bearer <access-token>

A resposta inclui os seguintes cabeçalhos:

x-ms-file-enable-change-feed: True
x-ms-file-change-feed-retention-in-days: 7
x-ms-file-blob-container-for-xfiles-change-feed: $fileschangefeed-<GUID>

Esses valores não são retornados para snapshots de compartilhamento. Um compartilhamento que nunca teve feed de alterações configurado informa false e 0.

Desativar o feed de alterações

1. No portal do Azure, abra a conta de armazenamento.
2. Em Armazenamento de dados, selecione Compartilhamentos de arquivos e então selecione o compartilhamento de arquivos.
3. Na página Visão geral, em Propriedades>Status do recurso, selecione o status ao lado de Feed de alterações.
4. Desmarque Habilitar feed de alterações.
5. Clique em Salvar.

Quando você desativa o feed de alteração, o sistema para de registrar novos eventos. Registros existentes permanecem acessíveis até o término do período de retenção.

Para desativar a funcionalidade da conta, defina enableFilesChangeFeed para false. Você não pode desabilitar a capacidade da conta enquanto qualquer compartilhamento de arquivos da conta ainda tiver dados do feed de alterações. A solicitação falha com FilesChangeFeedContainersExist. Desabilite o feed de alterações em cada compartilhamento e aguarde os dados do log retidos expirarem.

Consumir o feed de alterações

A forma recomendada de ler o feed de alterações é usando a biblioteca de clientes .NET. O cliente cuida da descoberta de logs, ordenação de segmentos, última marca d’água consumível, desserialização do Avro, detecção de reset e leituras retomáveis.

Instale o pacote de pré-lançamento:

dotnet add package Azure.Storage.Files.Shares.ChangeFeed --prerelease

Crie um cliente de um ShareClient existente e enumere os eventos disponíveis:

using Azure.Identity;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.ChangeFeed;

var serviceUri = new Uri("https://<storage-account>.file.core.windows.net");
var shareClient = new ShareServiceClient(serviceUri, new DefaultAzureCredential())
    .GetShareClient("<file-share>");

ShareChangeFeedClient changeFeedClient =
    shareClient.GetShareChangeFeedClient();

await foreach (ShareChangeFeedEvent change in changeFeedClient.GetChangesAsync())
{
    Console.WriteLine(
        $"{change.EventTime:o} {change.Reason} {change.EventData.FullFilePath}");
}

O cliente fornece métodos para:

• Enumere todos os eventos disponíveis até a última marca d'água consumível.
• Leia um intervalo de tempo delimitado.
• Retomar a partir de um token de continuação.
• Enumere as mudanças entre dois snapshots de compartilhamento.
• Obtenha o ponto completo e seguro mais recente no registro.
• Verifique se os metadados do snapshot estão finalizados.

Retomar com um token de continuação

Para um consumidor de longa execução, enumere por página e persista o token de continuação somente após processar com sucesso toda a página:

string? continuationToken = LoadCheckpoint();

await foreach (Page<ShareChangeFeedEvent> page in
    changeFeedClient.GetChangesAsync(continuationToken).AsPages())
{
    foreach (ShareChangeFeedEvent change in page.Values)
    {
        Process(change);
    }

    SaveCheckpoint(page.ContinuationToken);
}

Um token de continuação está vinculado à conta de armazenamento que o emitiu. Passe um token salvo para GetChanges ou GetChangesBetweenSnapshots, não para AsPages.

Leia o registro diretamente

Para linguagens sem uma biblioteca cliente de fluxo de alterações, você pode ler o contêiner do sistema com uma biblioteca cliente Armazenamento de Blobs:

1. Chame Obter Propriedades de Compartilhamento e leia o nome do contêiner de x-ms-file-blob-container-for-xfiles-change-feed.
2. Leia meta/reset-latest.json e verifique se há um novo identificador de reset.
3. Leia meta/segments.json e anote a lastConsumable marca d'água.
4. Para cada segmento até a marca d'água, leia seu arquivo meta.json e confirme que seu status é Finalized.
5. Leia os blobs do Avro listados por chunkFilePaths.
6. Processe os registros e avance seu ponto de controle até o final da janela.

Cada compartilhamento usa um contêiner chamado $fileschangefeed-<GUID>. Um contêiner $fileschangefeedsys no nível da conta é reservado para uso do serviço e não é acessível com credenciais de clientes.

Alterar registros de eventos

Cada registro Avro descreve uma alteração. A versão atual do esquema é 0.

Valores de string indisponíveis são emitidos como N/A. NewParentFileId e NewFullFilePath ficam vazios quando o evento não é uma renomeação ou movimentação. Trate ambas as formas como sem valor.

Alterar códigos de motivo

Os códigos de razão incluem os seguintes valores:

A lista pode crescer com o tempo. Programe os consumidores para ignorarem os códigos de motivo que não reconhecem. Ignore os registros ControlEvent e UnknownEventType.

Lidar com eventos de redefinição

Uma redefinição marca um limite onde o log não é mais contínuo com seu histórico anterior. Os registros anteriores ao limite podem estar ausentes ou podem descrever mudanças que não são mais refletidas no compartilhamento. Os registros posteriores ao limite são completos e consistentes com o compartilhamento.

Os resets podem ocorrer após um failover não planejado gerenciado pelo cliente ou quando o serviço reinicia o acompanhamento de mudanças da conta. O serviço informa um reset tanto como um registro in-band RESET quanto como blobs de marcador sob meta/resets/.

O meta/reset-latest.json ponteiro identifica o marcador de reset mais recente:

{
    "schemaVersion": 1,
    "latestResetId": "9f2c1c6e-4c0a-4d1e-9d6b-2b7a4c1e83f0",
    "latestResetFileTime": 134288352000000000,
    "latestResetTimeUtc": "2026-07-18T08:00:00.000Z",
    "accountName": "mystorageaccount",
    "containerName": "myshare",
    "reason": "CustomerManagedUnplannedFailover",
    "latestMarkerPath": "meta/resets/00134288352000000000.json"
}

O ponteiro não existe para um compartilhamento que nunca foi redefinido. Trate uma resposta 404 como sem redefinição. Use latestResetId para detectar um novo limite e latestMarkerPath para ler seu marcador imutável.

Quando um consumidor detecta um novo identificador de reset:

1. Pare o processamento incremental e descarte os checkpoints emitidos antes do reset.
2. Registre o identificador de redefinição e a hora da redefinição.
3. Recrie a linha de base enumerando todo o compartilhamento ou um novo instantâneo de compartilhamento.
4. Retome o processamento incremental do limite de redefinição.

A biblioteca cliente pode tanto gerar ShareChangeFeedResetException ou retornar um ShareChangeFeedResetEvent, dependendo do ShareChangeFeedResetPolicy configurado. Leituras limitadas falham na redefinição por padrão. Leituras sem término definido retornam eventos de redefinição em ordem por padrão.

Trabalhe com snapshots compartilhados

Cada evento inclui um número de versão do contêiner. Quando um instantâneo do compartilhamento é feito, o feed escreve metadados que mapeiam o instantâneo para uma versão do contêiner e suas janelas de log delimitadoras.

Use GetSnapshotStatus para confirmar que o instantâneo final está finalizado e depois use GetChangesBetweenSnapshots para enumerar eventos entre dois instantâneos. Consultas com escopo snapshot suportam tokens de continuação.

Diferenças em relação ao change feed do Armazenamento de Blobs

O feed de alterações dos Arquivos do Azure usa o layout do contêiner, a codificação do Avro, o modelo de segmento e a última marca d'água de consumo do feed de mudanças do Armazenamento de Blobs. A tabela a seguir descreve as principais diferenças:

Preços e faturação

O serviço armazena os dados do feed de alterações como blobs na mesma conta de armazenamento. O sistema de cobrança cobra pelos dados de log armazenados e pelas solicitações de leitura, nas taxas aplicáveis do Armazenamento de Blobs. A duração da retenção e o volume de alterações afetam diretamente os custos de armazenamento e transação. Para mais informações sobre modelos de faturamento do Arquivos do Azure, veja Entenda o faturamento do Arquivos do Azure.

Limitações de pré-visualização

• O feed de mudanças está disponível apenas para assinaturas aprovadas para a prévia.
• Compartilhamentos premium e operações NFS não são suportados.
• A configuração usa o plano de gerenciamento e não está disponível através da API de Arquivo REST, SMB ou NFS.
• A configuração não é retornada para snapshots de compartilhamento e não pode ser configurada em um snapshot ou em um compartilhamento deletado de forma suave.
• Os eventos são assíncronos e apenas as alterações feitas enquanto o feed está ativado são registradas.
• Os campos de identidade e iniciador não são preenchidos.
• Os consumidores devem tolerar campos e códigos de razão desconhecidos e lidar com resets.
• Uma cópia assíncrona emite um evento quando a cópia começa, mas não quando ela é concluída.
• Uma renomeação que substitui um arquivo existente não identifica o arquivo substituído.

Próximas Etapas 

• Visão geral do desenvolvimento de aplicativos com arquivos do Azure
• Compartilhe snapshots para Arquivos do Azure
• API REST do serviço de arquivos
• Suporte ao feed de alterações no Armazenamento de Blobs do Azure