Rangos de lista

La List Ranges operación devuelve la lista de rangos válidos para un archivo. Esta operación se admite en la versión 2025-05-05 y posteriores para recursos compartidos de archivos con el protocolo NFS habilitado. A partir de la versión 2026-10-06, esta operación soporta tokens de continuación mediante los marker parámetros y maxresults .

Disponibilidad del protocolo

Protocolo habilitado para recursos compartidos de archivos Disponible
SMB Yes
NFS Yes

Solicitud

La solicitud List Ranges se construye de la siguiente manera. Se recomienda usar HTTPS.

Método Solicitud de URI Versión de HTTP
OBTÉN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist HTTP/1.1
OBTÉN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&maxresults=<int> HTTP/1.1
OBTÉN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&marker=<string>&maxresults=<int> HTTP/1.1
OBTÉN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&marker=<string> HTTP/1.1
OBTÉN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist HTTP/1.1
OBTÉN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime> HTTP/1.1
OBTÉN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&prevsharesnapshot=<DateTime> HTTP/1.1

Reemplace los componentes de ruta de acceso que se muestran en el URI de solicitud por el suyo propio, como se indica a continuación:

Componente de ruta de acceso Description
myaccount El nombre de la cuenta de almacenamiento.
myshare Nombre del recurso compartido de archivos.
mydirectorypath Optional. Ruta de acceso al directorio primario.
myfile El nombre del archivo.

Para detalles sobre las restricciones de nombres de rutas, consulte Nombrar y referenciar compartidos, directorios, archivos y metadatos.

Parámetros de URI

Puede especificar los siguientes parámetros adicionales en el URI de solicitud.

Parámetro Description
sharesnapshot Optional. Versión 2017-04-17 y posteriores. El sharesnapshot parámetro es un valor opaco DateTime que, cuando está presente, especifica la instantánea de la compartición a consultar para el archivo.
timeout Optional. El timeout parámetro se expresa en segundos. Para más información, consulte Establecer tiempos de espera para operaciones de Azure Files.
prevsharesnapshot Opcional en la versión 2020-02-10 y posteriores. El prevsharesnapshot parámetro es un valor opaco DateTime que, cuando está presente, especifica la instantánea anterior.

Cuando tanto este parámetro como sharesnapshot este parámetro están presentes, la respuesta contendrá solo rangos de páginas que se han cambiado entre las dos instantáneas. Cuando solo prevsharesnapshot está presente, la respuesta contendrá solo los rangos de página que se han cambiado entre esta instantánea y el live share.

Las páginas modificadas incluyen páginas actualizadas y desactivadas.
maxresults Optional. Versión 2026-10-06 y posteriores. Especifica el número máximo de rangos a devolver en una página de respuesta. Si maxresults no se especifica, el servicio intenta devolver todos los rangos restantes en una sola respuesta, lo que puede resultar en un tiempo de espera para archivos muy grandes.

Si maxresults es mayor que 10.000, el servicio lo considera como 10.000. Establecer maxresults en un valor menor o igual que cero da como resultado el código de respuesta de error 400 (solicitud incorrecta).
marker Optional. Versión 2026-10-06 y posteriores. Un valor de cadena que identifica la parte de la lista que se devolverá con la siguiente List Ranges operación. Cuando una respuesta incluye NextMarker, utiliza ese valor como marker en una llamada posterior para continuar la enumeración.

Si marker se especifica sin maxresults, el servicio sigue iniciando la enumeración desde la posición del marcador, pero no emite otro NextMarker.

El valor del marcador es opaco para el cliente.

Cabeceras de solicitud

Los encabezados de solicitud obligatorios y opcionales se describen en las tablas siguientes:

Encabezados de solicitud comunes

Cabecera de solicitud Description
Authorization Required. Especifica el esquema de autorización, el nombre de la cuenta y la firma. Para más información, consulte Autorizar solicitudes a Azure Storage.
Date o x-ms-date Required. Especifica la hora universal coordinada (UTC) de la solicitud. Para más información, consulte Autorizar solicitudes a Azure Storage.
x-ms-version Requerido para todas las solicitudes autorizadas. Especifica la versión de la operación que se va a usar para esta solicitud. Esta operación se admite en la versión 2025-05-05 y posteriores para recursos compartidos de archivos con el protocolo NFS habilitado. Los parámetros de los tokens de continuación (marker y maxresults) están disponibles para la versión 2026-10-06 y posteriores.

Para obtener más información, vea Versiones de los servicios de Azure Storage.
Range Optional. Especifica el intervalo de bytes en el que se van a enumerar los intervalos, de forma inclusiva. Si se omite, se devuelven todos los rangos del archivo.
x-ms-range Optional. Especifica el intervalo de bytes en el que se van a enumerar los intervalos, de forma inclusiva.

