Flux de modifications pour Azure Files (aperçu)

Le flux de modifications d’Azure Files fournit un journal durable, ordonné, immuable, en lecture seule des modifications apportées aux fichiers et aux répertoires dans un partage de fichiers Azure. Les applications peuvent traiter le flux en mode streaming ou batch pour identifier les changements sans scanner à répétition l’ensemble du partage.

Utilisez le flux de changements d’Azure Files pour construire des solutions qui :

• Effectuer des sauvegardes incrémentales et une reprise après sinistre.
• Maintenez un index de recherche, un cache ou un catalogue.
• Synchronisez les données vers un autre stockage ou un système de fichiers sur site.
• Auditer et analyser les modifications des fichiers et des répertoires.
• Piloter les pipelines qui traitent les modifications de contenu

Comment fonctionne le flux de modification

Activer le flux de changements est une opération en deux étapes. Premièrement, activez la fonctionnalité sur le compte de stockage. Ensuite, activez le flux de changements sur chaque partage de fichiers que vous souhaitez suivre. Cette portée diffère du flux de changement de Stockage Blob, que vous activez une fois pour l’ensemble du compte.

Chaque modification prise en charge des données ou des métadonnées d’un partage suivi est enregistrée sous forme d’événement dans un journal Apache Avro en ajout uniquement. Le service stocke le journal de chaque partage dans un conteneur d’objets blob système du même compte de stockage.

Le flux de changement présente les caractéristiques suivantes :

• Ordonnés et immuables : les événements sont regroupés en intervalles de temps appelés segments. Une fois qu’un segment est finalisé, il ne change pas, donc les lectures sont répétables et un consommateur peut redémarrer depuis une position enregistrée.
• Asynchrones : les événements deviennent disponibles peu après la fin de l’opération qui les a générés. Le flux de modification n’est pas un mécanisme de notification synchrone.
• Reprise possible : les consommateurs peuvent enregistrer des jetons de continuation et reprendre le traitement après une interruption.
• Rétention configurable : Le service supprime automatiquement les événements après la période de conservation configurée sur le partage.
• Consommateurs indépendants : chaque application lit le journal et enregistre ses points de contrôle de manière indépendante.

La journalisation commence après l’activation du flux de modification. Le service n’enregistre pas les modifications effectuées avant que vous activiez le flux de changement ou lorsque le flux est désactivé.

Support des fonctionnalités

Activer et configurer le flux de changements

La configuration du flux de modification s’effectue via le plan de gestion. Vous ne pouvez pas activer, désactiver ni reconfigurer le flux de modification via l’API REST File, SMB ou NFS. Le plan de données fournit les paramètres actuels et l’emplacement du journal afin que les consommateurs puissent localiser le flux.

Activer le flux de changements sur le compte de stockage

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
  }
}

Lorsque vous activez cette propriété, le service provisionne un point de terminaison Stockage Blob pour le compte, car les journaux du flux de modification sont stockés sous forme d’objets blob.

Activer le flux de modifications sur un partage de fichiers

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
  }
}

Si vous activez le change feed sans spécifier la rétention, la valeur par défaut est de sept jours. Les valeurs de conservation valides sont de 1 à 365 jours. L’augmentation de la durée de conservation ne permet pas de récupérer les enregistrements déjà supprimés par le service.

Vérifier la configuration

Un consommateur peut localiser le journal en appelant Get Share Properties avec la version 2026-02-06 ou une version ultérieure du service de fichiers :

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

La réponse comprend les en-têtes suivants :

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>

Ces valeurs ne sont pas renvoyées pour les instantanés de partage. Pour un partage sur lequel le flux de modification n’a jamais été configuré, les valeurs false et 0 sont renvoyées.

Désactiver le flux de modification

1. Ouvrez le compte de stockage dans le portail Azure.
2. Dans Stockage de données, sélectionnez Partages de fichiers, puis sélectionnez le partage de fichiers.
3. Sur la page Aperçu, sous Propriétés>Statut de la fonctionnalité, sélectionnez le statut à côté de flux de modifications.
4. Décochez Activer le flux de modification.
5. Cliquez sur Enregistrer.

