Azure 檔案儲存體 的變更摘要(預覽版)

Azure 檔案儲存體 變更摘要提供耐久、具順序性、不可變且唯讀的記錄,用來追蹤 Azure 檔案共用中檔案與目錄的變更。 應用程式可以用串流或批次模式處理此摘要,以找出變更,而不必反覆掃描整個檔案共用。

使用 Azure 檔案儲存體 變更摘要來建立可執行下列作業的解決方案:

  • 執行增量備份與災難復原。
  • 維護搜尋索引、快取或目錄。
  • 將資料同步到其他儲存庫或本地檔案系統。
  • 審核並分析檔案及目錄變更。
  • 驅動處理已變更內容的管線。

Note

預覽版的存取權需透過訂閱才能啟用。 請填寫預覽版註冊表單:註冊預覽版:Azure 檔案儲存體 變更摘要。

團隊會為已核准的訂用帳戶啟用預覽版,並在功能可用時與您聯繫。 只有在獲得預覽權限後,才能啟用 Azure 檔案儲存體 變更串流。

Important

此功能目前仍處於預覽階段。 請參閱Microsoft Azure 預覽的補充使用條款,以了解適用於 Azure 測試版、預覽版或其他尚未正式發布的功能的法律條款。

變更資料流的運作方式

啟用變更摘要是兩步驟的操作。 首先,在儲存體帳戶上啟用此功能。 接著,在您要追蹤的每個檔案共用上啟用變更摘要。此範圍與 Blob 儲存體變更摘要不同,後者是整個帳號只需啟用一次。

對受追蹤共用所做的每項受支援的資料或中繼資料變更,都會以事件形式記錄在僅可附加的 Apache Avro 記錄中。 該服務會將每個檔案共用的記錄儲存在相同儲存體帳戶中的系統 blob 容器內。

Change feed 具有以下特性:

  • 有序且不可變: 事件被分組成稱為 段 的時間視窗。 區段定案後就不會再變更,因此讀取具可重複性,取用者也可以從已儲存的位置重新開始。
  • 非同步: 事件會在產生它們的操作完成後不久即可取得。 變更資訊流不是同步通知機制。
  • 可恢復: 消費者可以持久化接續權杖,並在中斷後繼續處理。
  • 可設定的保留: 服務會在共用上設定的保留期間結束後自動移除事件。
  • 獨立取用端: 每個應用程式都會獨立讀取並為日誌建立檢查點。

啟用變更摘要之後才會開始記錄。 服務不會記錄在啟用變更資訊流前或關閉資訊流時所做的變更。

功能支援

Item 預覽支援
計費模式 標準隨用隨付
進階檔案共用 不支援
共用通訊協定 SMB 與檔案 REST API
受追蹤的操作 透過 SMB 與 File REST API 進行的資料與元資料變更
最低檔案服務版本 2026-02-06
最低的管理 API 版本 2026-04-01
用戶端程式庫 .NET Azure.Storage.Files.Shares.ChangeFeed 預發布套件

啟用並設定變更摘要

變更串流設定使用管理平面。 你無法透過 File REST API、SMB 或 NFS 啟用、停用或重新設定變更串流。 資料平面會回報目前的設定和日誌位置,讓用戶端能找到該資訊流。

啟用儲存體帳戶上的變更摘要

當您建立儲存體帳戶時,請啟用 檔案變更摘要,位置在資料保護索引標籤上。您也可以在為現有檔案共用設定變更摘要時,啟用此帳戶功能。

建立儲存帳戶時的資料保護標籤截圖,且在 Azure 檔案儲存體 下勾選啟用 Azure 檔案儲存體 變更訂閱。

啟用這個屬性後,服務會在帳號上設定一個 Blob 儲存體 端點,因為它會把變更串流日誌儲存成 blob。

在檔案共用上啟用變更摘要

  1. 在 Azure 入口網站,開啟儲存體帳戶。
  2. 在資料儲存體下方,選取檔案共用,然後選取該檔案共用。
  3. 在屬性下方找到功能狀態,然後選取變更摘要。
  4. 啟用變更摘要,並指定 1 到 365 天的保留期間。
  5. 選取 [儲存]。

Azure 檔案共用總覽頁面及變更資料饋送窗格的螢幕擷圖,選取「啟用變更訂閱」。

您也可以在建立檔案共用時啟用變更摘要並設定保留期間。

新傳統檔案共用「基本」索引標籤的螢幕擷取畫面,其中已選取 [啟用變更摘要]。

如果您啟用變更摘要但未指定保留期限,預設為七天。 有效的保留時間為1至365天。 提高保留期限並不會復原服務已刪除的記錄。

驗證設定

取用者可透過使用檔案服務版本2026-02-06以上版本呼叫 Get Share Properties 來探索此記錄:

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

