Feed delle modifiche di File di Azure (anteprima)

Il feed di modifiche di File di Azure fornisce un registro duraturo, ordinato, immutabile e in sola lettura delle modifiche a file e directory in una condivisione file Azure. Le applicazioni possono elaborare il feed in modalità streaming o batch per identificare le modifiche senza scansionare ripetutamente l'intera condivisione di rete.

Usare il feed delle modifiche di File di Azure per costruire soluzioni che:

• Esegui backup incrementale e recupero in caso di disastro.
• Mantieni un indice di ricerca, una cache o un catalogo.
• Sincronizza i dati in un altro archivio o in un file system locale.
• Controllano e analizzano le modifiche a file e directory.
• Gestiscono le pipeline che elaborano contenuti modificati.

Funzionamento del feed di modifiche

Abilitare il change feed è un'operazione in due fasi. Per prima cosa, abilita la funzionalità sull'account storage. Poi abilita il feed di modifica su ogni condivisione di file che vuoi tracciare. Questo ambito differisce dal feed di modifiche di gestione rete virtuale di Azure, che si abilita una volta per l'intero account.

Ogni modifica supportata di dati o metadati a una condivisione tracciata viene registrata come evento in un registro Apache Avro di sola aggiunta. Il servizio memorizza il log di ogni condivisione in un container di blob di sistema nello stesso account di archiviazione.

Il feed di cambiamento presenta le seguenti caratteristiche:

• Ordinati e immutabili: Gli eventi sono raggruppati in finestre temporali chiamate segmenti. Dopo che un segmento è stato finalizzato, non cambia, quindi le letture sono ripetibili e il consumer può ricominciare da una posizione salvata.
• Asincrono: Gli eventi diventano disponibili poco dopo il completamento dell'operazione che li ha generati. Il change feed non è un meccanismo di notifica sincrono.
• Riprendibile: I consumatori possono conservare i token di continuazione e riprendere dopo un'interruzione.
• Ritenzione configurabile: Il servizio rimuove automaticamente gli eventi dopo il periodo di retention configurato sulla condivisione.
• Consumer indipendenti: ogni applicazione legge e controlla il log in modo indipendente.

La registrazione inizia dopo aver attivato il feed delle modifiche. Il servizio non registra le modifiche apportate prima che tu abiliti il feed delle modifiche o mentre il feed delle modifiche è disabilitato.

Supporto delle funzionalità

Abilita e configura il flusso delle modifiche

La configurazione del feed delle modifiche utilizza il piano di gestione. Non puoi abilitare, disabilitare o riconfigurare il feed delle modifiche tramite l'API File REST, SMB o NFS. Il piano dati riporta le impostazioni attuali e la posizione del log in modo che i consumer possano trovare il feed.

Abilita il feed delle modifiche sull'account di archiviazione

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 abiliti questa proprietà, il servizio effettua il provisioning di un endpoint gestione rete virtuale di Azure sull'account perché memorizza i log del feed delle modifiche come BLOB.

Abilita il feed delle modifiche su una condivisione file

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 abiliti il feed di modifica senza specificare la retention, il valore predefinito è sette giorni. I valori validi di conservazione sono da 1 a 365 giorni. Aumentare il periodo di conservazione non recupera i documenti che il servizio ha già cancellato.

Verificare la configurazione

Un utente può individuare il log chiamando Get Share Properties con la versione 2026-02-06 del servizio File o successiva:

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

La risposta include i seguenti intestaggi:

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>

Questi valori non vengono restituiti per gli snapshot delle condivisioni. Una condivisione che non ha mai avuto il feed delle modifiche configurato riporta false e 0.

Disabilita il feed delle modifiche

1. Nel portale di Azure aprire l'account di archiviazione.
2. Sotto Archiviazione dati, seleziona Condivisioni file, e poi seleziona la condivisione file.
3. Nella pagina Panoramica, sotto Proprietà>Stato della Caratteristica, seleziona lo stato accanto a Feed delle modifiche.
4. Deselezionare Abilita il feed delle modifiche.
5. Selezionare Salva.

Quando disabiliti il change feed, il sistema smette di registrare nuovi eventi. I documenti esistenti rimangono accessibili fino alla scadenza del loro periodo di conservazione.

Per disattivare la funzionalità dell'account, imposta enableFilesChangeFeed su false. Non è possibile disattivare la funzionalità dell'account finché qualsiasi condivisione nell'account ha ancora i dati del feed delle modifiche. La richiesta fallisce con FilesChangeFeedContainersExist. Disabilitare il feed delle modifiche su ogni condivisione e attendere che i dati di log conservati scadano.

Utilizzare il feed di modifiche

Il modo consigliato per leggere il feed di modifiche è usare la libreria client .NET. Il client gestisce l'individuazione dei log, l'ordine dei segmenti, l'offset limite consumabile più recente, la deserializzazione Avro, il rilevamento del ripristino e le letture riprendibili.

Installa il pacchetto di prerelease:

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

Creare un cliente da un elemento esistente ShareClient, ed elencare gli eventi disponibili:

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}");
}

Il cliente fornisce metodi per:

• Elenca tutti gli eventi disponibili fino all'ultimo watermark consumabile.
• Leggi un intervallo di tempo delimitato.
• Riprendi da un token di continuazione.
• Enumerare i cambiamenti tra due snapshot condivisi.
• Prendi l'ultimo punto completo e sicuro nel registro.
• Controlla se i metadati degli snapshot sono finalizzati.

Riprendere con un token di continuazione

Per un consumer a esecuzione prolungata, enumerare per pagina e persistere il token di continuazione solo dopo aver elaborato con successo l'intera pagina:

