Feed de alterações para o Ficheiros do Azure (pré-visualização)

O feed de alterações do Ficheiros do Azure fornece um registo duradouro, ordenado, imutável e apenas de leitura das alterações a ficheiros e diretórios numa partilha de ficheiros do Azure. As aplicações podem processar o feed em modo streaming ou batch para identificar alterações sem analisar repetidamente toda a partilha.

Utilize o feed de alterações do Ficheiros do Azure para construir soluções que:

• Realizar backup incremental e recuperação em caso de desastre.
• Mantenha um índice de pesquisa, cache ou catálogo.
• Sincronize os dados para outro armazenamento ou um sistema de ficheiros no local.
• Auditar e analisar alterações em ficheiros e diretórios.
• Acione pipelines que processam conteúdos alterados.

Como funciona o feed de alterações

Ativar o change feed é uma operação em duas etapas. Primeiro, ativa a funcionalidade na conta de armazenamento. Depois ativa o feed de alterações em cada partilha de ficheiros que queres acompanhar. Este âmbito difere do feed de alterações do Armazenamento de Blobs, que podes ativar uma vez para toda a conta.

Cada alteração de dados ou metadados suportados numa partilha rastreada é registada como um evento num registo Apache Avro apenas anexável. O serviço armazena o registo de cada partilha num contentor de blob do sistema na mesma conta de armazenamento.

O feed de alterações apresenta as seguintes características:

• Ordenados e imutáveis: Os eventos são agrupados em janelas temporais chamadas segmentos. Depois de um segmento ser finalizado, não muda, por isso as leituras são repetíveis e o consumidor pode reiniciar a partir de uma posição guardada.
• Assíncrono: Os eventos tornam-se disponíveis pouco depois da conclusão da operação que os produziu. O 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 na partilha.
• Consumidores independentes: Cada aplicação lê e verifica o log de forma independente.

O registo em log começa depois de ativar a change feed. O serviço não regista as alterações feitas antes de ativar o feed de alteração ou enquanto o feed está desativado.

Suporte de funcionalidades

Ativar e configurar o feed de alterações

A configuração do feed de alterações utiliza o plano de gestão. Não podes ativar, desativar ou reconfigurar o registo de alterações através da API REST de Ficheiro, SMB ou NFS. O plano de dados reporta as definições atuais e a localização do registo para que os consumidores possam encontrar o feed.

Ativar o feed de alterações 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 ativas esta propriedade, o serviço aprovisiona um endpoint de Armazenamento de Blobs na conta porque armazena os registos de alterações como blobs.

Ativar o feed de alterações numa partilha de ficheiros

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 ativares o feed de alterações sem especificar retenção, o padrão são sete dias. Os valores válidos de retenção são de 1 a 365 dias. Aumentar a retenção não recupera registos que o serviço já apagou.

Verifique a configuração

Um cliente pode descobrir o registo ao chamar Get Share Properties com a versão 2026-02-06 ou posterior do serviço File:

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>

Estes valores não são devolvidos para instantâneos de partição. Uma partilha que nunca teve o feed de alterações configurado apresenta false e 0.

Desativar o registo de alterações

1. No portal do Azure, abra a conta de armazenamento.
2. Em Armazenamento de Dados, selecione Partilhas de ficheiros e depois selecione a partilha de ficheiros.
3. Na página Descrição geral, em Propriedades>, selecione o estado junto a feed de alterações.
4. Desmarque Ativar o feed de alterações.
5. Selecione Guardar.

Quando desativa o feed de alterações, o sistema deixa de registar novos eventos. Os registos existentes permanecem acessíveis até ao fim do seu período de retenção.

Para desligar a funcionalidade da conta, defina enableFilesChangeFeed para false. Não podes desativar a funcionalidade da conta enquanto qualquer recurso partilhado na conta ainda tiver dados do feed de alterações. A solicitação falha com FilesChangeFeedContainersExist. Desative o feed de alterações em todas as partilhas e espere que os dados de registo retidos expirem.

Consumir o feed de mudança

A forma recomendada de ler o feed de alterações é através da biblioteca de cliente .NET. O cliente trata da descoberta de logs, ordenação de segmentos, marca de água do último consumível, desserialização do Avro, deteçã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 a partir de um(a) 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é à última marca de progresso consumível.
• Leia um intervalo temporal limitado.
• Retomar a partir de um token de continuação.
• Enumere as alterações entre dois snapshots de partilha.
• Obtenha o último ponto completo e seguro no registo.
• Verifique se os metadados do snapshot estão finalizados.

Retoma com um token de continuação

Para um consumidor de longa duração, enumere por página e persista o token de continuação apenas 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 guardado para GetChanges ou GetChangesBetweenSnapshots, não para AsPages.

Leia o registo diretamente