回應包含以下標頭:

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>

這些值不會針對共用快照回傳。 從未設定過變更摘要的共用,會回報false與0。

停用變更摘要

  1. 在 Azure 入口網站,開啟儲存體帳戶。
  2. 在資料儲存體下方,選取檔案共用,然後選取該檔案共用。
  3. 在概覽頁面中,於屬性>功能狀態下方,選取變更摘要旁的狀態。
  4. 清除啟用變更摘要。
  5. 選取 [儲存]。

當你關閉變更串流時,系統就會停止記錄新的事件。 現有紀錄可持續存取,直到保存期限屆滿。

要關閉帳號功能,請設定 enableFilesChangeFeed 為 false。 只要帳戶中還有任何共用保留變更摘要資料,就無法停用此帳戶功能。 請求因 FilesChangeFeedContainersExist 而失敗。 在每個共用上停用變更摘要,並等待保留的記錄資料過期。

使用變更摘要

讀取變更摘要的建議方式是使用 .NET 用戶端程式庫。 用戶端會處理記錄探索、區段排序、最後可取用浮水印、Avro 還原序列化、重設偵測與可繼續讀取。

安裝預發布套件:

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

從現有的ShareClient建立用戶端,並列舉可用的事件:

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

用戶端提供下列方法:

  • 列出所有可用事件,直到最後一個可消費的 watermark。
  • 讀取有界的時間範圍。
  • 從接續權杖繼續。
  • 列舉兩個共用快照之間的變更。
  • 取得記錄中最新且完整的可安全讀取位置。
  • 檢查快照的中繼資料是否已定稿。

使用接續權杖繼續

對於長時間執行的取用者,請分頁列舉,並且只有在成功處理完整頁之後,才保存接續權杖:

string? continuationToken = LoadCheckpoint();

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

    SaveCheckpoint(page.ContinuationToken);
}

延續代幣綁定於發行它的儲存帳戶。 請將已儲存的權杖傳遞給GetChanges或GetChangesBetweenSnapshots,而不是傳遞給AsPages。

直接閱讀日誌

對於沒有變更摘要用戶端程式庫的語言,您可以使用 Blob 儲存體用戶端程式庫來讀取系統容器:

  1. 呼叫 Get Share Properties,並從x-ms-file-blob-container-for-xfiles-change-feed讀取容器名稱。
  2. 讀取 meta/reset-latest.json 並檢查新的重置識別碼。
  3. 讀取meta/segments.json,並記下lastConsumable浮水印。
  4. 對於浮水印之前的每個區段,請讀取其meta.json檔案,並確認其狀態為Finalized。
  5. 請閱讀由 chunkFilePaths 列出的 Avro blobs。
  6. 處理這些記錄,並將檢查點推進到該時間範圍的盡頭。

Warning

系統容器由服務管理。 將其內容視為唯讀。 不要在這些容器中寫入、修改或刪除物件。 從區段元資料讀取區段長度與日誌位置,而非建立路徑或硬編碼視窗長度。

每個共用都會使用名為$fileschangefeed-<GUID>的容器。 帳號層 $fileschangefeedsys 級容器是保留給服務用途的,無法用客戶憑證存取。

變更事件記錄

每條 Avro 紀錄都會描述一個變更。 目前的結構版本為 0。

Field Description
SchemaVersion 記錄架構的版本。 依名稱讀取欄位,並忽略無法辨識的欄位。
Reason 描述變更的程式碼。
Protocol 產生變更的協定:Smb、Rest 或 Unknown。
EventTime 變更發生的UTC時間。
Id 此作業的關聯識別碼。
Cvnt 變更當下該共用的容器版本號。
Data.FileId 檔案或目錄的穩定識別碼。
Data.ParentFileId 父目錄的檔案 ID。
Data.NewParentFileId 經重新命名或移動的目的地父系識別碼。
Data.Etag 變更後的實體標記。
Data.FileName 項目名稱但不含目錄路徑。
Data.FullFilePath 變更當時相對於共用根目錄的路徑。
Data.NewFullFilePath 重新命名或移動後的目的地路徑。
Data.IsDirectory 表示該項目是否為目錄。
Data.Identity 保留識別欄位。 這些欄位在目前預覽中沒有被填入。
Data.Initiator 保留發起者欄位。 這個欄位在目前的預覽版本中沒有填入。

無法使用的字串值會以N/A表示。 NewParentFileId 和 NewFullFilePath 當事件不是重新命名或移動時,則為空。 將這兩種形式都視為沒有值。

更改原因代碼

原因代碼包含以下數值:

