Change feed for Azure Files (preview)

Der Azure Files-Änderungsfeed bietet ein dauerhaftes, geordnetes, unveränderliches, schreibgeschütztes Protokoll von Änderungen an Dateien und Verzeichnissen in einer Azure-Dateifreigabe. Anwendungen können den Feed im Streaming- oder Batch-Modus verarbeiten, um Änderungen zu identifizieren, ohne die gesamte Netzwerkfreigabe wiederholt zu scannen.

Verwenden Sie den Azure Files Change Feed, um Lösungen zu bauen, die:

• Führen Sie inkrementelle Backups und Notfallwiederherstellung durch.
• Pflegen Sie einen Suchindex, Cache oder Katalog.
• Synchronisieren Sie Daten mit einem anderen Speicher oder einem lokalen Dateisystem.
• Überprüfen und analysieren Sie Datei- und Verzeichnisänderungen.
• Starten Sie Pipelines, die veränderte Inhalte verarbeiten.

Funktionsweise des Änderungsfeeds

Das Aktivieren des Change Feed ist eine zweistufige Operation. Aktiviere zunächst die Funktionalität für das Speicherkonto. Dann aktiviere den Change Feed auf jeder Dateifreigabe, die du verfolgen möchtest. Dieser Umfang unterscheidet sich vom Blob Storage Change Feed, den du einmal für ein ganzes Konto aktivierst.

Jede unterstützte Daten- oder Metadatenänderung an einer nachverfolgten Freigabe wird als Ereignis in einem ausschließlich anhängbaren Apache-Avro-Log protokolliert. Der Dienst speichert das Protokoll jeder Dateifreigabe in einem System-Blobcontainer im selben Speicherkonto.

Der Änderungsfeed weist die folgenden Eigenschaften auf:

• Geordnet und unveränderbar: Ereignisse werden in Zeitfenstern gruppiert, die als Segmente bezeichnet werden. Nachdem ein Segment finalisiert wurde, ändert es sich nicht mehr, sodass Lesevorgänge reproduzierbar sind und ein Consumer von einer gespeicherten Position aus neu starten kann.
• Asynchron: Ereignisse werden kurz nach Abschluss der Operation, die sie erzeugt hat, verfügbar. Der Change Feed ist kein synchroner Benachrichtigungsmechanismus.
• Wiederaufnehmbar: Konsumenten können Fortsetzungstoken speichern und nach einer Unterbrechung wieder aufnehmen.
• Konfigurierbare Aufbewahrung: Der Dienst entfernt automatisch Ereignisse nach der auf der Freigabe konfigurierten Aufbewahrungsfrist.
• Unabhängige Consumer: Jede Anwendung liest das Log und setzt unabhängig Checkpoints.

Die Protokollierung beginnt, nachdem du den Änderungsfeed aktiviert hast. Der Dienst zeichnet Änderungen, die vorgenommen wurden, bevor du den Änderungsfeed aktivierst oder während der Feed deaktiviert ist, nicht auf.

Unterstützte Funktionen

Aktivieren und konfigurieren Sie den Änderungsfeed

Die Changefeed-Konfiguration nutzt die Managementebene. Man kann den Änderungsfeed nicht über die File REST API, SMB oder NFS aktivieren, deaktivieren oder neu konfigurieren. Die Datenebene meldet die aktuellen Einstellungen und den Log-Standort, damit die Verbraucher den Feed finden können.

Aktiviere den Änderungsfeed auf dem Speicherkonto

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

Wenn du diese Eigenschaft aktivierst, stellt der Dienst einen Blob Storage-Endpunkt auf dem Konto bereit, da er Change Feed-Logs als Blobs speichert.

Aktiviere den Änderungsfeed auf einer Dateifreigabe

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

Wenn du den Änderungsfeed ohne Angabe der Aufbewahrungsdauer aktivierst, beträgt die Standardaufbewahrungsdauer sieben Tage. Gültige Aufbewahrungswerte liegen bei 1 bis 365 Tagen. Eine erhöhte Aufbewahrung stellt keine bereits gelöschten Datensätze wieder her.

Überprüfen der Konfiguration

Ein Verbraucher kann das Protokoll finden, indem er die Version Get Share Properties with File Service 2026-02-06 oder später aufruft:

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

Die Antwort enthält die folgenden Header:

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>

Diese Werte werden für Share-Snapshots nicht zurückgegeben. Eine Share, die noch nie einen Change Feed hatte, konfigurierte Berichte false und 0.

Änderungsfeed deaktivieren

