Change feed for Azure Files (preview)

Dziennik zmian Azure Files zapewnia trwały, uporządkowany, niezmienny dziennik zmian tylko do odczytu dotyczący plików i katalogów w udziale plików platformy Azure. Aplikacje mogą przetwarzać strumień danych w trybie strumieniowym lub wsadowym, aby identyfikować zmiany bez konieczności wielokrotnego skanowania całego udziału.

Użyj kanału zmian w Azure Files, aby budować rozwiązania, które:

• Wykonuj przyrostowe kopie zapasowe i odzyskiwanie po awarii.
• Utrzymuj indeks wyszukiwania, pamięć podręczną lub katalog.
• Synchronizuj dane do innego magazynu lub lokalnego systemu plików.
• Audytuj i analizuj zmiany w plikach i katalogach.
• Kieruj potokami przetwarzającymi zmienioną treść.

Jak działa kanał informacyjny zmian

Włączanie przepływu zmian to operacja dwuetapowa. Po pierwsze, włącz tę funkcję na koncie magazynu. Następnie włącz strumień zmian na każdym udziale plików, który chcesz śledzić. Ten zakres różni się od strumienia zmian w Blob Storage, który włączasz raz dla całego konta.

Każda zmiana obsługiwanych danych lub metadanych w monitorowanym udziale jest rejestrowana jako zdarzenie w logu Apache Avro tylko do dopisywania. Usługa przechowuje dziennik każdego udziału w kontenerze systemowych obiektów blob na tym samym koncie magazynu.

Kanał zmian ma następujące cechy:

• Uporządkowane i niezmienne: Zdarzenia są grupowane w okna czasowe zwane segmentami. Po finalizacji segmentu nie zmienia się, więc odczyty są powtarzalne i konsument może wznowić od zapisanej pozycji.
• Asynchroniczny: Zdarzenia stają się dostępne wkrótce po zakończeniu operacji, która je wygenerowała. Feed zmian nie jest synchronicznym mechanizmem powiadomień.
• Możliwość wznawiania: Konsumenci mogą utrzymywać tokeny kontynuacyjne i wznowić po przerwie.
• Konfigurowalny okres retencji: Usługa automatycznie usuwa zdarzenia po upływie okresu retencji skonfigurowanego dla udziału.
• Niezależni konsumenci: Każda aplikacja odczytuje i zapisuje punkty kontrolne w dzienniku niezależnie.

Rejestrowanie rozpoczyna się po włączeniu change feed. Usługa nie rejestruje zmian przed włączeniem feed zmian lub gdy feed jest wyłączony.

Obsługa funkcji

Włącz i skonfiguruj feed zmian

Zmień konfigurację feedu za pomocą płaszczyzny zarządzania. Nie możesz włączyć, wyłączyć ani ponownie skonfigurować change feed przez interfejs API File REST, SMB ani NFS. Powierzchnia danych raportuje aktualne ustawienia i lokalizację logu, aby konsumenci mogli znaleźć kanał.

Włącz feed zmian na koncie pamięci

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

Po włączeniu tej właściwości usługa przydziela na koncie punkt końcowy Blob Storage, ponieważ przechowuje dzienniki kanału zmian jako obiekty blob.

Włącz feed zmian na udostępnionym pliku

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

Jeśli włączysz change feed bez określenia retencji, domyślny okres retencji wynosi siedem dni. Ważne wartości retencyjne to od 1 do 365 dni. Zwiększenie okresu przechowywania nie odzyskuje rekordów, które usługa już usunęła.

Sprawdzanie konfiguracji

Konsument może odnaleźć log, wywołując metodę Get Share Properties z usługą File w wersji 2026-02-06 lub nowszą:

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

Odpowiedź zawiera następujące nagłówki:

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>

Te wartości nie są zwracane do snapshotów share. Udział, który nigdy nie miał skonfigurowanych raportów false feed zmian oraz 0.

Wyłącz feed zmiany

1. W witrynie Azure Portal otwórz konto magazynu.
2. W sekcji Data storage wybierz Udziały plików, a następnie wybierz udział plików.
3. Na stronie Przegląd, w sekcji Właściwości>Status funkcji, wybierz status obok Kanał informacyjny o zmianach.
4. Usuń Włącz feed zmian.
5. Wybierz Zapisz.

