Paginabereiken ophalen

Artikel
02/07/2024

De bewerking Paginabereiken ophalen retourneert de lijst met geldige paginabereiken voor een pagina-blob of momentopname van een pagina-blob.

Aanvraag

De aanvraag Paginabereiken ophalen kan als volgt worden samengesteld. U wordt aangeraden HTTPS te gebruiken. Vervang myaccount door de naam van uw opslagaccount:

GET-methode-aanvraag-URI	HTTP-versie
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>&prevsnapshot=<DateTime>`	HTTP/1.1

Geëmuleerde opslagservice-URI

Wanneer u een aanvraag indient bij de geëmuleerde opslagservice, geeft u de hostnaam van de emulator en Azure Blob Storage poort op als 127.0.0.1:10000, gevolgd door de naam van het geëmuleerde opslagaccount:

GET-methode-aanvraag-URI	HTTP-versie
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=pagelist`	HTTP/1.1

Zie De Azure-opslagemulator gebruiken voor ontwikkelen en testen voor meer informatie.

URI-parameters

De volgende aanvullende parameters kunnen worden opgegeven voor de aanvraag-URI:

Parameter	Beschrijving
`marker`	Optioneel, versie 2020-10-02 en hoger. Identificeert het gedeelte van de bereiken die moeten worden geretourneerd met de volgende GetPageRanges-bewerking. De bewerking retourneert een markeringswaarde in de antwoordtekst als de geretourneerde bereiken onvolledig zijn. De markeringswaarde kan vervolgens in een volgende aanroep worden gebruikt om de volgende set bereiken aan te vragen. De markeringswaarde is ondoorzichtig voor de client.
`maxresults`	Optioneel, versie 2020-10-02 en hoger. Hiermee geeft u het maximum aantal paginabereiken op dat moet worden geretourneerd. Als de aanvraag een waarde opgeeft die groter is dan 10.000, retourneert de server maximaal 10.000 items. Als er aanvullende resultaten moeten worden geretourneerd, retourneert de service een vervolgtoken in het antwoordelement NextMarker. Als u instelt `maxresults` op een waarde die kleiner is dan of gelijk is aan nul, resulteert dit in foutcode 400 (Ongeldige aanvraag).
`snapshot`	Optioneel. Een ondoorzichtige Datum/tijd-waarde die, indien aanwezig, de momentopname van de blob aangeeft waaruit informatie moet worden opgehaald. Zie Een momentopname van een blob maken voor meer informatie over het werken met blob-momentopnamen.
`timeout`	Optioneel. Uitgedrukt in seconden. Zie Time-outs instellen voor Blob Storage-bewerkingen voor meer informatie.
`prevsnapshot`	Optioneel, versie 2015-07-08 en hoger. Een Datum/tijd-waarde die aangeeft dat het antwoord alleen pagina's bevat die zijn gewijzigd tussen de doel-blob en de vorige momentopname. Gewijzigde pagina's bevatten zowel bijgewerkte als gewiste pagina's. De doel-blob kan een momentopname zijn, zolang de momentopname die is opgegeven door `prevsnapshot` de oudere van de twee is. Opmerking: Incrementele momentopnamen worden momenteel alleen ondersteund voor blobs die zijn gemaakt op of na 1 januari 2016.

Aanvraagheaders

In de volgende tabel worden vereiste en optionele aanvraagheaders beschreven.