Protocol 原因代碼
SMB SmbCreate、SmbRename、SmbDelete、SmbWrite、SmbExtend、SmbCreateTruncate、SetInfo、SetSecurityInfo
REST RestCreate, RestRename, RestDelete, RestWrite, RestCreateTruncate, RestSetInfo, RestSetSecurityInfo, SyncCopyFile,AsyncCopyFile
Service RESET、ControlEvent、UnknownEventType

這份清單可能隨時間增加。 設計取用者時,請讓取用者忽略無法辨識的原因代碼。 忽略 ControlEvent 和 UnknownEventType 記錄。

處理重置事件

重置標誌著一個界線,在此界線之後,日誌不再與其先前歷史連續。 邊界之前的記錄可能遺漏,或所描述的變更已不再反映在共用中。 邊界之後的記錄是完整的,且與共用一致。

在客戶管理的非預期容錯移轉之後,或服務重新啟動帳戶的變更追蹤時,可能會發生重設。 服務會以頻內 RESET 記錄和位於 meta/resets/ 下的標記 blob 形式回報重置。

meta/reset-latest.json指標用來識別最新的重置標記:

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

從未重設過的共用不會有這個指標。 將404回應視為沒有重設。 使用latestResetId偵測新的邊界,並使用latestMarkerPath讀取其不可變的標記。

當消費者偵測到新的重置識別碼時:

  1. 停止增量處理,並丟棄重置前發出的檢查點。
  2. 記錄重置識別碼和重置時間。
  3. 透過列舉整個共用或新的共用快照,重新建立基準。
  4. 從重設邊界恢復增量處理。

Important

千萬不要把重置前後的紀錄當作完整的歷史。 備份與複寫工作負載在重置後必須進行完整枚舉。

用戶端函式庫可以拋出 ShareChangeFeedResetException 或回傳 ShareChangeFeedResetEvent,視配置 ShareChangeFeedResetPolicy而定。 預設情況下,有界讀取在發生重設時會失敗。 預設情況下,開放式讀取會依序回傳重設事件。

使用共用快照

每個事件都會有一個容器版本號。 建立共用快照時,摘要會寫入中繼資料,將該快照對應到容器版本及其界限記錄時間範圍。

使用GetSnapshotStatus確認結束快照已定案,然後使用GetChangesBetweenSnapshots列舉兩個快照之間的事件。 快照範圍的查詢支援接續權杖。

與 Blob 儲存體 變更資訊流的差異

Azure 檔案儲存體 變更摘要沿用 Blob 儲存體變更摘要的容器配置、Avro 編碼、區段模型與最後可取用浮水印。 下表說明了主要差異:

層面 Blob 儲存體變更摘要 Azure 檔案變更摘要
Scope 針對帳戶啟用一次,涵蓋所有容器。 先在帳號啟用,然後在每個共用項目上啟用。
記錄位置 每個帳號一個 $blobchangefeed 容器。 每個共用各有一個$fileschangefeed-<GUID>容器。
記錄探索 使用知名的容器名稱。 使用 Get Share Properties 回傳的容器名稱。
物品識別 使用 Blob 名稱。 重新命名等同於先複製再刪除。 使用穩定的檔案與父系識別碼。 重新命名和移動會保留檔案 ID。
Hierarchy blob 名稱可以包含 /,但目錄並非獨立的資源。 包含目錄資源與目錄事件。
快照整合 不會提供快照範圍的變更列舉。 使用容器版本號與快照元資料來進行快照範圍的查詢。
通訊協定歸因 不適用。 識別變更是在 SMB 還是 REST 上發生。
不連續 不會提供重設標記。 使用重置標記來識別故障轉移和追蹤重設邊界。

價格和計費

該服務會將變更資料以 blob 形式儲存在同一個儲存帳號中。 計費系統會依適用的儲存費率,向您收取儲存記錄資料及讀取請求費用。 保留期間與變更量直接影響儲存與交易成本。 如需 Azure 檔案計費模式的詳細資訊,請參閱解 Azure 檔案計費。

預覽限制

  • 變更動態僅對已獲准參與預覽的訂閱開放。
  • 變更資料串流支援使用本地冗餘儲存(LRS)或區域冗餘儲存(ZRS)的儲存帳戶。 目前尚未支援地理冗餘儲存(GRS),但計畫在正式推出時提供支援。
  • 不支援高級檔案分享和NFS操作。
  • 設定使用管理平面,無法透過 File REST API、SMB 或 NFS 進行。
  • 共用快照不會回傳設定,也無法在快照或虛刪除的共用上設定。
  • 事件是非同步的,且只有啟用摘要期間所做的變更才會被記錄。
  • 身分識別與啟動者欄位不會填入值。
  • 取用者必須容忍未知的欄位與原因代碼,並且必須處理重設。
  • 非同步複製在複製開始時會發出事件,但完成時不會。
  • 替換現有檔案的重命名並不會識別被替換的檔案。

下一步