Get Page Ranges

Artikel
02/07/2024

Der Vorgang Seitenbereiche abrufen gibt die Liste der gültigen Seitenbereiche für ein Seitenblob oder Momentaufnahme eines Seitenblobs zurück.

Anforderung

Die Anforderung "Seitenbereiche abrufen" kann wie folgt erstellt werden. Es wird empfohlen, HTTPS zu verwenden. Ersetzen Sie myaccount durch den Namen Ihres Speicherkontos:

GET-Methodenanforderungs-URI	HTTP-Version
`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

Emulierter Speicherdienst-URI

Wenn Sie eine Anforderung für den emulierten Speicherdienst stellen, geben Sie den Hostnamen des Emulators und Azure Blob Storage Port als 127.0.0.1:1000 an, gefolgt vom Namen des emulierten Speicherkontos:

GET-Methodenanforderungs-URI	HTTP-Version
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=pagelist`	HTTP/1.1

Weitere Informationen finden Sie unter Verwenden des Azure-Speicheremulators für Entwicklung und Tests.

URI-Parameter

Die folgenden zusätzlichen Parameter können für den Anforderungs-URI angegeben werden:

Parameter	BESCHREIBUNG
`marker`	Optional, Version 2020-10-02 und höher. Gibt den Teil der Bereiche an, der mit dem nächsten GetPageRanges-Vorgang zurückgegeben werden soll. Der Vorgang gibt einen Markerwert innerhalb des Antworttexts zurück, wenn die zurückgegebenen Bereiche unvollständig waren. Der Markerwert kann dann in einem nachfolgenden Aufruf verwendet werden, um den nächsten Satz von Bereichen anzufordern. Der Markerwert ist für den Client nicht transparent.
`maxresults`	Optional, Version 2020-10-02 und höher. Gibt die maximale Anzahl von Seitenbereichen an, die zurückgegeben werden sollen. Wenn die Anforderung einen Wert über 10.000 angibt, gibt der Server bis zu 10.000 Elemente zurück. Wenn zusätzliche Ergebnisse zurückgegeben werden sollen, gibt der Dienst ein Fortsetzungstoken im Antwortelement NextMarker zurück. Wenn Sie `maxresults` auf einen Wert festlegen, der kleiner oder gleich Null ist, wird der Fehlerantwortcode 400 (Ungültige Anforderung) angezeigt.
`snapshot`	Optional. Ein undurchsichtiger DateTime-Wert, der, wenn vorhanden, das Blob angibt, aus dem Informationen abgerufen Momentaufnahme werden sollen. Weitere Informationen zum Arbeiten mit Blobmomentaufnahmen finden Sie unter Erstellen einer Momentaufnahme eines Blobs.
`timeout`	Optional. Ausgedrückt in Sekunden. Weitere Informationen finden Sie unter Festlegen von Timeouts für Blob Storage-Vorgänge.
`prevsnapshot`	Optional, Version 2015-07-08 und höher. Ein DateTime-Wert, der angibt, dass die Antwort nur Seiten enthält, die zwischen dem Zielblob und dem vorherigen Momentaufnahme geändert wurden. Geänderte Seiten umfassen sowohl aktualisierte als auch gelöschte Seiten. Das Zielblob kann ein Momentaufnahme sein, solange die von `prevsnapshot` angegebene Momentaufnahme die ältere der beiden ist. Hinweis: Inkrementelle Momentaufnahmen werden derzeit nur für Blobs unterstützt, die am oder nach dem 1. Januar 2016 erstellt wurden.

Anforderungsheader

In der folgenden Tabelle werden erforderliche und optionale Anforderungsheader beschrieben.

