Lijstbereiken

De bewerking List Ranges retourneert de lijst met geldige bereiken voor een bestand. Deze bewerking wordt ondersteund in versie 2025-05-05 en hoger voor bestandsshares waarvoor het NFS-protocol is ingeschakeld. Vanaf versie 2026-10-06 ondersteunt deze operatie continuationstokens via de marker parameters and maxresults .

Beschikbaarheid van protocol

Protocol voor bestandsshare ingeschakeld Beschikbaar
SMB Ja-
NFS Ja-

Verzoek

De List Ranges aanvraag wordt als volgt samengesteld. U wordt aangeraden HTTPS te gebruiken.

Methode Aanvraag-URI HTTP-versie
TOEVOEGEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist HTTP/1.1
TOEVOEGEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&maxresults=<int> HTTP/1.1
TOEVOEGEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&marker=<string>&maxresults=<int> HTTP/1.1
TOEVOEGEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&marker=<string> HTTP/1.1
TOEVOEGEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist HTTP/1.1
TOEVOEGEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime> HTTP/1.1
TOEVOEGEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&prevsharesnapshot=<DateTime> HTTP/1.1

Vervang de padonderdelen in de aanvraag-URI als volgt door uw eigen padonderdelen:

Padonderdeel Beschrijving
myaccount De naam van uw opslagaccount.
myshare De naam van uw bestandsshare.
mydirectorypath Facultatief. Het pad naar de bovenliggende map.
myfile De naam van het bestand.

Zie Naamgeving en verwijzingen naar shares, mappen, bestanden en metagegevensvoor meer informatie over padnaamgevingsbeperkingen.

URI-parameters

U kunt de volgende aanvullende parameters opgeven voor de aanvraag-URI.

Parameter Beschrijving
sharesnapshot Facultatief. Versie 2017-04-17 en hoger. De sharesnapshot parameter is een ondoorzichtige DateTime waarde die, indien aanwezig, de momentopname van de share specificeert die moet worden opgevraagd voor het bestand.
timeout Facultatief. De parameter timeout wordt uitgedrukt in seconden. Zie Time-outs instellen voor Azure Files-bewerkingenvoor meer informatie.
prevsharesnapshot Optioneel in versie 2020-02-10 en hoger. De parameter prevsharesnapshot is een ondoorzichtige DateTime waarde die, indien aanwezig, de vorige momentopname aangeeft.

Wanneer zowel deze parameter als sharesnapshot aanwezig zijn, bevat het antwoord alleen paginabereiken die zijn gewijzigd tussen de twee momentopnamen. Wanneer alleen prevsharesnapshot aanwezig is, bevat het antwoord alleen paginabereiken die zijn gewijzigd tussen deze momentopname en de liveshare.

Gewijzigde pagina's bevatten zowel bijgewerkte als gewiste pagina's.
maxresults Facultatief. Versie 2026-10-06 en later. Specificeert het maximale aantal bereiken dat in een responspagina moet worden teruggegeven. Als maxresults niet wordt gespecificeerd, probeert de dienst alle resterende bereiken in één antwoord terug te geven, wat kan resulteren in een time-out voor zeer grote bestanden.

Als maxresults het meer is dan 10.000, behandelt de dienst het als 10.000. Als u maxresults instelt op een waarde die kleiner is dan of gelijk is aan nul, resulteert dit in foutcode 400 (Ongeldige aanvraag).
marker Facultatief. Versie 2026-10-06 en later. Een stringwaarde die het deel van de lijst identificeert dat met de volgende List Ranges bewerking moet worden teruggegeven. Wanneer een antwoord bevat NextMarker, gebruik die waarde zoals marker in een volgende oproep om de enumeratie voort te zetten.

Als marker is gespecificeerd zonder maxresults, begint de service nog steeds met de enumeratie vanaf de markerpositie, maar zendt geen nieuwe NextMarkeruit.

De markeringswaarde is ondoorzichtig voor de client.

Aanvraagheaders

De vereiste en optionele aanvraagheaders worden beschreven in de volgende tabellen:

Algemene aanvraagheaders

Aanvraagheader Beschrijving
Authorization Vereist. Hiermee geeft u het autorisatieschema, de accountnaam en de handtekening op. Zie Aanvragen autoriseren voor Azure Storagevoor meer informatie.
Date of x-ms-date Vereist. Hiermee geeft u de Coordinated Universal Time (UTC) voor de aanvraag. Zie Aanvragen autoriseren voor Azure Storagevoor meer informatie.
x-ms-version Vereist voor alle geautoriseerde aanvragen. Hiermee geeft u de versie van de bewerking die moet worden gebruikt voor deze aanvraag. Deze bewerking wordt ondersteund in versie 2025-05-05 en hoger voor bestandsshares waarvoor het NFS-protocol is ingeschakeld. Parameters van de voortzettingstoken (marker en maxresults) zijn beschikbaar voor versie 2026-10-06 en later.