1. Öffnen Sie im Azure-Portal das Speicherkonto.
2. Unter Datenspeicher wählen Sie Dateifreigaben und dann die Dateifreigabe.
3. Auf der Übersichtsseite , unter Status der Eigenschaften>und Funktionen, wählen Sie den Status neben dem Feed ändern.
4. Lösche den Wechselfeed frei.
5. Wählen Sie Speichern.

Wenn du den Change Feed deaktivierst, hört das System auf, neue Ereignisse aufzuzeichnen. Bestehende Unterlagen bleiben bis zum Ablauf ihrer Aufbewahrungsfrist zugänglich.

Um die Kontofähigkeit auszuschalten, setzen Sie enableFilesChangeFeed auf false. Du kannst die Kontofähigkeit nicht deaktivieren, solange ein Share im Konto noch Änderungsfeeddaten enthält. Die Anfrage scheitert mit FilesChangeFeedContainersExist. Deaktiviere den Änderungsfeed bei jeder Freigabe und warte, bis die gespeicherten Logdaten ablaufen.

Konsumieren Sie den Änderungsfeed

Die empfohlene Methode, den Change Feed zu lesen, ist die .NET-Clientbibliothek. Der Client übernimmt die Log-Discovery, die Segmentreihenfolge, die letzte konsumierbare Offsetmarke, die Avro-Deserialisierung, die Reset-Erkennung und die wiederaufnehmbaren Lesevorgänge.

Installieren Sie das Prerelease-Paket:

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

Erstellen Sie einen Client aus einem bestehenden ShareClientund listen Sie die verfügbaren Ereignisse auf:

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

Der Client stellt Methoden bereit, um:

• Zähle alle verfügbaren Ereignisse bis zum letzten Verbrauchswasserzeichen auf.
• Liest einen begrenzten Zeitbereich.
• Mit einem Fortsetzungstoken fortfahren.
• Zähle Änderungen zwischen zwei Share-Snapshots auf.
• Erhalten Sie den neuesten vollständigen und sicheren Punkt im Logbuch.
• Überprüfen Sie, ob die Snapshot-Metadaten finalisiert sind.

Mit einem Fortsetzungstoken fortsetzen

Für einen lang laufenden Consumer seitenweise auflisten und das Fortsetzungstoken erst nach erfolgreicher Verarbeitung der gesamten Seite speichern:

string? continuationToken = LoadCheckpoint();

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

    SaveCheckpoint(page.ContinuationToken);
}

Ein Fortsetzungstoken ist an das Speicherkonto gebunden, das es ausgegeben hat. Übergebe einen gespeicherten Token an GetChanges oder GetChangesBetweenSnapshots, nicht an AsPages.

Lies das Protokoll direkt

Für Sprachen, für die keine Change-Feed-Clientbibliothek verfügbar ist, können Sie den Systemcontainer mit einer Clientbibliothek für Blob Storage lesen:

1. Rufen Sie Get Share Properties an und lesen Sie den Namen des Containers von x-ms-file-blob-container-for-xfiles-change-feed.
2. Lies meta/reset-latest.json und prüfe, ob es eine neue Reset-Kennung gibt.
3. Lesen meta/segments.json Sie und notieren Sie das lastConsumable Wasserzeichen.
4. Für jedes Segment bis zur Wasserstandsmarke lesen Sie die Datei meta.json und bestätigen Sie, dass der Status Finalized ist.
5. Lies die Avro-Blobs, die von chunkFilePaths.
6. Bearbeiten Sie die Unterlagen und verschieben Sie Ihren Checkpoint bis zum Ende des Fensters.

Jede Freigabe verwendet einen Container namens $fileschangefeed-<GUID>. Ein Container auf Kontoebene $fileschangefeedsys ist für die Nutzung des Dienstes reserviert und mit Kundendaten nicht zugänglich.

Ändern von Ereignisdatensätzen

Jeder Avro-Datensatz beschreibt eine Veränderung. Die aktuelle Schema-Version ist 0.

Nicht verfügbare String-Werte werden emittiert als N/A. NewParentFileId und NewFullFilePath sind leer, wenn das Event keine Umbenennung oder Verschiebung ist. Behandle beide Formen als ohne Wert.

Änderungsgrundcodes

Reason-Codes umfassen folgende Werte:

Die Liste kann mit der Zeit wachsen. Implementieren Sie Consumer so, dass sie Reason-Codes ignorieren, die sie nicht erkennen. Ignorieren Sie ControlEvent- und UnknownEventType-Datensätze.

Reset-Ereignisse behandeln

Ein Reset markiert eine Grenze, an der der Log nicht mehr an seinen bisherigen Verlauf anschließt. Datensätze vor der Grenze könnten fehlen oder Änderungen beschreiben, die im Share nicht mehr widerspiegelt sind. Aufzeichnungen nach der Grenze sind vollständig und stimmen mit dem Anteil überein.