string? continuationToken = LoadCheckpoint();

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

    SaveCheckpoint(page.ContinuationToken);
}

Un token di continuazione è vincolato all'account di archiviazione che lo ha emesso. Passa un token salvato a GetChanges o GetChangesBetweenSnapshots, non a AsPages.

Leggi direttamente il log

Per linguaggi senza libreria client di change feed, puoi leggere il contenitore di sistema con una libreria client gestione rete virtuale di Azure:

1. Chiama Get Share Properties e leggi il nome del container da x-ms-file-blob-container-for-xfiles-change-feed.
2. Leggere meta/reset-latest.json e controllare un nuovo identificatore di ripristino.
3. Leggi meta/segments.json e annota la lastConsumable filigrana.
4. Per ogni segmento fino alla filigrana, leggere il meta.json file e confermare che lo stato è Finalized.
5. Leggi i blob Avro elencati da chunkFilePaths.
6. Elaborare i record e anticipare il checkpoint fino alla fine della finestra.

Ogni condivisione utilizza un contenitore chiamato $fileschangefeed-<GUID>. Un container a livello $fileschangefeedsys di account è riservato all'uso di servizio e non è accessibile con le credenziali del cliente.

Record degli eventi di modifica

Ogni record Avro descrive una modifica. La versione attuale dello schema è 0.

I valori stringa non disponibili sono emessi come N/A. NewParentFileId e NewFullFilePath sono vuoti quando l'evento non è una ridenominazione o uno spostamento. Considerare entrambe le forme come senza valore.

Modificare i codici motivo

I codici motivo includono i seguenti valori:

La lista può crescere nel tempo. Progettare i consumer per ignorare i codici motivo che non riconoscono. Ignorare i record ControlEvent e UnknownEventType.

Gestire gli eventi di ripristino

Un ripristino segna un limite in cui il log non è più la continuazione della sua storia precedente. I record precedenti al limite potrebbero mancare oppure descrivere modifiche che non sono più presenti nella condivisione. I record dopo il limite sono completi e coerenti con la condivisione.

I ripristini possono avvenire dopo un failover non pianificato gestito dal cliente o quando il servizio riavvia il tracciamento delle modifiche per l'account. Il servizio segnala un ripristino sia come record in banda RESET sia come BLOB di marcatori in meta/resets/.

Il meta/reset-latest.json puntatore identifica il marker di reset più 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"
}

Il puntatore non esiste per una condivisione che non è mai stata ripristinata. Considera una 404 risposta come se non fosse un reset. Usare latestResetId per rilevare un nuovo limite e latestMarkerPath per leggere il suo marcatore immutabile.

Quando un consumatore rileva un nuovo identificatore di reset:

1. Interrompere l'elaborazione incrementale e scartare i checkpoint creati prima del reset.
2. Registra l'identificatore di reset e l'ora di reset.
3. Ripianificare la baseline elencando l'intera condivisione o un nuovo snapshot della condivisione.
4. Riprendere l'elaborazione incrementale dal limite di ripristino.

La libreria client può lanciare ShareChangeFeedResetException o restituire un ShareChangeFeedResetEvent, a seconda del ShareChangeFeedResetPolicy configurato. Le letture limitate non riescono al ripristino per impostazione predefinita. Le letture senza limite restituiscono gli eventi di ripristino in ordine per impostazione predefinita.

Usare gli snapshot di condivisione

Ogni evento include un numero di versione del container. Quando viene effettuata uno snapshot di condivisione, il feed scrive metadati che mappano lo snapshot a una versione del contenitore e alle sue finestre di log delimitate.

Usare GetSnapshotStatus per confermare che lo snapshot finale sia finalizzato, e poi usare GetChangesBetweenSnapshots per enumerare gli eventi tra due snapshot. Le query con scopo snapshot supportano token di continuazione.

Differenze rispetto al feed di cambiamento di gestione rete virtuale di Azure

Il feed di modifiche di File di Azure utilizza il layout del contenitore, la codifica Avro, il modello di segmento e l'ultima filigrana consumabile dal feed di modifiche di archiviazione BLOB. La seguente tabella descrive le principali differenze:

Determinazione dei prezzi e fatturazione

Il servizio memorizza i dati del feed di modifiche come BLOB nello stesso account di archiviazione. Il sistema di fatturazione addebita i costi per i dati di log memorizzati e per le richieste di lettura alle tariffe di archiviazione BLOB applicabili. La durata di conservazione e il volume delle modifiche influenzano direttamente i costi di stoccaggio e transazione. Per maggiori informazioni sui modelli di fatturazione di File di Azure, vedi Comprendere la fatturazione di File di Azure.

Limitazioni dell'anteprima

• Il feed di modifiche è disponibile solo per le sottoscrizioni approvate per l'anteprima.
• Le condivisioni file premium e le operazioni NFS non sono supportate.
• La configurazione utilizza il piano di gestione e non è disponibile tramite file REST API, SMB o NFS.
• La configurazione non viene restituita per gli snapshot della condivisione e non può essere impostata su uno snapshot o su una condivisione con eliminazione temporanea.
• Gli eventi sono asincroni e vengono registrate solo le modifiche apportate mentre il feed è abilitato.
• I campi Identità e Iniziatore non vengono compilati.
• I consumer devono tollerare campi e codici di ragione sconosciuti e gestire i ripristini.
• Una copia asincrona emette un evento all'inizio della copia, ma non al completamento.
• Una ridenominazione che sostituisce un file esistente non identifica il file sostituito.

Passaggi successivi

• Panoramica dello sviluppo di applicazioni con File di Azure
• Condividi snapshot per File di Azure
• API REST del servizio file
• Supporto del feed di modifiche in Archiviazione BLOB di Azure