Get Block List

Der Get Block List-Vorgang ruft die Liste der Blöcke ab, die als Teil eines Block-BLOB hochgeladen wurden.

Für ein BLOB werden zwei Blockierlisten verwaltet:

  • Commit-Blockliste: Die Liste der Blöcke, für die erfolgreich ein Commit für ein bestimmtes Blob mit Put Block Listausgeführt wurde.

  • Blockliste ohneCommitted: Die Liste der Blöcke, die mit Put Blockfür ein Blob hochgeladen wurden, für die jedoch noch kein Commit ausgeführt wurde. Diese Blöcke werden in Azure in Verbindung mit einem BLOB gespeichert, sind aber noch nicht Teil des BLOB.

Sie können Get Block List aufrufen, um die Liste der Blöcke mit ausgeführtem Commit, die Liste der Blöcke ohne ausgeführten Commit oder beide zurückzugeben. Sie können diesen Vorgang auch aufrufen, um die Liste der Blöcke mit ausgeführtem Commit für eine Momentaufnahme abzurufen.

Anforderung

Die Get Block List-Anforderung kann wie folgt erstellt werden. HTTPS wird empfohlen. Ersetzen Sie myaccount durch den Namen Ihres Speicherkontos:

Anforderungs-URI für GET-Methode HTTP-Version
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&snapshot=<DateTime>

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&versionid=<DateTime>
HTTP/1.1

Emulierter Speicherdienst-URI

Wenn Sie eine Anforderung für den emulierten Speicherdienst ausführen, geben Sie den Emulatorhostnamen und den Port des Blob-Diensts mit 127.0.0.1:10000 an, gefolgt vom Namen des emulierten Speicherkontos:

Anforderungs-URI für GET-Methode HTTP-Version
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=blocklist HTTP/1.1

Weitere Informationen finden Sie unter Verwenden der Azure Storage Emulator für Entwicklung und Tests.

URI-Parameter

Im Anforderungs-URI können die folgenden zusätzlichen Parameter angegeben werden.

URI-Parameter BESCHREIBUNG
snapshot Optional. Der Momentaufnahmeparameter ist ein nicht transparenter DateTime-Wert, der ggf. die abzurufende BLOB-Liste angibt. Weitere Informationen zum Arbeiten mit Blobmomentaufnahmen finden Sie unter Erstellen einer Momentaufnahme eines Blobs.
versionid Optional für die Versionen 2019-12-12 und höher. Der versionid-Parameter ist ein nicht transparenter DateTime Wert, der, sofern vorhanden, die Version des abzurufenden Blobs angibt.
blocklisttype Gibt an, ob die Liste der Blöcke mit ausgeführtem Commit, die Liste der Blöcke ohne ausgeführten Commit oder beide Listen zusammen zurückgegeben werden. Gültige Werte sind committed, uncommitted oder all. Wenn Sie diesen Parameter nicht angeben, gibt Get Block List die Liste der Blöcke mit ausgeführtem Commit zurück.
timeout Optional. Der timeout-Parameter wird in Sekunden angegeben. Weitere Informationen finden Sie unter Festlegen von Timeouts für Blobdienstvorgänge.

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 Storage Services.
x-ms-lease-id:<ID> Optional. Bei Angabe dieses Headers wird der Vorgang nur ausgeführt, wenn die beiden folgenden Bedingungen erfüllt sind:

– Die Lease des Blobs ist derzeit aktiv.
– Die in der Anforderung angegebene Lease-ID stimmt mit der des Blobs überein.

Wenn der Header angegeben ist und beide Bedingungen nicht erfüllt sind, schlägt die Anforderung fehl, und der Vorgang schlägt mit dem Statuscode 412 (Vorbedingung nicht erfüllt) fehl.
x-ms-client-request-id Optional. Stellt einen vom Client generierten, nicht transparenten Wert mit einem Zeichenlimit von 1 KiB bereit, der in den Analyseprotokollen aufgezeichnet wird, wenn die Protokollierung der Speicheranalyse aktiviert ist. Es wird empfohlen, diesen Header für das Korrelieren clientseitiger Aktivitäten mit vom Server empfangenen Anforderungen zu verwenden. Weitere Informationen finden Sie unter Informationen Storage Analytics-Protokollierung und Azure-Protokollierung: Verwenden von Protokollen zum Nachverfolgen Storage Anforderungen.

Dieser Vorgang unterstützt zudem die Verwendung von bedingten Headern zum Ausführen des Vorgangs, wobei eine bestimmte Bedingung erfüllt sein muss. Weitere Informationen finden Sie unter Specifying Conditional Headers for Blob Service Operations (Angeben von bedingten Headern für Vorgänge des Blob-Diensts).

Anforderungstext

Keine.

Beispiel für eine Anforderung

Durch den folgenden Beispielanforderungs-URI wird die Liste der Blöcke mit ausgeführtem Commit für ein BLOB mit dem Namen MOV1.avi zurückgegeben:

GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=committed HTTP/1.1  

