Fuente de cambios para Azure Files (versión preliminar)

El feed de cambios de Azure Files proporciona un registro duradero, ordenado, inmutable y de solo lectura de los cambios en archivos y directorios en un recurso compartido de archivos de Azure. Las aplicaciones pueden procesar la fuente en modo de streaming o por lotes para identificar los cambios sin examinar repetidamente todo el recurso compartido.

Utiliza el feed de cambios de Azure Files para crear soluciones que:

• Realiza copias de seguridad incrementales y recuperación ante desastres.
• Mantén un índice de búsqueda, caché o catálogo.
• Sincronizar los datos con otro almacén o con un sistema de archivos local.
• Auditar y analizar los cambios en archivos y directorios.
• Impulsar las canalizaciones que procesan el contenido cambiado.

Funcionamiento del flujo de cambios

Habilitar el feed de cambios es una operación de dos pasos. Primero, activa la funcionalidad en la cuenta de almacenamiento. Luego activa el feed de cambios en cada recurso compartido de archivos que quieras rastrear. Este ámbito difiere del feed de cambios de Blob Storage, que activas una vez para toda la cuenta.

Cada cambio de datos o metadatos admitido en un recurso compartido supervisado se registra como un evento en un registro de Apache Avro de solo anexado. El servicio almacena el registro de cada recurso compartido en un contenedor de blob del sistema en la misma cuenta de almacenamiento.

La fuente de cambios tiene las siguientes características:

• Ordenados e inmutables: los eventos se agrupan en ventanas de tiempo denominadas segmentos. Una vez finalizado un segmento, no cambia, por lo que las lecturas son repetibles y un consumidor puede reiniciar desde una posición guardada.
• Asincrónicos: los eventos están disponibles poco después de que se completa la operación que los produce. La fuente de cambios no es un mecanismo de notificación sincrónica.
• Retomable: Los consumidores pueden mantener los tokens de continuación y reanudar tras una interrupción.
• Retención configurable: el servicio quita automáticamente los eventos después del período de retención configurado en el recurso compartido.
• Consumidores independientes: cada aplicación lee y marca el registro de forma independiente.

El registro comienza después de activar el feed de cambios. El servicio no registra los cambios realizados antes de que actives el cambio de feed ni mientras el feed está desactivado.

Soporte de funcionalidades

Habilitar y configurar la fuente de cambios

La configuración de la fuente de cambios usa el plano de administración. No se puede habilitar, deshabilitar ni volver a configurar la fuente de cambios a través de la API REST de archivos, SMB o NFS. El plano de datos notifica la configuración actual y la ubicación del registro para que los consumidores puedan buscar la fuente.

Activar el feed de cambios en la cuenta de almacenamiento

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

Cuando activas esta propiedad, el servicio aprovisiona un endpoint de Blob Storage en la cuenta porque almacena los registros de cambios como blobs.

Activar el feed de cambios en un recurso compartido de archivos

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 habilita la fuente de cambios sin especificar la retención, el valor predeterminado es de siete días. Los valores válidos de retención son de 1 a 365 días. Aumentar la retención no recupera registros que el servicio ya eliminó.

Comprobación de la configuración

Un consumidor puede detectar el registro llamando a Get Share Properties con la versión de File service 2026-02-06 o posterior:

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

La respuesta incluye los siguientes encabezados:

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>

Estos valores no se devuelven para las instantáneas de recursos compartidos. Un recurso compartido en el que nunca se ha configurado la fuente de cambios notifica false y 0.

Deshabilitar la fuente de cambios

1. En Azure Portal, abra la cuenta de almacenamiento.
2. En Almacenamiento de datos, selecciona Recursos compartidos de archivos y luego selecciona el recurso compartido.
3. En la página Información general, en Propiedades> > Estado de la característica, seleccione el estado situado junto a Fuente de cambios.
4. Desactive Habilitar fuente de cambios.
5. Seleccione Guardar.

Cuando desactivas el change feed, el sistema deja de registrar nuevos eventos. Los registros existentes permanecen accesibles hasta que expire su periodo de conservación.

Para desactivar la funcionalidad de la cuenta, establezca enableFilesChangeFeed en false. No se puede deshabilitar la funcionalidad de la cuenta mientras cualquier recurso compartido de la cuenta aún tenga datos de la fuente de cambios. La petición falla con FilesChangeFeedContainersExist. Deshabilite la fuente de cambios en cada recurso compartido y espere a que expiren los datos del registro conservados.

Uso de la fuente de cambios

La forma recomendada de leer el feed de cambios es la biblioteca cliente .NET. El cliente controla la detección del registro, la ordenación de los segmentos, la última marca de agua consumible, la deserialización de Avro, la detección de restablecimiento y las lecturas reanudables.

Instala el paquete de prelanzamiento:

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

Crea un cliente a partir de un existente ShareClient, y enumera los eventos 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}");
}

El cliente proporciona métodos para:

• Enumerar todos los eventos disponibles hasta la última marca de agua consumible.
• Lee un intervalo de tiempo limitado.
• Reanudar desde un token de continuación.
• Enumerar los cambios entre dos instantáneas del recurso compartido.
• Obtener el último punto completo y seguro del registro.
• Comprueba si los metadatos de la instantánea están finalizados.

Reanudar con un token de continuación

Para un consumidor de larga duración, enumera por página y persiste el token de continuación solo después de procesar con éxito toda la página:

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 de continuación está vinculado a la cuenta de almacenamiento que lo emitió. Pasa un token guardado a GetChanges o GetChangesBetweenSnapshots, no a AsPages.