Zie Versiebeheer voor de Azure Storage-servicesvoor meer informatie.
Range Facultatief. Hiermee geeft u het bereik van bytes op waarvoor bereik moet worden vermeld, inclusief. Als u dit weglaat, worden alle bereiken voor het bestand geretourneerd.
x-ms-range Facultatief. Hiermee geeft u het bereik van bytes op waarvoor bereik moet worden vermeld, inclusief.

Als zowel de Range als x-ms-range headers zijn opgegeven, gebruikt de service de waarde van x-ms-range. Zie De bereikheader voor Azure Files-bewerkingen opgeven voor meer informatie.
x-ms-lease-id:<ID> Facultatief. Versie 2019-02-02 en hoger. Als de header is opgegeven, wordt de bewerking alleen uitgevoerd als de lease van het bestand momenteel actief is en de lease-id die is opgegeven in de aanvraag overeenkomt met die van het bestand. Anders mislukt de bewerking met statuscode 412 (voorwaarde mislukt).

Deze header wordt genegeerd als het bestand zich op een bestandsshare bevindt waarvoor het NFS-protocol is ingeschakeld, wat geen ondersteuning biedt voor bestandsleases.
x-ms-client-request-id Facultatief. Biedt een door de client gegenereerde, ondoorzichtige waarde met een tekenlimiet van 1 kibibyte (KiB) die wordt vastgelegd in de logboeken wanneer logboekregistratie is geconfigureerd. We raden u ten zeerste aan deze header te gebruiken om activiteiten aan de clientzijde te correleren met aanvragen die de server ontvangt. Zie Monitor Azure Filesvoor meer informatie.
x-ms-file-request-intent Vereist als Authorization header een OAuth-token opgeeft. Acceptabele waarde is backup. Deze header geeft aan dat de Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action of Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action moeten worden verleend als ze zijn opgenomen in het RBAC-beleid dat is toegewezen aan de identiteit die is geautoriseerd met behulp van de Authorization-header. Beschikbaar voor versie 2022-11-02 en hoger.
x-ms-allow-trailing-dot: { <Boolean> } Facultatief. Versie 2022-11-02 en hoger. De Booleaanse waarde geeft aan of een volgpunt aanwezig in de aanvraag-URL moet worden ingekort of niet.

Deze header wordt genegeerd als het doel zich op een bestandsshare bevindt waarvoor het NFS-protocol is ingeschakeld. Dit biedt standaard ondersteuning voor een volgpunt.

Zie Shares, mappen, bestanden en metagegevensvoor meer informatie.
x-ms-file-support-rename: { <Boolean> } Facultatief. Ondersteund in versie 2024-05-04 en hoger. Deze header is alleen toegestaan wanneer prevsharesnapshot queryparameter aanwezig is. De Booleaanse waarde bepaalt of de gewijzigde bereiken voor een bestand moeten worden vermeld wanneer de locatie van het bestand in de vorige momentopname verschilt van de locatie in de aanvraag-URI, als gevolg van naamswijzigings- of verplaatsingsbewerkingen. Als de waarde waar is, worden de geldige gewijzigde bereiken voor het bestand geretourneerd. Als de waarde onwaar is, resulteert de bewerking in een fout met een reactie van 409 (Conflict). De standaardwaarde is onwaar.

Alleen aanvraagheaders voor SMB

Geen.

Alleen aanvraagheaders voor NFS

Geen.

Aanvraagbody

Geen.

Antwoord

Het antwoord bevat een HTTP-statuscode, een set antwoordheaders en een antwoordtekst in XML-indeling.

Statuscode

Een geslaagde bewerking retourneert statuscode 200 (OK). Zie Status en foutcodesvoor meer informatie over statuscodes.

Antwoordheaders

Het antwoord voor deze bewerking bevat de headers in de volgende tabellen. Het antwoord kan ook aanvullende standaard HTTP-headers bevatten. Alle standaardheaders voldoen aan de HTTP/1.1-protocolspecificatie.

Algemene antwoordheaders

Antwoordheader Beschrijving
Last-Modified De datum/tijd waarop het bestand het laatst is gewijzigd. Elke bewerking die het bestand wijzigt, inclusief een update van de metagegevens of eigenschappen van het bestand, wijzigt de laatste wijzigingstijd van het bestand.
ETag De ETag bevat een waarde die de versie van het bestand vertegenwoordigt, tussen aanhalingstekens.
x-ms-content-length De grootte van het bestand in bytes. Wanneer prevsharesnapshot aanwezig is, beschrijft de waarde de grootte van het bestand op de sharesnapshot (als de sharesnapshot queryparameter aanwezig is). Anders wordt de grootte van het live-bestand beschreven.
x-ms-request-id Deze header identificeert de aanvraag die is gemaakt en kan worden gebruikt voor het oplossen van problemen met de aanvraag. Zie Problemen met API-bewerkingen oplossenvoor meer informatie.
x-ms-version Geeft de versie van Azure Files aan die wordt gebruikt om de aanvraag uit te voeren.
Date of x-ms-date Een UTC-datum/tijd-waarde die de tijd aangeeft waarop het antwoord is gestart. De service genereert deze waarde.
x-ms-client-request-id U kunt deze header gebruiken om problemen met aanvragen en bijbehorende antwoorden op te lossen. De waarde van deze header is gelijk aan de waarde van de x-ms-client-request-id-header als deze aanwezig is in de aanvraag. De waarde is maximaal 1024 zichtbare ASCII-tekens. Als de x-ms-client-request-id header niet aanwezig is in de aanvraag, is deze header niet aanwezig in het antwoord.