Para linguagens sem biblioteca de cliente do feed de alterações, pode ler o contentor do sistema com uma biblioteca cliente de Armazenamento de Blobs:

1. Chame Get Share Properties e leia o nome do contentor em x-ms-file-blob-container-for-xfiles-change-feed.
2. Leia meta/reset-latest.json e verifique se há um novo identificador de reposição.
3. Leia meta/segments.json e anote a lastConsumable marca de água.
4. Para cada segmento até à marca de água, leia o seu meta.json ficheiro e confirme que o seu estado é Finalized.
5. Leia os blobs do Avro listados por chunkFilePaths.
6. Processe os registos e avance o seu ponto de controlo até ao fim da janela.

Cada partilha utiliza um contentor chamado $fileschangefeed-<GUID>. Um contentor ao nível $fileschangefeedsys da conta é reservado para uso em serviço e não é acessível com credenciais do cliente.

Alterar registos de eventos

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

Valores de cadeia de caracteres indisponíveis são emitidos como N/A. NewParentFileId e NewFullFilePath estão vazios quando o evento não é uma mudança de nome ou movimento. 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. Projete os consumidores para ignorarem códigos de razão que não reconhecem. Ignorar os registos ControlEvent e UnknownEventType.

Processar eventos de reinício

Um reset marca uma fronteira onde o log já não é contínuo com a sua história anterior. Os registos anteriores ao limite podem estar em falta ou podem descrever alterações que já não estão refletidas na pasta partilhada. Os registos após o limite são completos e consistentes com a partição.

Os resets podem ocorrer após um failover não planeado gerido pelo cliente ou quando o serviço reinicia o acompanhamento de alterações da conta. O serviço reporta um reset tanto como registo in-band RESET como como blobs de marcador em 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 uma partilha que nunca foi reposta. Trate uma 404 resposta como sem reposição. Utilize latestResetId para detetar uma nova fronteira e latestMarkerPath para ler o seu marcador imutável.

Quando um consumidor detetar um novo identificador de reset:

1. Pare o processamento incremental e descarte os checkpoints emitidos antes do reset.
2. Registe o identificador da reposição e a hora da reposição.
3. Redefina a linha de base enumerando a partilha inteira ou um novo instantâneo da partilha.
4. Retomar o processamento incremental a partir do limite de reinício.

A biblioteca cliente pode lançar ShareChangeFeedResetException ou devolver um ShareChangeFeedResetEvent, dependendo do ShareChangeFeedResetPolicy configurado. Por defeito, as leituras limitadas falham ao reiniciar. Leituras sem limite definido devolvem eventos de reinicialização ordenados por predefinição.

Trabalhar com instantâneos de partilha

Cada evento inclui um número de versão do contentor. Quando é feito um snapshot de ficheiro partilhado, o feed escreve metadados que mapeiam o snapshot para uma versão do contentor e para as suas janelas de registo delimitadoras.

Utilize GetSnapshotStatus para confirmar que o snapshot final está finalizado, e depois utilize GetChangesBetweenSnapshots para enumerar eventos entre dois snapshots. Consultas com âmbito de instantâneo suportam tokens de continuação.

Diferenças em relação ao feed de alterações do Armazenamento de Blobs

O feed de alterações do Ficheiros do Azure utiliza o layout do contentor, a codificação Avro, o modelo de segmento e a última marca de água consumível do feed de alterações do Armazenamento de Blobs. A tabela seguinte descreve as principais diferenças:

Preços e faturação

O serviço armazena dados do change feed como blobs na mesma conta de armazenamento. O sistema de faturação cobra-lhe pelos dados de registo armazenados e pelos pedidos para os ler às 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 faturação do Ficheiros do Azure, consulte Compreender a faturação do Ficheiros do Azure.

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

• O feed de alterações está disponível apenas para subscrições aprovadas para a pré-visualização.
• Partilhas de ficheiros premium e operações NFS não são suportadas.
• A configuração utiliza o plano de gestão e não está disponível através da API do Ficheiro REST, SMB ou NFS.
• A configuração não é retornada para snapshots de partilha e não pode ser definida num snapshot ou numa partilha eliminada de forma recuperável.
• Os eventos são assíncronos e apenas as alterações feitas enquanto o feed está ativado são registadas.
• Os campos de identidade e iniciador não estão preenchidos.
• Os consumidores devem tolerar campos e códigos de razão desconhecidos e lidar com reinicializações.
• Uma cópia assíncrona emite um evento quando a cópia começa, mas não quando esta termina.
• Uma renomeação que substitui um ficheiro existente não identifica o ficheiro substituído.

Passos seguintes

• Visão geral do desenvolvimento de aplicações com Ficheiros do Azure
• Partilhar instantâneos do Ficheiros do Azure
• API REST do serviço de ficheiros
• Alterar o suporte ao feed em Armazenamento de Blobs do Azure