Aanvraagheader	Beschrijving
`Authorization`	Vereist. Hiermee geeft u het autorisatieschema, de accountnaam en de handtekening. Zie Aanvragen voor Azure Storage autoriseren voor meer informatie.
`Date` of `x-ms-date`	Vereist. Geef de Coordinated Universal Time (UTC) op voor de aanvraag. Zie Aanvragen voor Azure Storage autoriseren voor meer informatie.
`x-ms-version`	Vereist voor alle geautoriseerde aanvragen, optioneel voor anonieme aanvragen. Hiermee geeft u de versie van de bewerking te gebruiken voor deze aanvraag. Zie Versiebeheer voor de Azure Storage-services voor meer informatie.
`Range`	Optioneel. Hiermee geeft u het bereik van bytes waarover bereik, inclusief. Als `Range` u dit weglaat, worden alle bereiken voor de blob geretourneerd.
`x-ms-range`	Optioneel. Hiermee geeft u het bereik van bytes waarover bereik, inclusief. Als zowel `Range` als `x-ms-range` zijn opgegeven, gebruikt de service de waarde van `x-ms-range`. Zie De bereikheader opgeven voor Blob Storage-bewerkingen voor meer informatie.
`x-ms-lease-id:<ID>`	Optioneel. Als deze header is opgegeven, wordt de bewerking alleen uitgevoerd als aan beide van de volgende voorwaarden wordt voldaan: - De lease van de blob is momenteel actief. - De lease-id die in de aanvraag is opgegeven, komt overeen met de lease-id van de blob. Als deze header is opgegeven en aan een van de voorwaarden niet wordt voldaan, mislukt de aanvraag en mislukt de bewerking met statuscode 412 (voorwaarde mislukt).
`x-ms-previous-snapshot-url`	Optioneel, versie 2019-07-07 en hoger. De `previous-snapshot-url` geeft aan dat het antwoord alleen pagina's bevat die zijn gewijzigd tussen de doel-blob en momentopname die zich op de opgegeven URI bevinden. Gewijzigde pagina's bevatten zowel bijgewerkte als gewiste pagina's. De doel-blob kan een momentopname zijn, zolang de momentopname die door deze header is opgegeven, de oudere van de twee is. Opmerking: incrementele momentopnamen worden momenteel alleen ondersteund voor blobs die zijn gemaakt op of na 1 januari 2016 en dat deze header alleen mag worden gebruikt in scenario's met beheerde schijven. Gebruik anders de `prevsnapshot` parameter .
`x-ms-client-request-id`	Optioneel. Biedt een door de client gegenereerde, ondoorzichtige waarde met een limiet van 1 kibibyte (KiB), die wordt vastgelegd in de analyselogboeken wanneer Logboekregistratie van Azure Opslaganalyse is ingeschakeld. We raden u ten zeerste aan deze header te gebruiken wanneer u activiteiten aan de clientzijde correleert met aanvragen die door de server worden ontvangen. Zie Over Opslaganalyse logboekregistratie en Azure-logboekregistratie: logboeken gebruiken om Azure Storage-aanvragen bij te houden voor meer informatie.

Deze bewerking ondersteunt ook het gebruik van voorwaardelijke kopteksten om paginabereiken op te halen, alleen als aan een opgegeven voorwaarde wordt voldaan. Zie Voorwaardelijke headers opgeven voor Blob Storage-bewerkingen voor meer informatie.

Aanvraagbody

Geen.

Antwoord

Het antwoord bevat een HTTP-statuscode, een set antwoordheaders en de hoofdtekst van het antwoord.

Statuscode

Een geslaagde bewerking retourneert statuscode 200 (OK).

Zie Status- en foutcodes voor meer informatie over statuscodes.

Antwoordheaders

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

Syntax	Description
`Last-Modified`	De datum/tijd waarop de blob het laatst is gewijzigd. De datumnotatie volgt RFC 1123. Elke bewerking die de blob wijzigt, inclusief een update van de metagegevens of eigenschappen van de blob, wijzigt de laatste wijzigingstijd van de blob.
`ETag`	Bevat een waarde die de client kan gebruiken om de bewerking voorwaardelijk uit te voeren. Als de aanvraagversie 2011-08-18 of hoger is, staat de ETag-waarde tussen aanhalingstekens.
`x-ms-blob-content-length`	De grootte van de blob in bytes.
`x-ms-request-id`	Identificeert op unieke wijze de aanvraag die is gedaan en deze kan worden gebruikt om problemen met de aanvraag op te lossen. Zie Problemen met API-bewerkingen oplossen voor meer informatie.
`x-ms-version`	Geeft de Blob Storage-versie aan die is gebruikt om de aanvraag uit te voeren. Deze header wordt geretourneerd voor aanvragen die zijn gedaan op basis van versie 2009-09-19 en hoger. Deze header wordt ook geretourneerd voor anonieme aanvragen zonder een opgegeven versie als de container is gemarkeerd voor openbare toegang met Blob Storage versie 2009-09-19.
`Date`	Een UTC-datum/tijd-waarde die wordt gegenereerd door de service, die de tijd aangeeft waarop het antwoord is gestart.
`x-ms-client-request-id`	Kan worden gebruikt 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 en de waarde niet meer dan 1024 zichtbare ASCII-tekens bevat. Als de `x-ms-client-request-id` header niet aanwezig is in de aanvraag, is deze niet aanwezig in het antwoord.