Si se especifican ambos Range encabezados y x-ms-range , el servicio utiliza el valor de x-ms-range. Consulta Especificar el encabezado de rango para operaciones de Azure Files para más información.
x-ms-lease-id:<ID> Optional. Versión 2019-02-02 y posteriores. Si se especifica el encabezado, la operación solo se realizará si el contrato de arrendamiento del archivo está activo y el ID del arrendamiento especificado en la solicitud coincide con el del archivo. De lo contrario, se produce un error en la operación con el código de estado 412 (error de condición previa).

Este encabezado se omite si el archivo se encuentra en un recurso compartido de archivos con el protocolo NFS habilitado, que no admite concesiones de archivos.
x-ms-client-request-id Optional. Proporciona un valor opaco generado por el cliente con un límite de caracteres de 1 kibibyte (KiB) que se registra en los registros cuando se configura el registro. Se recomienda encarecidamente usar este encabezado para correlacionar las actividades del lado cliente con las solicitudes que recibe el servidor. Para obtener más información, consulte Supervisión de Azure Files
x-ms-file-request-intent Obligatorio si Authorization encabezado especifica un token de OAuth. El valor aceptable es backup. Este encabezado especifica que se debe conceder el Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action o Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action si se incluyen en la directiva de RBAC asignada a la identidad autorizada mediante el encabezado Authorization. Disponible para la versión 2022-11-02 y posteriores.
x-ms-allow-trailing-dot: { <Boolean> } Optional. Versión 2022-11-02 y posteriores. El valor booleano especifica si se debe recortar o no un punto final presente en la dirección URL de solicitud.

Este encabezado se omite si el destino se encuentra en un recurso compartido de archivos con el protocolo NFS habilitado, que admite el punto final de forma predeterminada.

Para obtener más información, vea Asignar nombres y hacer referencia a recursos compartidos, directorios, archivos y metadatos.
x-ms-file-support-rename: { <Boolean> } Optional. Soportado en la versión 2024-05-04 y superiores. Este encabezado solo está permitido cuando prevsharesnapshot hay un parámetro de consulta presente. El valor booleano determina si los rangos modificados de un archivo deben listarse cuando la ubicación del archivo en la instantánea anterior es diferente de la ubicación en el URI de la Solicitud, como resultado de operaciones de renombramiento o movimiento. Si el valor es true, se devolverán los intervalos modificados válidos para el archivo. Si el valor es false, la operación producirá un error con la respuesta 409 (Conflicto). El valor predeterminado es falso.

Encabezados de solicitud solo SMB

Ninguna.

Encabezados de solicitud solo NFS

Ninguna.

Cuerpo de la solicitud

Ninguna.

Respuesta

La respuesta incluye un código de estado HTTP, un conjunto de encabezados de respuesta y un cuerpo de respuesta en formato XML.

Código de estado

Una operación correcta devuelve el código de estado 200 (Correcto). Para obtener información sobre los códigos de estado, vea Códigos de estado y de error.

Encabezados de respuesta

La respuesta de esta operación incluye los encabezados de las tablas siguientes. La respuesta también puede incluir encabezados HTTP estándar adicionales. Todos los encabezados estándar cumplen con la especificación del protocolo HTTP / 1.1.

Encabezados de respuesta comunes

Encabezado de respuesta Description
Last-Modified Fecha y hora en que se modificó por última vez el archivo. Cualquier operación que modifique el archivo, incluida una actualización de los metadatos o propiedades del archivo, cambia la hora de la última modificación del archivo.
ETag El ETag contiene un valor que representa la versión del archivo, entre comillas.
x-ms-content-length Tamaño de archivo en bytes. Cuando prevsharesnapshot está presente, entonces el valor describe el tamaño del archivo en el sharesnapshot (si el sharesnapshot parámetro de consulta está presente). De lo contrario, describe el tamaño del archivo en vivo.
x-ms-request-id Este encabezado identifica de forma única la solicitud que se realizó y se puede usar para solucionar problemas de la solicitud. Para obtener más información, consulte Solución de problemas de operaciones de API.
x-ms-version Indica la versión de Azure Files utilizada para ejecutar la solicitud.
Date o x-ms-date Un valor de fecha y hora UTC que indica la hora a la que se inició la respuesta. El servicio genera este valor.
x-ms-client-request-id Puede usar este encabezado para solucionar problemas de solicitudes y respuestas correspondientes. El valor de este encabezado es igual al valor del x-ms-client-request-id encabezado, si está presente en la solicitud. El valor tiene como máximo 1024 caracteres ASCII visibles. Si el encabezado x-ms-client-request-id no está presente en la solicitud, este encabezado no estará presente en la respuesta.

Encabezados de respuesta solo SMB

Ninguna.

Encabezados de respuesta solo NFS

Ninguna.

Cuerpo de respuesta