Lorsque vous désactivez le change feed, le système arrête d’enregistrer les nouveaux événements. Les documents existants restent accessibles jusqu’à l’expiration de leur période de conservation.

Pour désactiver la fonctionnalité au niveau du compte, définissez enableFilesChangeFeed sur false. Vous ne pouvez pas désactiver la fonctionnalité au niveau du compte tant qu’un partage de ce compte contient encore des données du flux de modification. La requête échoue avec FilesChangeFeedContainersExist. Désactivez le flux de changement sur chaque partage et attendez que les données de journal conservées expirent.

Utiliser le flux de modification

La méthode recommandée pour lire le flux de modification consiste à utiliser la bibliothèque cliente .NET. La bibliothèque cliente gère la découverte des journaux, l’ordre des segments, le dernier point de progression lisible, la désérialisation Avro, la détection des réinitialisations et la reprise de la lecture.

Installez le package en version préliminaire :

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

Créez un client à partir d’un objet ShareClient existant, puis parcourez les événements disponibles :

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

Le client fournit des méthodes pour:

• Parcourir tous les événements disponibles jusqu’au dernier point de progression lisible.
• Lire les événements sur une plage temporelle délimitée.
• Reprendre à partir d’un jeton de continuation.
• Énumérer les modifications survenues entre deux instantanés de partage.
• Obtenir le dernier point complet et sûr du journal.
• Vérifiez si les métadonnées de l’instantané sont finalisées.

Reprendre la lecture à l’aide d’un jeton de continuation

Pour un consommateur exécuté sur une longue durée, parcourez les événements page par page et enregistrez le jeton de continuation uniquement après avoir traité intégralement la page :

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 jeton de continuation est lié au compte de stockage qui l’a émis. Passez un jeton enregistré à GetChanges ou GetChangesBetweenSnapshots, pas à AsPages.

Lire directement le journal

Pour les langages sans bibliothèque client de flux de changement, vous pouvez lire le conteneur système avec une bibliothèque client Stockage Blob :

1. Appelez Get Share Properties et lisez le nom du conteneur depuis x-ms-file-blob-container-for-xfiles-change-feed.
2. Lisez meta/reset-latest.json et vérifiez s’il y a un nouvel identifiant de réinitialisation.
3. Lisez meta/segments.json et relevez la valeur du point de progression lastConsumable.
4. Pour chaque segment situé jusqu’à ce point de progression, lisez son fichier meta.json et vérifiez que son état est Finalized.
5. Lisez les blobs Avro répertoriés par chunkFilePaths.
6. Traitez les enregistrements et avancez le point de contrôle jusqu’à la fin de l’intervalle.

Chaque partage utilise un conteneur nommé $fileschangefeed-<GUID>. Un conteneur $fileschangefeedsys au niveau du compte est réservé à l’utilisation du service et n’est pas accessible avec les informations d’identification du client.

Enregistrements d’événements de modification

Chaque enregistrement Avro décrit une modification. La version actuelle du schéma est 0.

Les valeurs de chaîne indisponibles sont émises sous la forme N/A. NewParentFileId et NewFullFilePath sont vides lorsque l’événement n’est pas un renommage ou un déplacement. Traitez ces deux formes comme des valeurs absentes.

Modifier les codes de motif

Les codes de motif comprennent notamment les valeurs suivantes :

La liste peut s’allonger avec le temps. Concevez les consommateurs de manière à ce qu’ils ignorent les codes de motif qu’ils ne reconnaissent pas. Ignorez les enregistrements ControlEvent et UnknownEventType.

Gérer les événements de réinitialisation

Une réinitialisation marque une limite au-delà de laquelle le journal ne constitue plus une suite continue de l’historique précédent. Les enregistrements antérieurs à cette limite peuvent être manquants ou décrire des modifications qui ne sont plus reflétées dans le partage. Les enregistrements postérieurs à cette limite sont complets et cohérents avec l’état du partage.