Der folgende Beispielanforderungs-URI gibt sowohl die Liste der Blöcke mit ausgeführtem Commit als auch die Liste der Blöcke ohne ausgeführten Commit zurück:

GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=all HTTP/1.1  

Der folgende Beispielanforderungs-URI gibt die Liste der Blöcke mit ausgeführtem Commit für eine Momentaufnahme zurück. Beachten Sie, dass eine Momentaufnahme nur aus Blöcken mit ausgeführtem Commit besteht, sodass ihr keine Blöcke ohne ausgeführten Commit zugeordnet sind.

GET http://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&snapshot=2009-09-30T20%3a11%3a15.2735974Z  

Antwort

Die Antwort enthält den HTTP-Statuscode, einen Satz von Antwortheadern sowie einen Antworttext mit der Liste der Blöcke.

Statuscode

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

Informationen zu Statuscodes 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.

Antwortheader BESCHREIBUNG
Last-Modified Datum/Uhrzeit der letzten Änderung des BLOB. Das Datumsformat entspricht RFC 1123. Weitere Informationen finden Sie unter Darstellung von Date-Time-Werten in Headern. Dieser Header wird zurückgegeben, wenn das BLOB Blöcke mit ausgeführtem Commit aufweist.

Durch jeden Vorgang, der das BLOB ändert, einschließlich von Updates der Metadaten oder Eigenschaften des BLOB, wird der Zeitpunkt der letzten Änderung des BLOB aktualisiert.
ETag Das ETag für das BLOB. Dieser Header wird zurückgegeben, wenn das BLOB Blöcke mit ausgeführtem Commit aufweist.
Content-Type Der MIME-Inhaltstyp des BLOB. Der Standardwert ist application/xml.
x-ms-blob-content-length Die Größe des Blobs in Byte.
x-ms-request-id Dieser Header identifiziert die erfolgte Anforderung eindeutig und kann für die Problembehandlung der Anforderung verwendet werden. Weitere Informationen finden Sie unter Problembehandlung bei API-Vorgängen.
x-ms-version Gibt die Version des Blob-Diensts an, der zum Ausführen der Abfrage verwendet wird. Dieser Header wird für Anforderungen zurückgegeben, die für Version 2009-09-19 und höher erfolgen.

Dieser Header wird auch für die anonymen Anforderungen ohne Versionsangabe zurückgegeben, wenn der Container für öffentlichen Zugriff mit Version 2009-09-19 des Blob-Diensts markiert wurde. Beachten Sie, dass nur die Liste der Blöcke mit ausgeführtem Commit über eine anonyme Anforderung zurückgegeben werden kann.
Date Ein vom Dienst generierter Datums-/Uhrzeitwert in UTC, der angibt, wann die Antwort initiiert wurde.
x-ms-client-request-id Dieser Header kann zur Problembehandlung von Anforderungen und entsprechenden Antworten verwendet werden. Der Wert dieses Headers entspricht dem Wert des x-ms-client-request-id Headers, wenn er in der Anforderung vorhanden ist und der Wert höchstens 1.024 sichtbare ASCII-Zeichen hat. Wenn der x-ms-client-request-id Header in der Anforderung nicht vorhanden ist, ist dieser Header in der Antwort nicht vorhanden.

Dieser Vorgang unterstützt zudem die Verwendung von bedingten Headern zum Abrufen der Blockliste nur dann, wenn eine bestimmte Bedingung erfüllt ist. Weitere Informationen finden Sie unter Specifying Conditional Headers for Blob Service Operations (Angeben von bedingten Headern für Vorgänge des Blob-Diensts).

Antworttext

Das Format des Antworttexts für eine Anforderung, die nur Blöcke mit ausgeführtem Commit zurückgibt, lautet wie folgt:

<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <CommittedBlocks>  
    <Block>  
      <Name>base64-encoded-block-id</Name>  
      <Size>size-in-bytes</Size>  
    </Block>  
  <CommittedBlocks>  
</BlockList>  

Das Format des Antworttexts für eine Anforderung, die sowohl Blöcke mit ausgeführtem Commit als auch Blöcke ohne ausgeführten Commit zurückgibt, lautet wie folgt:

  
<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <CommittedBlocks>  
     <Block>  
        <Name>base64-encoded-block-id</Name>  
        <Size>size-in-bytes</Size>  
     </Block>  
  </CommittedBlocks>  
  <UncommittedBlocks>  
    <Block>  
      <Name>base64-encoded-block-id</Name>  
      <Size>size-in-bytes</Size>  
    </Block>  
  </UncommittedBlocks>  
 </BlockList>  
  

Beispiel für eine Antwort

Im folgenden Beispiel wurde der blocklisttype-Parameter auf committed festgelegt, sodass nur die Blöcke mit ausgeführtem Commit des BLOB in der Antwort zurückgegeben werden.

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23  
Date: Sun, 25 Sep 2011 00:33:19 GMT  
  