Alleen SMB-antwoordheaders

Geen.

Alleen antwoordheaders van NFS

Geen.

Hoofdtekst van antwoord

De hoofdtekst van het antwoord bevat een lijst met niet-overlappende geldige bereiken, gesorteerd op een groter adresbereik. De indeling van de hoofdtekst van het antwoord is als volgt.

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

Als de volledige reeks bereiken van het bestand is gewist, bevat de hoofdtekst van het antwoord geen bereiken.

Wanneer maxresults in het verzoek is gespecificeerd en er blijven extra bereiken over, bevat het responslichaam een NextMarker element. De indeling van dit antwoord is als volgt:

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

Het NextMarker element wordt weggelaten wanneer er geen bereiken meer over zijn of wanneer maxresults niet is gespecificeerd in het verzoek. Om de enumeratie voort te zetten, vul je de NextMarker waarde als parameter marker in bij het volgende List Ranges verzoek.

Als prevsharesnapshot is opgegeven, bevat het antwoord alleen de pagina's die verschillen tussen de doelmomentopname (of het livebestand) en de vorige momentopname. De geretourneerde bereiken bevatten beide bereiken die zijn bijgewerkt of die zijn gewist. De indeling van dit antwoord is als volgt:

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

Als de volledige set pagina's van het bestand is gewist en de parameter prevsharesnapshot niet is opgegeven, bevat de hoofdtekst van het antwoord geen bereiken.

Machtiging

Alleen de accounteigenaar kan deze bewerking aanroepen.

Opmerkingen

De begin- en eind-byte-offsets voor elk bereik zijn inclusief. Raadpleeg de bereikupdatebewerkingen en bereik clear operations voorbeelden voor Put Range. In deze voorbeelden ziet u welke bereiken worden geretourneerd als u een bytebereik van 512 niet-uitgelijnde byte uit het bestand schrijft of wist.

In een zeer gefragmenteerd bestand met een groot aantal schrijfbewerkingen kan een List Ranges aanvraag mislukken vanwege een time-out van een interne server. Toepassingen die bereiken van een bestand ophalen met een groot aantal schrijfbewerkingen, moeten een subset bereiken tegelijk ophalen.

Vanaf versie 2020-02-10 kunt u List Ranges aanroepen met een prevsharesnapshot parameter. Hiermee worden de bereiken geretourneerd die verschillen tussen het livebestand en een momentopname, of tussen twee momentopnamen van het bestand op momentopnamen. Door deze bereikverschillen te gebruiken, kunt u een incrementele momentopname van een bestand ophalen. Incrementele momentopnamen zijn een rendabele manier om back-ups te maken van bestanden als u uw eigen back-upoplossing wilt implementeren.

Vanaf versie 2026-10-06 kun je aanroepen List Ranges met een maxresults parameter om het aantal bereiken dat in één enkele respons wordt teruggegeven te beperken. Als de respons niet alle resterende bereiken omvat, wordt een NextMarker element opgenomen in het responslichaam. Je kunt deze waarde vervolgens als parameter marker gebruiken bij een volgende List Ranges oproep om de enumeratie voort te zetten vanaf waar het vorige antwoord was gestopt.

Let bij het gebruik van voortzettingstokens op het volgende:

  • Als marker is gespecificeerd zonder maxresults, reikt de service-terugkeer van de markerpositie tot het einde van het bestand zonder een nieuwe NextMarkeruit te zenden.
  • Als het oorspronkelijke verzoek een Range or-header x-ms-range bevatte, zouden latere continuation-verzoeken dezelfde bereikheader moeten bevatten. De marker waarde is alleen betekenisvol binnen de context van het oorspronkelijke bereik.
  • Als marker er een positie wordt verwezen voorbij het einde van het bestand, geeft de dienst 400 (Bad Request) terug.

Bepaalde bewerkingen op een bestand veroorzaken List Ranges mislukken wanneer deze wordt aangeroepen om een incrementele momentopname op te halen. De service retourneert:

  • 404 (Niet gevonden) als u een bestand aanroept dat niet bestaat in een van de momentopnamen (of live, als sharesnapshot niet is opgegeven).
  • 409 (Conflict) als u een bestand aanroept dat het doel was van een overschrijven Kopiëren na de momentopname, opgegeven door prevsharesnapshot.
  • 409 (Conflict) als u een bestand aanroept dat is verwijderd en opnieuw is gemaakt met dezelfde naam en locatie, nadat de momentopname die is opgegeven door prevsharesnapshot is gemaakt.

Zie ook

bewerkingen voor bestanden

  • Last updated on