Anforderungsheader	BESCHREIBUNG
`Authorization`	Erforderlich. Gibt das Autorisierungsschema, den Kontonamen und die Signatur an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
`Date` oder `x-ms-date`	Erforderlich. Gibt die koordinierte Weltzeit (Coordinated Universal Time, UTC) für die Anforderung an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
`x-ms-version`	Erforderlich für alle autorisierten Anforderungen, optional für anonyme Anforderungen. Gibt die Version des für die Anforderung zu verwendenden Vorgangs an. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste.
`Range`	Optional. Gibt den Bereich von Bytes an, über den Bereiche aufgelistet werden sollen (jeweils einschließlich). Wenn `Range` nicht angegeben wird, werden alle Bereiche für das Blob zurückgegeben.
`x-ms-range`	Optional. Gibt den Bereich von Bytes an, über den Bereiche aufgelistet werden sollen (jeweils einschließlich). Wenn `Range` und `x-ms-range` angegeben werden, verwendet der Dienst den Wert `x-ms-range`. Weitere Informationen finden Sie unter Angeben des Bereichsheaders für Blob Storage-Vorgänge .
`x-ms-lease-id:<ID>`	Optional. Wenn dieser Header angegeben ist, wird der Vorgang nur ausgeführt, wenn beide der folgenden Bedingungen erfüllt sind: – Die Lease des Blobs ist derzeit aktiv. – Die in der Anforderung angegebene Lease-ID entspricht der Lease-ID des Blobs. Wenn dieser Header angegeben wird und beide Bedingung nicht erfüllt ist, schlägt die Anforderung fehl, und der Vorgang schlägt mit status Code 412 (Vorbedingung fehlgeschlagen) fehl.
`x-ms-previous-snapshot-url`	Optional, Version 2019-07-07 und höher. Gibt `previous-snapshot-url` an, dass die Antwort nur Seiten enthält, die zwischen dem Zielblob und Momentaufnahme geändert wurden, die sich am angegebenen URI befinden. Geänderte Seiten umfassen sowohl aktualisierte als auch gelöschte Seiten. Das Zielblob kann ein Momentaufnahme sein, solange die in diesem Header angegebene Momentaufnahme die ältere der beiden ist. Hinweis: Inkrementelle Momentaufnahmen werden derzeit nur für Blobs unterstützt, die am oder nach dem 1. Januar 2016 erstellt wurden, und dass dieser Header nur in Szenarien mit verwalteten Datenträgern verwendet werden sollte. Verwenden Sie andernfalls den `prevsnapshot` -Parameter.
`x-ms-client-request-id`	Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (KiB) bereit, der in den Analyseprotokollen aufgezeichnet wird, wenn die Azure Storage Analytics Protokollierung aktiviert ist. Es wird dringend empfohlen, diesen Header zu verwenden, wenn Sie clientseitige Aktivitäten mit Anforderungen korrelieren, die vom Server empfangen werden. Weitere Informationen finden Sie unter Informationen zu Storage Analytics Protokollierung und Azure-Protokollierung: Verwenden von Protokollen zum Nachverfolgen von Azure Storage-Anforderungen.

Dieser Vorgang unterstützt zudem die Verwendung von bedingten Headern zum Abrufen von Seitenbereichen nur dann, wenn eine bestimmte Bedingung erfüllt ist. Weitere Informationen finden Sie unter Angeben von bedingten Headern für Blob Storage-Vorgänge.

Anforderungstext

Keine.

Antwort

Die Antwort enthält den HTTP-Statuscode, einen Satz von Antwortheadern und den Antworttext.

Statuscode

Bei einem erfolgreichen Vorgang wird der Statuscode 200 (OK) zurückgegeben.

Weitere Informationen zu status Codes finden Sie unter Status- und Fehlercodes.

Antwortheader