Hoofdtekst van de reactie

De antwoordtekst bevat een lijst met niet-overlappende, geldige paginabereiken, gesorteerd op het vergroten van het adrespaginabereik. De indeling van de antwoordtekst is als volgt:

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

Als de volledige set pagina's van de blob is gewist, bevat de antwoordtekst geen paginabereiken.

Als de prevsnapshot parameter is opgegeven, bevat het antwoord alleen de pagina's die verschillen tussen de doelmomentopname of blob en de vorige momentopname. De geretourneerde pagina's bevatten beide pagina's die zijn bijgewerkt of gewist. De indeling van deze antwoordtekst is als volgt:

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

Als de volledige set pagina's van de blob is gewist en de prevsnapshot parameter niet is opgegeven, bevat de antwoordtekst geen paginabereiken.

Als de maxresults parameter is opgegeven, bevat het antwoord alleen het opgegeven aantal bereiken met een vervolgtoken in de NextMarker tag. Het vervolgtoken is leeg als er geen bereiken meer in behandeling zijn, of anders bevat het een ondoorzichtige waarde die moet worden verzonden als een marker parameter in de volgende aanvraag. De indeling van deze antwoordtekst is als volgt:

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <ClearRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </ClearRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>
   <NextMarker/>
</PageList>

Autorisatie

Autorisatie is vereist bij het aanroepen van een bewerking voor gegevenstoegang in Azure Storage. U kunt de Get Page Ranges bewerking autoriseren zoals hieronder wordt beschreven.

Azure Storage ondersteunt het gebruik van Microsoft Entra ID om aanvragen voor blobgegevens te autoriseren. Met Microsoft Entra ID kunt u op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC) gebruiken om machtigingen te verlenen aan een beveiligingsprincipal. De beveiligingsprincipal kan een gebruiker, groep, toepassingsservice-principal of door Azure beheerde identiteit zijn. De beveiligingsprincipal wordt geverifieerd door Microsoft Entra ID om een OAuth 2.0-token te retourneren. Het token kan vervolgens worden gebruikt om een aanvraag voor de Blob-service te autoriseren.

Zie Toegang tot blobs autoriseren met behulp van Microsoft Entra ID voor meer informatie over autorisatie met behulp van Microsoft Entra ID.

Machtigingen

Hieronder vindt u de RBAC-actie die nodig is voor een Microsoft Entra gebruiker, groep of service-principal om de Get Page Ranges bewerking aan te roepen, en de ingebouwde Azure RBAC-rol met de minste bevoegdheden die deze actie omvat:

Azure RBAC-actie:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Ingebouwde rol met minimale bevoegdheden:Lezer voor opslagblobgegevens

Zie Een Azure-rol toewijzen voor toegang tot blobgegevens voor meer informatie over het toewijzen van rollen met behulp van Azure RBAC.

Een Shared Access Signature (SAS) biedt beveiligde gedelegeerde toegang tot resources in een opslagaccount. Met een SAS hebt u gedetailleerde controle over hoe een client toegang heeft tot gegevens. U kunt opgeven tot welke resource de client toegang heeft, welke machtigingen ze hebben voor deze resources en hoe lang de SAS geldig is.

De Get Page Ranges bewerking ondersteunt drie typen handtekeningen voor gedeelde toegang: SAS voor gebruikersdelegatie, service-SAS en account-SAS.

Als best practice voor beveiliging raden we u aan Microsoft Entra referenties te gebruiken in plaats van de opslagaccountsleutel, die gemakkelijker kan worden aangetast. Als voor uw toepassingsontwerp handtekeningen voor gedeelde toegang zijn vereist, gebruikt u indien mogelijk Microsoft Entra referenties om een SAS voor gebruikersdelegatie te maken.

Wanneer toegang tot gedeelde sleutel niet is toegestaan voor het opslagaccount, is een service-SAS-token of een ACCOUNT-SAS-token niet toegestaan op een aanvraag voor Blob Storage. Zie Begrijpen hoe het niet toewijzen van gedeelde sleutel van invloed is op SAS-tokens voor meer informatie.

SAS voor gebruikersdelegering