Zurücksetzungen können nach einem vom Kunden verwalteten ungeplanten Failover oder wenn der Dienst die Änderungsverfolgung für das Konto neu startet, erfolgen. Der Dienst meldet einen Reset sowohl als In-Band-Datensatz RESET als auch als Marker-Blobs unter meta/resets/.

Der meta/reset-latest.json Zeiger identifiziert den neuesten Reset-Marker:

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

Der Zeiger existiert nicht für einen Share, der nie zurückgesetzt wurde. Behandle eine 404 Antwort als kein Reset. Verwenden latestResetId Sie, um eine neue Grenze zu erkennen und latestMarkerPath ihren unveränderlichen Marker zu lesen.

Wenn ein Client eine neue Reset-ID erkennt:

1. Stoppen Sie die inkrementelle Verarbeitung und verwerfen Sie Kontrollpunkte, die vor dem Reset ausgegeben wurden.
2. Notieren Sie die Reset-Kennung und die Reset-Zeit.
3. Rebaseline, indem man den gesamten Share oder einen neuen Share-Snapshot enumeriert.
4. Setze die inkrementelle Verarbeitung ab der Rücksetzgrenze fort.

Die Client-Bibliothek kann je nach konfigurierter Konfiguration ShareChangeFeedResetPolicyentweder eine Variante ShareChangeFeedResetExceptionShareChangeFeedResetEventwerfen oder zurückgeben. Beschränkte Lesungen schlagen beim Zurücksetzen standardmäßig fehl. Reads mit offenem Ende geben standardmäßig Reset-Events in der Reihenfolge zurück.

Arbeiten Sie mit Freigabe-Snapshots

Jedes Ereignis enthält eine Container-Versionsnummer. Wenn ein Share-Snapshot gemacht wird, schreibt der Feed Metadaten, die den Snapshot auf eine Containerversion und deren zugehörigen begrenzenden Logfenster abbilden.

Verwenden Sie GetSnapshotStatus, um zu bestätigen, dass der abschließende Snapshot finalisiert ist, und verwenden Sie dann GetChangesBetweenSnapshots, um Ereignisse zwischen zwei Snapshots aufzulisten. Abfragen mit Snapshotbereich unterstützen Fortsetzungstoken.

Unterschiede zum Blob Storage Change Feed

Der Azure Files-Änderungsfeed verwendet das Container-Layout, die Avro-Codierung, das Segmentmodell und das letzte verbrauchbare Wasserzeichen aus dem Blob Storage-Änderungsfeed. Die folgende Tabelle beschreibt die wichtigsten Unterschiede:

Preise und Abrechnung

Der Dienst speichert Changefeed-Daten als Blobs im selben Speicherkonto. Das Abrechnungssystem berechnet Ihnen für gespeicherte Logdaten und Leseanforderungen für diese Daten die entsprechenden Blob Storage-Tarife. Die Aufbewahrungsdauer und das Änderungsvolumen beeinflussen direkt Speicher- und Transaktionskosten. Für weitere Informationen zu Azure Files-Abrechnungsmodellen siehe Azure Files-Abrechnung verstehen.

Einschränkungen bei der Vorschau

• Der Change Feed ist nur für Abonnements verfügbar, die für die Vorschau genehmigt wurden.
• Premium-Dateifreigaben und NFS-Operationen werden nicht unterstützt.
• Die Konfiguration nutzt die Verwaltungsebene und ist nicht über die Datei REST API, SMB oder NFS verfügbar.
• Die Konfiguration wird für Share-Snapshots nicht zurückgegeben und kann auch nicht auf einem Snapshot oder einem weich gelöschten Share eingestellt werden.
• Ereignisse sind asynchron, und nur Änderungen, die vorgenommen werden, während der Feed aktiviert ist, werden aufgezeichnet.
• Identitäts- und Initiatorfelder sind nicht ausgefüllt.
• Clients müssen unbekannte Felder und Fehlercodes tolerieren und Zurücksetzungen bewältigen.
• Eine asynchrone Kopie sendet ein Ereignis aus, wenn die Kopie startet, aber nicht, wenn sie abgeschlossen wird.
• Eine Umbenennung, die eine vorhandene Datei ersetzt, gibt nicht an, welche Datei ersetzt wurde.

Nächste Schritte

• Übersicht über die Anwendungsentwicklung mit Azure Files
• Freigabemomentaufnahmen für Azure Files
• Dateiservice REST API
• Change-Feed-Unterstützung in Azure Blob Storage