Die Antwort für diesen Vorgang umfasst die folgenden Header. Die Antwort kann außerdem weitere HTTP-Standardheader enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Syntax	BESCHREIBUNG
`Last-Modified`	Datum/Uhrzeit der letzten Änderung des BLOB. Das Datumsformat entspricht RFC 1123. Durch jeden Vorgang, der das BLOB ändert, einschließlich eines Updates der Metadaten oder Eigenschaften des BLOB, wird der Zeitpunkt der letzten BLOB-Änderung aktualisiert.
`ETag`	Enthält einen Wert, den der Client verwenden kann, um den Vorgang bedingt auszuführen. Wenn die Anforderungsversion 2011-08-18 oder höher ist, wird der ETag-Wert in Anführungszeichen eingeschlossen.
`x-ms-blob-content-length`	Die Größe des Blobs in Byte.
`x-ms-request-id`	Identifiziert eindeutig die Anforderung, die gestellt wurde, und kann zur Problembehandlung für die Anforderung verwendet werden. Weitere Informationen finden Sie unter Problembehandlung bei API-Vorgängen.
`x-ms-version`	Gibt die Blob Storage-Version an, die zum Ausführen der Anforderung verwendet wurde. Dieser Header wird für Anforderungen zurückgegeben, die für Version 2009-09-19 und höher vorgenommen wurden. Dieser Header wird auch für anonyme Anforderungen ohne angegebene Version zurückgegeben, wenn der Container mit Blob Storage-Version 2009-09-19 für den öffentlichen Zugriff markiert wurde.
`Date`	Ein UTC-Datums-/Uhrzeitwert, der vom Dienst generiert wird, der die Uhrzeit angibt, zu der die Antwort initiiert wurde.
`x-ms-client-request-id`	Kann verwendet werden, um Anforderungen und entsprechende Antworten zu behandeln. Der Wert dieses Headers ist gleich dem Wert des `x-ms-client-request-id` Headers, wenn er in der Anforderung vorhanden ist und der Wert nicht mehr als 1.024 sichtbare ASCII-Zeichen enthält. Wenn der `x-ms-client-request-id` Header in der Anforderung nicht vorhanden ist, ist er in der Antwort nicht vorhanden.

Antworttext

Der Antworttext enthält eine Liste von nicht überlappenden, gültigen Seitenbereichen, sortiert nach Erhöhung des Adressseitenbereichs. Der Antworttext weist das folgende Format auf:

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

Wenn der gesamte Seitensatz des Blobs gelöscht wurde, enthält der Antworttext keine Seitenbereiche.

Wenn der prevsnapshot Parameter angegeben wurde, enthält die Antwort nur die Seiten, die sich zwischen dem Ziel-Momentaufnahme oder Blob und dem vorherigen Momentaufnahme unterscheiden. Die zurückgegebenen Seiten enthalten beide Seiten, die aktualisiert oder gelöscht wurden. Das Format dieses Antworttexts ist wie folgt:

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

Wenn der gesamte Seitensatz des Blobs gelöscht und der prevsnapshot Parameter nicht angegeben wurde, enthält der Antworttext keine Seitenbereiche.

Wenn der maxresults Parameter angegeben wurde, enthält die Antwort nur die angegebene Anzahl von Bereichen mit einem Fortsetzungstoken im NextMarker Tag. Das Fortsetzungstoken ist leer, wenn keine weiteren ausstehenden Bereiche vorhanden sind, oder es enthält einen undurchsichtigen Wert, der als marker Parameter in der nächsten Anforderung gesendet werden muss. Das Format dieses Antworttexts ist wie folgt:

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

Authorization

Beim Aufrufen eines Datenzugriffsvorgangs in Azure Storage ist eine Autorisierung erforderlich. Sie können den Get Page Ranges Vorgang wie unten beschrieben autorisieren.

Azure Storage unterstützt die Verwendung von Microsoft Entra ID zum Autorisieren von Anforderungen an Blobdaten. Mit Microsoft Entra ID können Sie die rollenbasierte Zugriffssteuerung (Azure RBAC) von Azure verwenden, um einem Sicherheitsprinzipal Berechtigungen zu erteilen. Der Sicherheitsprinzipal kann ein Benutzer, eine Gruppe, ein Anwendungsdienstprinzipal oder eine verwaltete Azure-Identität sein. Der Sicherheitsprinzipal wird von Microsoft Entra ID authentifiziert, um ein OAuth 2.0-Token zurückzugeben. Das Token kann anschließend zum Autorisieren einer Anforderung an den Blob-Dienst verwendet werden.

Weitere Informationen zur Autorisierung mit Microsoft Entra ID finden Sie unter Autorisieren des Zugriffs auf Blobs mit Microsoft Entra ID.