Een SAS voor gebruikersdelegatie wordt beveiligd met Microsoft Entra referenties en ook met de machtigingen die zijn opgegeven voor de SAS.

Voor het aanroepen van de Get Page Ranges bewerking met behulp van een SAS-token dat is gedelegeerd aan een container of blob-resource, is de machtiging Lezen (r) vereist als onderdeel van het SAS-token voor gebruikersdelegatie.

Zie Een SAS voor gebruikersdelegering maken voor meer informatie over de SAS voor gebruikersdelegatie.

Service-SAS

Een service-SAS wordt beveiligd met de sleutel van het opslagaccount. Een service-SAS delegeert toegang tot een resource in één Azure Storage-service, zoals blobopslag.

Voor het aanroepen van de Get Page Ranges bewerking met behulp van een SAS-token dat is gedelegeerd aan een container of blobresource, is de machtiging Lezen (r) vereist als onderdeel van het service-SAS-token.

Zie Een service-SAS maken voor meer informatie over de service-SAS.

Account-SAS

Een account-SAS wordt beveiligd met de sleutel van het opslagaccount. Een account-SAS delegeert toegang tot resources in een of meer van de opslagservices. Alle bewerkingen die beschikbaar zijn via een service- of gebruikersdelegatie-SAS zijn ook beschikbaar via een account-SAS.

In de volgende tabel ziet u het ondertekende resourcetype en de ondertekende machtigingen die moeten worden opgegeven bij het delegeren van toegang:

Bewerking	Ondertekende service	Ondertekend resourcetype	Ondertekende machtiging
Paginabereiken ophalen	Blob (b)	Object (o)	Lezen (r)

Zie Een account-SAS maken voor meer informatie over de account-SAS.

Opmerkingen

De begin- en eind-byte offsets voor elk paginabereik zijn inclusief.

In een zeer gefragmenteerde pagina-blob met een groot aantal schrijfbewerkingen kan een Get Page Ranges aanvraag mislukken vanwege een interne servertime-out. Toepassingen die bereiken van een pagina-blob met een groot aantal schrijfbewerkingen ophalen, moeten een subset van paginabereiken tegelijk ophalen.

Vanaf versie 2015-07-08 kunt u aanroepen Get Page Ranges met de prevsnapshot parameter om de pagina's te retourneren die verschillen tussen de basis-blob en een momentopname, of tussen twee momentopnamen van de blob. Met deze paginaverschillen kunt u een incrementele momentopname van een pagina-blob opslaan. Incrementele momentopnamen zijn een rendabele manier om back-ups te maken van schijven van virtuele machines als u uw eigen back-upoplossing wilt implementeren.

Aanroepen Get Page Ranges met de prevsnapshot parameter retourneert pagina's die zijn bijgewerkt of gewist sinds de momentopname die is opgegeven door prevsnapshot is gemaakt. U kunt vervolgens de pagina's kopiëren die worden geretourneerd naar een blob van een back-uppagina in een ander opslagaccount met behulp van Pagina plaatsen.

Vanaf versie 2019-07-07 kunt u de x-ms-previous-snapshot-url header gebruiken om momentopnamen in beheerde schijfaccounts op te geven voor incrementele momentopnamen. Als u geen beheerde schijven gebruikt, gebruikt u de prevsnapshot queryparameter.

Bepaalde bewerkingen op een blob mislukken Get Page Ranges wanneer deze wordt aangeroepen om een incrementele momentopname te retourneren. Get Pages Ranges mislukt met foutcode 409 (conflict) als deze wordt aangeroepen op een blob die het doel was van een Put Blob - of Copy Blob-aanvraag nadat de momentopname is gemaakt die is opgegeven door prevsnapshot . Als het doel van de Get Page Ranges bewerking zelf een momentopname is, slaagt de aanroep zolang de momentopname die is opgegeven door prevsnapshot ouder is en er geen Put Blob of-bewerking Copy Blob is aangeroepen in het interval tussen de twee momentopnamen.

Notitie

Incrementele momentopnamen worden momenteel alleen ondersteund voor blobs die zijn gemaakt op of na 1 januari 2016. Pogingen om deze functie op een oudere blob te gebruiken, leiden tot de BlobOverwritten fout HTTP-foutcode 409 (conflict).

Zie ook

Aanvragen voor Azure Storage autoriseren
Status en foutcodes
Time-outs instellen voor Blob Storage-bewerkingen