Des réinitialisations peuvent survenir après un basculement non planifié géré par le client ou lorsque le service redémarre le suivi des modifications pour le compte. Le service signale une réinitialisation à la fois au moyen d’un enregistrement RESET intégré au flux et de blobs marqueurs stockés sous meta/resets/.

Le pointeur meta/reset-latest.json identifie le marqueur de réinitialisation le plus récent :

{
    "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"
}

Le pointeur n’existe pas pour un partage n’ayant jamais été réinitialisé. Considérez une réponse 404 comme l’indication qu’aucune réinitialisation n’a eu lieu. Utilisez latestResetId pour détecter une nouvelle limite et latestMarkerPath pour lire son marqueur immuable.

Lorsqu’un consommateur détecte un nouvel identifiant de réinitialisation :

1. Arrêtez le traitement incrémental et supprimez les points de contrôle émis avant la réinitialisation.
2. Enregistrez l’identifiant de réinitialisation et l’heure de réinitialisation.
3. Établissez une nouvelle référence de base en énumérant l’intégralité du partage ou en créant un nouvel instantané de partage.
4. Reprenez le traitement incrémentiel à partir de la limite de réinitialisation.

Selon la valeur configurée pour ShareChangeFeedResetPolicy, la bibliothèque cliente peut soit lever une exception ShareChangeFeedResetException, soit renvoyer un objet ShareChangeFeedResetEvent. Par défaut, les lectures sur une plage délimitée échouent en cas de réinitialisation. Par défaut, les lectures sans borne de fin renvoient les événements de réinitialisation dans l’ordre.

Utiliser des instantanés de partage

Chaque événement inclut un numéro de version du conteneur. Lorsqu’un instantané de partage est créé, le flux écrit des métadonnées qui associent cet instantané à une version de conteneur et aux intervalles du journal qui le délimitent.

Utilisez GetSnapshotStatus pour confirmer que l’instantané final est finalisé, puis utilisez GetChangesBetweenSnapshots pour énumérer les événements entre deux instantanés. Les requêtes portant sur un instantané prennent en charge les jetons de continuation.

Différences avec le flux de changements de Stockage Blob

Le flux de modification Azure Files utilise la disposition des conteneurs, l’encodage Avro, le modèle de segments et le dernier point de progression lisible du flux de modification Stockage Blob. Le tableau suivant décrit les principales différences :

Tarification et facturation

Le service stocke les données du flux de modifications sous forme de blobs dans le même compte de stockage. Le système de facturation vous facture les données de journal stockées et les requêtes de lecture aux tarifs Stockage Blob applicables. La durée de conservation et le volume de changements affectent directement les coûts de stockage et de transaction. Pour plus d’informations sur les modèles de facturation Azure Files, voir Comprendre la facturation Azure Files.

Limitations de la version préliminaire

• Le flux de modification est disponible uniquement pour les abonnements autorisés à accéder à la version préliminaire.
• Les partages de fichiers premium et les opérations NFS ne sont pas pris en charge.
• La configuration s’effectue via le plan de gestion et n’est pas disponible via l’API REST File, SMB ou NFS.
• La configuration n’est pas renvoyée pour les instantanés de partage et ne peut pas être définie sur un instantané ni sur un partage supprimé de manière réversible.
• Les événements sont asynchrones et seules les modifications effectuées pendant que le flux est activé sont enregistrées.
• Les champs d’identité et d’initiateur ne sont pas remplis.
• Les consommateurs doivent tolérer des champs et des codes de raison inconnus et gérer les réinitialisations.
• Une copie asynchrone émet un événement au début de la copie, mais pas à sa fin.
• Un renommage qui remplace un fichier existant n’identifie pas le fichier remplacé.

Étapes suivantes

• Vue d’ensemble du développement d’applications avec Azure Files
• Partager des snapshots pour Azure Files
• API REST du service de fichiers
• Prise en charge des flux de modifications dans Stockage Blob Azure