Berechtigungen

Im Folgenden sind die RBAC-Aktion aufgeführt, die für einen Microsoft Entra Benutzer, Eine Gruppe oder einen Dienstprinzipal erforderlich ist, um den Get Page Ranges Vorgang aufzurufen, und die integrierte Azure RBAC-Rolle mit den geringsten Berechtigungen, die diese Aktion enthält:

Azure RBAC-Aktion:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Integrierte Rolle mit den geringsten Berechtigungen:Speicherblobdatenleser

Weitere Informationen zum Zuweisen von Rollen mithilfe von Azure RBAC finden Sie unter Zuweisen einer Azure-Rolle für den Zugriff auf Blobdaten.

Eine SAS (Shared Access Signature) bietet sicheren delegierten Zugriff auf Ressourcen in einem Speicherkonto. Mit einer SAS haben Sie eine präzise Kontrolle darüber, wie ein Client auf Daten zugreifen kann. Sie können angeben, auf welche Ressource der Client zugreifen darf, welche Berechtigungen er für diese Ressourcen hat und wie lange die SAS gültig ist.

Der Get Page Ranges Vorgang unterstützt drei Arten von Shared Access Signaturen: Benutzerdelegierungs-SAS, Dienst-SAS und Konto-SAS.

Als bewährte Sicherheitsmethode wird empfohlen, Microsoft Entra Anmeldeinformationen anstelle des Speicherkontoschlüssels zu verwenden, der leichter kompromittiert werden kann. Wenn Ihr Anwendungsentwurf Shared Access Signatures erfordert, verwenden Sie nach Möglichkeit Microsoft Entra Anmeldeinformationen, um eine SAS für die Benutzerdelegierung zu erstellen.

Wenn der Zugriff auf freigegebene Schlüssel für das Speicherkonto nicht zulässig ist, wird ein SAS-Diensttoken oder ein Konto-SAS-Token für eine Anforderung an Blob Storage nicht zulässig. Weitere Informationen finden Sie unter Grundlegendes dazu, wie sich das Aufheben der Zuordnung von freigegebenem Schlüssel auf SAS-Token auswirkt.

SAS für die Benutzerdelegierung

Eine Benutzerdelegierungs-SAS wird mit Microsoft Entra Anmeldeinformationen und auch durch die für die SAS angegebenen Berechtigungen geschützt.

Für das Aufrufen des Get Page Ranges Vorgangs mithilfe eines SAS-Tokens, das an einen Container oder eine Blobressource delegiert wurde, ist die Berechtigung Lesen (r) als Teil des SAS-Tokens der Benutzerdelegierung erforderlich.

Weitere Informationen zur Benutzerdelegierungs-SAS finden Sie unter Erstellen einer Benutzerdelegierungs-SAS.

Dienst-SAS

Eine Dienst-SAS wird mit dem Speicherkontoschlüssel geschützt. Eine Dienst-SAS delegiert den Zugriff auf eine Ressource in einem einzelnen Azure Storage-Dienst, z. B. Blob Storage.

Für das Aufrufen des Get Page Ranges Vorgangs mit einem SAS-Token, das an einen Container oder eine Blobressource delegiert wurde, ist die Leseberechtigung (r) als Teil des Dienst-SAS-Tokens erforderlich.

Weitere Informationen zur Dienst-SAS finden Sie unter Erstellen einer Dienst-SAS.

Konto-SAS

Eine Konto-SAS wird mit dem Speicherkontoschlüssel geschützt. Eine Konto-SAS delegiert den Zugriff auf Ressourcen in einem oder mehreren der Speicherdienste. Alle Vorgänge, die über eine Dienst-SAS oder eine SAS für die Benutzerdelegierung verfügbar sind, sind auch über eine Konto-SAS verfügbar.

In der folgenden Tabelle sind der signierte Ressourcentyp und die signierten Berechtigungen angegeben, die beim Delegieren des Zugriffs angegeben werden sollen:

Vorgang	Signierter Dienst	Signierter Ressourcentyp	Signierte Berechtigung
Get Page Ranges	Blob (b)	Objekt (o)	Lesen (r)

Weitere Informationen zur Konto-SAS finden Sie unter Erstellen einer Konto-SAS.

Der Get Page Ranges Vorgang unterstützt die Freigabeschlüsselautorisierung. Die Autorisierung mit Kontoschlüsseln wird für die meisten Szenarien nicht empfohlen, da sie weniger sicher ist.

Microsoft empfiehlt, die Autorisierung mit freigegebenem Schlüssel für das Speicherkonto nach Möglichkeit nicht zu verwenden. Weitere Informationen finden Sie unter Verhindern der Autorisierung mit gemeinsam verwendetem Schlüssel.

Hinweise

Die Start- und Endbyteoffsets für die einzelnen Seitenbereiche sind inklusiv.

In einem stark fragmentierten Seiten-BLOB mit einer hohen Anzahl von Schreibvorgängen kann eine Get Page Ranges-Anforderung zu einem Fehler aufgrund eines internen Servertimeouts führen. Anwendungen, die Bereiche eines Seiten-BLOB mit vielen Schreibvorgängen abrufen, sollten immer jeweils eine Teilmenge der Seitenbereiche abrufen.

Ab Version 2015-07-08 können Sie mit dem prevsnapshot -Parameter aufrufenGet Page Ranges, um die Seiten zurückzugeben, die sich zwischen dem Basisblob und einem Momentaufnahme oder zwischen zwei Momentaufnahmen des Blobs unterscheiden. Mithilfe dieser Seitenunterschiede können Sie eine inkrementelle Momentaufnahme eines Seitenblobs speichern. Inkrementelle Momentaufnahmen sind eine kostengünstige Möglichkeit zum Sichern von Datenträgern virtueller Computer, wenn Sie Ihre eigene Sicherungslösung implementieren möchten.

Das Aufrufen Get Page Ranges mit dem prevsnapshot Parameter gibt Seiten zurück, die aktualisiert oder gelöscht wurden, seit die von angegebene prevsnapshot Momentaufnahme übernommen wurde. Anschließend können Sie die Seiten, die in ein Sicherungsseitenblob zurückgegeben werden, mithilfe von Put Page in ein anderes Speicherkonto kopieren.

Ab Version 2019-07-07 können Sie den x-ms-previous-snapshot-url Header verwenden, um Momentaufnahmen in Konten mit verwalteten Datenträgern für inkrementelle Momentaufnahmen anzugeben. Wenn Sie keine verwalteten Datenträger verwenden, verwenden Sie den prevsnapshot Abfrageparameter.

Bei bestimmten Vorgängen für ein Blob tritt Get Page Ranges ein Fehler auf, wenn es aufgerufen wird, um eine inkrementelle Momentaufnahme zurückzugeben. Get Pages Rangesschlägt mit dem Fehlercode 409 (Konflikt) fehl, wenn es für ein Blob aufgerufen wird, das das Ziel einer Put Blob- oder Copy Blob-Anforderung war, nachdem die von prevsnapshot angegebene Momentaufnahme verwendet wurde. Wenn das Ziel des Get Page Ranges Vorgangs selbst ein Momentaufnahme ist, ist der Aufruf erfolgreich, solange die von prevsnapshot angegebene Momentaufnahme älter ist und kein Vorgang oder Copy Blob vorgang Put Blob im Intervall zwischen den beiden Momentaufnahmen aufgerufen wurde.

Hinweis

Inkrementelle Momentaufnahmen werden derzeit nur für Blobs unterstützt, die am oder nach dem 1. Januar 2016 erstellt wurden. Versuche, dieses Feature in einem älteren Blob zu verwenden, führen zu dem Fehler, der BlobOverwritten HTTP-Fehlercode 409 (Konflikt) ist.

Weitere Informationen

Autorisieren von Anforderungen an Azure Storage
Status- und Fehlercodes
Festlegen von Timeouts für Blob Storage-Vorgänge