<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <CommittedBlocks>  
    <Block>  
      <Name>BlockId001</Name>  
      <Size>4194304</Size>  
    </Block>  
    <Block>  
      <Name>BlockId002</Name>  
      <Size>4194304</Size>  
    </Block>  
  </CommittedBlocks>  
</BlockList>  

In diesem Beispiel wurde der blocklisttype-Parameter auf all festgelegt. In der Antwort werden die Blöcke mit ausgeführtem Commit und die Blöcke ohne ausgeführten Commit des BLOB zurückgegeben.

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23  
Date: Sun, 25 Sep 2011 00:35:56 GMT  
  
<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <CommittedBlocks>  
    <Block>  
      <Name>BlockId001</Name>  
      <Size>4194304</Size>  
    </Block>  
    <Block>  
      <Name>BlockId002</Name>  
      <Size>4194304</Size>  
    </Block>  
  </CommittedBlocks>  
  <UncommittedBlocks>  
    <Block>  
      <Name>BlockId003</Name>  
      <Size>4194304</Size>  
    </Block>  
    <Block>  
      <Name>BlockId004</Name>  
      <Size>1024000</Size>  
    </Block>  
  </UncommittedBlocks>  
</BlockList>  

Im nächsten Beispiel wurde der blocklisttype-Parameter auf all festgelegt, aber für das BLOB wurde noch kein Commit ausgeführt, sodass das CommittedBlocks-Element leer ist.

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23  
Date: Wed, 14 Sep 2011 00:40:22 GMT  
  
<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <CommittedBlocks />  
  <UncommittedBlocks>  
    <Block>  
      <Name>BlockId001</Name>  
      <Size>1024</Size>  
    </Block>  
    <Block>  
      <Name>BlockId002</Name>  
      <Size>1024</Size>  
    </Block>  
    <Block>  
      <Name>BlockId003</Name>  
      <Size>1024</Size>  
    </Block>  
    <Block>  
      <Name>BlockId004</Name>  
      <Size>1024</Size>  
    </Block>  
  </UncommittedBlocks>  
</BlockList>  

Autorisierung

Wenn die ACL des Containers den anonymen Zugriff zulässt, kann jeder Client Get Block List aufrufen. Aber der öffentliche Zugriff ist nur auf Blöcke mit ausgeführtem Commit möglich. Der Zugriff auf die Liste der Blöcke ohne ausgeführten Commit ist auf den Kontobesitzer und jeden Benutzer mit einer SAS (Shared Access Signature) beschränkt, der über die Berechtigung verfügt, dieses BLOB oder den zugehörigen Container zu lesen.

Hinweise

Rufen Sie Get Block List auf, um die Liste der Blöcke, für die ein Commit für ein Block-BLOB ausgeführt wurde, die Liste der Blöcke, für die noch kein Commit ausgeführt wurde, oder beide Listen zurückzugeben. Verwenden Sie den blocklisttype-Parameter, um anzugeben, welche Liste von Blöcken zurückgegeben werden soll. Die Liste der Blöcke, für die ein Committed durchgeführt wurde, wird in derselben Reihenfolge zurückgegeben, in der sie vom Put Block List-Vorgang durchgeführt wurden.

Wenn Aufrufe von Put Block oder Put Block List zu einem Fehler führen, können Sie die Liste der Blöcke ohne ausgeführten Commit verwenden, um zu bestimmen, welche Blöcke im BLOB fehlen. Die Liste der Blöcke ohne Auskommentiert wird in alphabetischer Reihenfolge zurückgegeben. Wenn eine Block-ID mehrmals hochgeladen wurde, wird nur der zuletzt hochgeladene Block in der Liste angezeigt.

Wenn für ein BLOB noch kein Commit ausgeführt wurde, gibt der Aufruf von Get Block List mit blocklisttype=all die Blöcke ohne ausgeführten Commit zurück, und das CommittedBlocks-Element ist leer.

Get Block List unterstützt keine Parallelität beim Lesen der Liste der Blöcke ohneCommitted. Aufrufe von Get Block List , bei denen oder eine niedrigere maximale blocklisttype=uncommitted blocklisttype=all Anforderungsrate als andere Lesevorgänge haben. Weitere Informationen zum Zieldurchsatz für Lesevorgänge finden Sie unter Azure Storage Skalierbarkeits- und Leistungsziele.

Ab Version 2019-12-12 kann ein Blockblob Blöcke mit einer Größe von bis zu 4.000 MiB enthalten. Um Anwendungen zu schützen, die eine 32-Bit-Ganzzahl mit Vorzeichen verwenden, um die Blockgröße anzuzeigen, führt der Aufruf von für ein Blockblob, das einen Block enthält, der größer als 100 MiB ist, mit einer Get Block List REST-Version vor 2019-12-12 zum Statuscode 409 (Konflikt).

Get Block List ist nur für Block-BLOBs anwendbar. Der Aufruf von Get Block List für ein Seitenblob führt zum Statuscode 400 (Ungültige Anforderung).

Get Block List für ein archiviertes Blockblob wird ein Fehler angezeigt.

Siehe auch

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