Leer el registro directamente

Para lenguajes sin una biblioteca cliente de flujo de cambios, puedes leer el contenedor del sistema con una biblioteca cliente de Blob Storage:

1. Llame a Get Share Properties y lea el nombre del contenedor desde x-ms-file-blob-container-for-xfiles-change-feed.
2. Lee meta/reset-latest.json y comprueba si hay un nuevo identificador de rinicio.
3. Lea meta/segments.json y anote la marca de agua lastConsumable.
4. Para cada segmento hasta la marca de agua, lea su archivo meta.json y confirme que su estado es Finalized.
5. Lee los blobs de Avro listados por chunkFilePaths.
6. Procese los registros y avance el punto de comprobación hasta el final de la ventana.

Cada recurso compartido usa un contenedor denominado $fileschangefeed-<GUID>. Un contenedor a nivel $fileschangefeedsys de cuenta está reservado para uso de servicio y no es accesible con las credenciales del cliente.

Registros de eventos de cambio

Cada registro de Avro describe un cambio. La versión del esquema actual es 0.

Los valores de tipo cadena no disponibles se representan como N/A. NewParentFileId y NewFullFilePath están vacíos cuando el evento no es un cambio de nombre o movimiento. Trate ambas formas como sin valor.

Códigos del motivo del cambio

Los códigos de razón incluyen los siguientes valores:

La lista puede crecer con el tiempo. Diseña los consumidores para que ignoren los códigos de motivo que no reconozcan. Ignora los registros ControlEvent y UnknownEventType.

Controlar los eventos de restablecimiento

Un reinicio marca un punto de separación a partir del cual el registro deja de ser continuo con su historial anterior. Los registros anteriores al límite pueden faltar o podrían describir cambios que ya no se reflejan en el recurso compartido. Los registros posteriores al límite son completos y coherentes con el recurso compartido.

Los reinicios pueden producirse tras una conmutación por error no planificada administrada por el cliente o cuando el servicio reinicia el seguimiento de cambios de la cuenta. El servicio notifica un reinicio tanto en forma de registro en banda RESET como de blobs marcadores bajo meta/resets/.

El meta/reset-latest.json puntero identifica el marcador de reinicio más reciente:

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

El puntero no existe para un recurso compartido que nunca se ha restablecido. Trate una respuesta 404 como ningún restablecimiento. Usa latestResetId para detectar un nuevo límite y latestMarkerPath para leer su marcador inmutable.

Cuando un consumidor detecta un nuevo identificador de rinicio:

1. Detenga el procesamiento incremental y descarte los puntos de comprobación emitidos antes del restablecimiento.
2. Registra el identificador de restablecimiento y la hora de reinicio.
3. Vuelva a establecer la línea base enumerando todo el recurso compartido o una nueva instantánea del recurso compartido.
4. Reanude el procesamiento incremental desde el límite de restablecimiento.

La biblioteca de cliente puede lanzar ShareChangeFeedResetException o devolver un ShareChangeFeedResetEvent, según el ShareChangeFeedResetPolicy configurado. Las lecturas acotadas producen un error en el restablecimiento de manera predeterminada. Las lecturas abiertas devuelven los eventos de restablecimiento en orden de manera predeterminada.

Trabajar con instantáneas de recurso compartido

Cada evento incluye un número de versión del contenedor. Cuando se toma una instantánea del recurso compartido, la fuente escribe metadatos que asignan la instantánea a una versión del contenedor y sus ventanas de registro delimitadoras.

Use GetSnapshotStatus para confirmar que la instantánea final está finalizada y, a continuación, use GetChangesBetweenSnapshots para enumerar los eventos entre dos instantáneas. Las consultas con ámbito de instantánea admiten tokens de continuación.

Diferencias con el feed de cambios de Blob Storage

La fuente de cambios de Azure Files utiliza la disposición del contenedor, la codificación Avro, el modelo de segmentos y la última marca de agua consumible de la fuente de cambios de Blob Storage. La siguiente tabla describe las diferencias clave:

Precios y facturación

El servicio almacena los datos de la fuente de cambios como blobs en la misma cuenta de almacenamiento. El sistema de facturación te cobra por los datos de registro almacenados y las solicitudes para leerlos a las tarifas aplicables de Blob Storage. La duración de la retención y el volumen de cambios afectan directamente a los costes de almacenamiento y transacción. Para más información sobre los modelos de facturación de Azure Files, consulta Entender la facturación de Azure Files.

Limitaciones de la versión preliminar

• El feed de cambios solo está disponible para suscripciones aprobadas para la vista previa.
• No se soportan los recursos compartidos de archivos premium ni las operaciones NFS.
• La configuración utiliza el plano de gestión y no está disponible a través de la API de archivo REST, SMB o NFS.
• La configuración no se devuelve para las instantáneas de recursos compartidos y no se puede configurar en una instantánea o en un recurso compartido eliminado de forma temporal.
• Los eventos son asincrónicos y solo se registran los cambios realizados mientras la fuente está habilitada.
• Los campos de identidad e iniciador no están poblados.
• Los consumidores deben tolerar campos y códigos de razón desconocidos y gestionar los reinicios.
• Una copia asíncrona emite un evento cuando la copia comienza, pero no cuando se completa.
• Un cambio de nombre que reemplaza un archivo existente no identifica el archivo reemplazado.

Pasos siguientes

• Información general del desarrollo de aplicaciones con Azure Files
• Compartir instantáneas para Azure Files
• API REST del servicio de archivos
• Compatibilidad con el flujo de cambios en Azure Blob Storage.