Gdy wyłączysz feed zmian, system przestaje rejestrować nowe zdarzenia. Istniejące dokumenty pozostają dostępne do końca okresu ich przechowywania.

Aby wyłączyć funkcję konta, ustaw enableFilesChangeFeed na false. Nie możesz wyłączyć funkcji konta, gdy każda udziałka na koncie nadal ma dane o zmianach. Żądanie kończy się niepowodzeniem .FilesChangeFeedContainersExist Wyłącz change feed w każdym udziale i poczekaj na wygaśnięcie zachowanych danych logowych.

Korzystanie ze zestawienia zmian

Zalecanym sposobem odczytu kanału zmian jest biblioteka klienta .NET. Klient obsługuje odkrywanie logów, kolejność segmentów, ostatni używany znak wodny, deserializację Avro, wykrywanie resetów oraz wstrzymywane odczyty.

Zainstaluj pakiet przedpremierowy:

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

Stwórz klienta z istniejącego ShareClient, i wylicz dostępne zdarzenia:

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

Klient udostępnia metody do:

• Wypisz wszystkie dostępne zdarzenia aż do ostatniego przetwarzalnego znacznika wodnego.
• Odczytaj ograniczony zakres czasowy.
• Wznów przy użyciu tokena kontynuacji.
• Wylicz zmiany między dwoma snapshotami share.
• Pobierz najnowszy pełny i punkt bezpieczny w dzienniku.
• Sprawdź, czy metadane snapshotów są sfinalizowane.

Wznów za pomocą tokenu kontynuacji

Dla długotrwale działającego konsumenta należy wyliczać po stronach i zapisywać token kontynuacji dopiero po pomyślnym przetworzeniu całej strony:

string? continuationToken = LoadCheckpoint();

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

    SaveCheckpoint(page.ContinuationToken);
}

Token kontynuacyjny jest powiązany z kontem magazynu, które go wydało. Przekaż zapisany token do GetChanges lub GetChangesBetweenSnapshots, nie do AsPages.

Przeczytaj dziennik bezpośrednio

Dla języków bez biblioteki klienta feed zmian można odczytać kontener systemowy za pomocą biblioteki klienta Blob Storage:

1. Wołaj Get Share Properties i czytaj nazwę kontenera z x-ms-file-blob-container-for-xfiles-change-feed.
2. Przeczytaj meta/reset-latest.json i sprawdź, czy nie ma nowego identyfikatora resetu.
3. Przeczytaj meta/segments.json i zanotuj znak lastConsumable wodny.
4. Dla każdego segmentu do znacznika przeczytaj jego plik meta.json i potwierdź, że jego status to Finalized.
5. Przeczytaj obiekty blob Avro wymienione przez chunkFilePaths.
6. Przetwórz rekordy i przesuń punkt kontrolny na koniec okna.

Każdy udział używa kontenera o nazwie $fileschangefeed-<GUID>. Kontener na poziomie $fileschangefeedsys konta jest zarezerwowany do użytku usługowego i nie jest dostępny za pomocą danych danych klienta.

Zmienianie rekordów zdarzeń

Każdy rekord Avro opisuje jedną zmianę. Obecna wersja schematu to 0.

Niedostępne wartości ciągów znaków są emitowane jako N/A. NewParentFileId NewFullFilePath i są puste, gdy zdarzenie nie jest zmianą nazwy lub przeniesieniem. Traktuj obie formy jako bez wartości.

Zmień kody powodów

Kody przyczyn obejmują następujące wartości:

Lista może się z czasem powiększać. Projektuj odbiorców tak, aby ignorowali kody przyczyn, których nie rozpoznają. Ignoruj rekordy ControlEvent i UnknownEventType.

Obsługa zdarzeń resetowania

Reset oznacza granicę, na której dziennik nie jest już ciągły ze swoją wcześniejszą historią. Zapisy przed granicą mogą być nieobecne lub opisywać zmiany, które nie są już odzwierciedlone w udziale. Zapisy po granicy są kompletne i zgodne z podziałem.