El cuerpo de respuesta incluye una lista de rangos válidos no solapados, ordenados por rango de direcciones creciente. El formato del cuerpo de respuesta es el siguiente.

<?xml version="1.0" encoding="utf-8"?>  
<Ranges>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
</Ranges>

Si se ha eliminado todo el conjunto de rangos del archivo, el cuerpo de respuesta no incluirá ningún rango.

Cuando maxresults se especifica en la solicitud y quedan rangos adicionales, el cuerpo de respuesta incluye un NextMarker elemento. El formato de esta respuesta es el siguiente:

<?xml version="1.0" encoding="utf-8"?>
<Ranges>
  <Range>
    <Start>Start Byte</Start>
    <End>End Byte</End>
  </Range>
  <Range>
    <Start>Start Byte</Start>
    <End>End Byte</End>
  </Range>
  <NextMarker>opaque-string</NextMarker>
</Ranges>

El NextMarker elemento se omite cuando no quedan más rangos o cuando maxresults no se especifica en la solicitud. Para continuar la enumeración, proporciona el NextMarker valor como marker parámetro en la siguiente List Ranges petición.

Si prevsharesnapshot se especifica, la respuesta incluye solo las páginas que difieren entre la instantánea de destino (o el archivo en vivo) y la instantánea anterior. Los rangos devueltos incluyen tanto los que fueron actualizados como los que fueron eliminados. El formato de esta respuesta es el siguiente:

<?xml version="1.0" encoding="utf-8"?> 
<Ranges> 
  <Range> 
    <Start>Start Byte</Start> 
    <End>End Byte</Start> 
  </Range> 
  <ClearRange> 
    <Start>Start Byte</Start>
    <End>End Byte</Start> 
  </ClearRange> 
  <Range> 
    <Start>Start Byte</Start> 
    <End>End Byte</Start> 
  </Range> 
</Ranges>

Si se ha borrado todo el conjunto de páginas del archivo y no se especifica el prevsharesnapshot parámetro, el cuerpo de la respuesta no incluirá ningún rango.

Autorización

Solo el propietario de la cuenta puede llamar a esta operación.

Remarks

Los desplazamientos de bytes de inicio y fin para cada rango son inclusivos. Consulte los ejemplos de Operaciones de Actualización de Rango y Operaciones de Limpieza de Rango para Alcance de Put. Estos ejemplos muestran qué rangos se devuelven si escribes o borras un rango de 512 bytes no alineados del archivo.

En un archivo muy fragmentado con un gran número de escrituras, una List Ranges petición puede fallar debido a un tiempo de espera interno del servidor. Las aplicaciones que recuperan rangos de un archivo con un gran número de operaciones de escritura deben recuperar un subconjunto de rangos a la vez.

A partir de la versión 2020-02-10, puedes llamar List Ranges con un prevsharesnapshot parámetro. Esto devuelve los rangos que difieren entre el archivo en vivo y una instantánea, o entre dos instantáneas del archivo en instantáneas. Al usar estas diferencias de rango, puedes obtener una instantánea incremental de un archivo. Las instantáneas incrementales son una forma rentable de hacer copias de seguridad de archivos si quieres implementar tu propia solución de respaldo.

A partir de la versión 2026-10-06, puedes llamar List Ranges con un maxresults parámetro para limitar el número de rangos devueltos en una sola respuesta. Si la respuesta no incluye todos los rangos restantes, se incluye un NextMarker elemento en el cuerpo de respuesta. Luego puedes usar este valor como marker parámetro en una llamada posterior List Ranges para continuar la enumeración desde donde terminó la respuesta anterior.

Al usar tokens de continuación, tenga en cuenta lo siguiente:

  • Si marker se especifica sin maxresults, el servicio devuelve desde la posición del marcador hasta el final del archivo sin emitir otro NextMarker.
  • Si la solicitud original incluía un Range encabezado de or x-ms-range , las solicitudes de continuación posteriores deberían incluir el mismo encabezado de rango. El marker valor solo tiene sentido dentro del contexto del rango original.
  • Si marker hace referencia a una posición más allá del final del archivo, el servicio devuelve 400 (Solicitud Incorrecta).

Ciertas operaciones sobre un archivo hacen List Ranges fallar cuando se llama para recuperar una instantánea incremental. El servicio devuelve:

  • 404 (No encontrado) si llamas a un archivo que no existe en una de las instantáneas (o en vivo, si sharesnapshot no está especificado).
  • 409 (Conflicto) si llamas a un archivo que fue el objetivo de una copia de sobreescritura tras la instantánea, especificada por prevsharesnapshot.
  • 409 (Conflicto) si llamas a un archivo que fue eliminado y recreado con el mismo nombre y ubicación, después de que se tomó la instantánea especificada.prevsharesnapshot

Véase también

Operaciones de en archivos

  • Last updated on