Resety mogą nastąpić po nieplanowanym przełączaniu awaryjnym zarządzanym przez klienta lub po wznowieniu przez usługę śledzenia zmian dla konta. Usługa zgłasza reset zarówno jako rekord in-band RESET, jak i jako markerowe bloby w meta/resets/.

Wskaźnik meta/reset-latest.json wskazuje najnowszy znacznik resetu:

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

Wskaźnik nie istnieje dla udziału, który nigdy nie został zresetowany. Traktuj 404 odpowiedź jako brak resetu. Użyj latestResetId do wykrywania nowej granicy podziału i latestMarkerPath do odczytu jej niezmiennego znacznika.

Gdy konsument wykryje nowy identyfikator resetu:

1. Zatrzymaj przetwarzanie przyrostowe i usuń punkty kontrolne wydane przed resetem.
2. Zarejestruj identyfikator resetu i czas resetu.
3. Zmień linię bazową, wyliczając cały udział sieciowy lub nową migawkę udziału.
4. Wznowiaj inkrementalne przetwarzanie od granicy resetu.

Biblioteka klienta może wyrzucać ShareChangeFeedResetException lub zwracać , ShareChangeFeedResetEventw zależności od skonfigurowanej ShareChangeFeedResetPolicy. Odczyty ograniczone domyślnie nie ustępują przy resecie. Odczyty bez określonego końca domyślnie zwracają zdarzenia resetu w kolejności.

Współpraca z migawkami udostępniania

Każde zdarzenie zawiera numer wersji kontenera. Gdy migawka udziału jest tworzona, kanał informacyjny zapisuje metadane, które przypisują migawkę do wersji kontenera i odpowiadających jej granicznych okien dziennika.

Użyj GetSnapshotStatus, aby potwierdzić, że migawka końcowa jest sfinalizowana, a następnie użyj GetChangesBetweenSnapshots, aby wyliczyć zdarzenia pomiędzy dwoma migawkami. Zapytania w zakresie migawki obsługują tokeny kontynuacyjne.

Różnice w stosunku do Blob Storage feed zmian

Strumień zmian usługi Azure Files wykorzystuje układ kontenera, kodowanie Avro, model segmentowy oraz ostatni znacznik możliwy do odczytu ze strumienia zmian usługi Blob Storage. Poniższa tabela opisuje kluczowe różnice:

Ceny i rozliczenia

Usługa przechowuje dane kanału informacyjnego zmian w postaci obiektów blob na tym samym koncie magazynu. System rozliczeniowy pobiera opłaty za przechowywane dane logowe i żądania ich odczytu według odpowiednich stawek Blob Storage. Czas retencji i wolumen zmian bezpośrednio wpływają na koszty przechowywania i transakcji. Więcej informacji o modelach rozliczeń Azure Files można znaleźć w artykule Understand Azure Files billing.

Ograniczenia wersji zapoznawczej

• Feed zmian jest dostępny tylko dla subskrypcji zatwierdzonych do podglądu.
• Udostępnianie plików Premium i operacje NFS nie są obsługiwane.
• Konfiguracja korzysta z płaszczyzny zarządzania i nie jest dostępna przez API File REST, SMB ani NFS.
• Konfiguracja nie jest zwracana dla migawek udziału i nie można jej ustawić dla migawki ani miękko usuniętego udziału.
• Zdarzenia są asynchroniczne i rejestrowane są tylko zmiany dokonane podczas włączania feedu.
• Pola tożsamości i inicjatora nie są wypełniane.
• Klienci muszą tolerować nieznane pola i kody przyczyn oraz radzić sobie z resetami.
• Kopia asynchroniczna emituje zdarzenie na początku kopii, ale nie podczas jego zakończenia.
• Zmiana nazwy, która zastępuje istniejący plik, nie identyfikuje zastąpionego pliku.

Następne kroki

• Omówienie tworzenia aplikacji za pomocą usługi Azure Files
• Udostępniaj migawki dla Azure Files
• API REST usługi plików
• Obsługa strumienia zmian w Azure Blob Storage