Put Block

Mit dem Vorgang Put Block wird ein neuer Block erstellt, für den ein Commit als Teil eines BLOB ausgeführt werden soll.

Anforderung

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

Anforderungs-URI für PUT-Methode HTTP-Version
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=id HTTP/1.1

URI des emulierten Speicherdiensts

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 PUT-Methode HTTP-Version
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=block&blockid=id HTTP/1.1

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

URI-Parameter

Parameter Beschreibung
blockid Erforderlich. Ein gültiger Base64-Zeichenfolgenwert, der den Block bezeichnet. Vor der Codierung muss die Zeichenfolge kleiner oder gleich 64 Bytes sein.

Für jedes BLOB muss die Länge des für den blockid-Parameter angegebenen Werts gleich der Größe jedes Blocks sein.

Beachten Sie, dass die Base64-Zeichenfolge codiert sein muss.
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. Gibt die Version des für die Anforderung zu verwendenden Vorgangs an. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure Storage Services.
Content-Length Erforderlich. Die Länge des Blockinhalts in Bytes. Der Block muss für Version 2019-12-12 und höher kleiner als oder gleich 4.000 MiB sein. Informationen zu Grenzwerten in älteren Versionen finden Sie in den Hinweisen.

Wenn die Länge nicht angegeben ist, tritt bei dem Vorgang ein Fehler mit dem Statuscode 411 (Länge erforderlich) auf.
Content-MD5 Optional. Ein MD5-Hash des Blockinhalts. Mithilfe des Hashs wird die Integrität des Blocks während der Übertragung überprüft. Bei Angabe dieses Headers vergleicht der Speicherdienst den Hash des eingegangenen Inhalts mit diesem Headerwert.

Beachten Sie, dass dieser MD5-Hash nicht mit dem BLOB gespeichert wird.

Wenn die beiden Hashs nicht übereinstimmen, schlägt der Vorgang mit Fehlercode 400 (Ungültige Anforderung) fehl.
x-ms-content-crc64 Optional. Ein CRC64-Hash des Blockinhalts. Mithilfe des Hashs wird die Integrität des Blocks während der Übertragung überprüft. Bei Angabe dieses Headers vergleicht der Speicherdienst den Hash des eingegangenen Inhalts mit diesem Headerwert.

Beachten Sie, dass dieser CRC64-Hash nicht mit dem Blob gespeichert wird.

Wenn die beiden Hashs nicht übereinstimmen, schlägt der Vorgang mit Fehlercode 400 (Ungültige Anforderung) fehl.

Wenn sowohl Content-MD5- als auch x-ms-content-crc64-Header vorhanden sind, schlägt die Anforderung mit dem Fehler 400 (Ungültige Anforderung) fehl.

Dieser Header wird in den Versionen 2019-02-02 oder höher unterstützt.
x-ms-encryption-scope Optional. Gibt den Verschlüsselungsbereich an, der zum Verschlüsseln des Anforderungsinhalts verwendet werden soll. Dieser Header wird in den Versionen 2019-02-02 oder höher unterstützt.
x-ms-lease-id:<ID> Erforderlich, wenn das BLOB über eine aktive Lease verfügt. Um diesen Vorgang für ein BLOB mit einer aktiven Lease auszuführen, geben Sie die gültige Lease-ID für diesen Header an.
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.

Anforderungsheader (vom Kunden bereitgestellte Verschlüsselungsschlüssel)

Ab Version 2019-02-02 können die folgenden Header in der Anforderung angegeben werden, ein Blob mit einem vom Kunden bereitgestellten Schlüssel zu verschlüsseln. Die Verschlüsselung mit einem vom Kunden bereitgestellten Schlüssel (und dem entsprechenden Satz von Headern) ist optional.

Anforderungsheader BESCHREIBUNG
x-ms-encryption-key Erforderlich. Der Base64-codierte AES-256-Verschlüsselungsschlüssel.
x-ms-encryption-key-sha256 Erforderlich. Der Base64-codierte SHA256-Hash des Verschlüsselungsschlüssels.
x-ms-encryption-algorithm: AES256 Erforderlich. Gibt den Algorithmus an, der für die Verschlüsselung verwendet werden soll. Der Wert dieses Headers muss auf AES256 festgelegt sein.

Anforderungstext

Der Anforderungstext enthält den Inhalt des Blocks.

Beispiel für eine Anforderung

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Sun, 25 Sep 2011 14:37:35 GMT  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048576  

Antwort

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

Statuscode

Bei einem erfolgreichen Vorgang wird der Statuscode 201 (Erstellt) 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
Content-MD5 Dieser Header wird zurückgegeben, damit der Client die Integrität des Nachrichteninhalts überprüfen kann. Der Wert dieses Headers wird vom Blob-Dienst berechnet; er stimmt nicht unbedingt mit dem Wert überein, der in den Anforderungsheadern angegeben wurde. Für die Versionen 2019-02-02 oder höher wird dieser Header nur zurückgegeben, wenn die Anforderung über diesen Header verfügt.
x-ms-content-crc64 Für die Versionen 2019-02-02 oder höher wird dieser Header zurückgegeben, damit der Client die Integrität des Nachrichteninhalts überprüfen kann. Der Wert dieses Headers wird vom Blob-Dienst berechnet; er stimmt nicht unbedingt mit dem Wert überein, der in den Anforderungsheadern angegeben wurde.

Dieser Header wird zurückgegeben, Content-md5 wenn der Header in der Anforderung nicht vorhanden ist.
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.
Date Ein vom Dienst generierter Datums-/Uhrzeitwert in UTC, der angibt, wann die Antwort initiiert wurde.
x-ms-request-server-encrypted: true/false Version 2015-12-11 oder neuer. Der Wert dieses Headers wird auf festgelegt, wenn der Inhalt der Anforderung erfolgreich mit dem angegebenen Algorithmus verschlüsselt true wurde, false andernfalls .
x-ms-encryption-key-sha256 Version 2019-02-02 oder neuer. Dieser Header wird zurückgegeben, wenn die Anforderung einen vom Kunden bereitgestellten Schlüssel für die Verschlüsselung verwendet hat, sodass der Client sicherstellen kann, dass der Inhalt der Anforderung erfolgreich mit dem bereitgestellten Schlüssel verschlüsselt wird.
x-ms-encryption-scope Version 2019-02-02 oder neuer. Dieser Header wird zurückgegeben, wenn die Anforderung einen Verschlüsselungsbereich verwendet hat, sodass der Client sicherstellen kann, dass der Inhalt der Anforderung erfolgreich mithilfe des Verschlüsselungsbereichs verschlüsselt wird.
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 Headers, wenn er in der Anforderung vorhanden ist und der Wert mindestens x-ms-client-request-id 1.024 sichtbare ASCII-Zeichen beträgt. Wenn der Header in der Anforderung nicht vorhanden ist, ist dieser x-ms-client-request-id Header in der Antwort nicht vorhanden.

Beispiel für eine Antwort

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  

Autorisierung

Dieser Vorgang kann vom Kontobesitzer und von einem Benutzer mit einer SAS (Shared Access Signature) aufgerufen werden, der über die Berechtigung verfügt, in dieses BLOB oder den Container zu schreiben.

Hinweise

Put Block lädt einen Block hoch, der später in einen Block-BLOB eingeschlossen werden soll. Jeder Block in einem Blockblob kann eine andere Größe haben. Ein Blockblob kann maximal 50.000 Blöcke mit einem Committed enthalten. In der folgenden Tabelle werden die maximalen Block- und Blobgrößen beschrieben, die nach Dienstversion zulässig sind:

Dienstversion Maximale Blockgröße (über Put Block) Maximale Blob-Größe (über Put Block-Liste) Maximale Blob-Größe über einen einzelnen Schreibvorgang (über Put Blob)
Ab Version 2019-12-12 4.000 MiB Ungefähr 190,7 TiB (4-000 MiB · 50.000 Blöcke) 5000 MiB (Vorschau)
Version 2016-05-31 bis Version 2019-07-07 100 MiB Ungefähr 4,75 TiB (100 MiB X 50.000 Blöcke) 256 MiB
Versionen vor 2016-05-31 4 MiB Ungefähr 195 GiB (4 MiB X 50.000 Blöcke) 64 MiB

Die maximale Anzahl von Blöcken ohneCommitted, die einem Blob zugeordnet sein können, beträgt 100.000. Wenn dieser Höchstwert überschritten wird, gibt der Dienst den Statuscode 409 (RequestEntityTooLargeBlockCountExceedsLimit) zurück.

Nachdem Sie eine Reihe von Blöcken hochgeladen haben, können Sie das Blob auf dem Server aus diesem Satz erstellen oder aktualisieren, indem Sie den Vorgang Put Block List aufrufen. Jeder Satz im Block wird durch eine Block-ID bezeichnet, die innerhalb des BLOB eindeutig ist. Block-IDs werden als Bereich zu einem bestimmten BLOB zusammengefasst, sodass verschiedene BLOBs Blöcke mit gleichen IDs enthalten können.

Wenn Sie Put Block für ein BLOB aufrufen, das noch nicht vorhanden ist, wird ein neues Block-BLOB mit einer Inhaltslänge von 0 erstellt. Wenn die include=uncommittedblobs-Option angegeben wurde, wird das BLOB mit dem Vorgang List Blobs aufgelistet. Für den Block oder die Blöcke, die Sie hochgeladen haben, wird erst dann ein Commit ausgeführt, wenn Sie Put Block List für das neue BLOB aufrufen. Ein auf diese Weise erstelltes BLOB wird eine Woche lang auf dem Server verwaltet. Wenn Sie dem BLOB innerhalb dieses Zeitraums keine Blöcke oder Blöcke mit ausgeführtem Commit hinzufügen, unterliegt das BLOB der Garbage Collection.

Der Block, der mit dem Vorgang Put Block erfolgreich hochgeladen wurde, wird erst Teil eines BLOB, wenn für ihn mit Put Block List ein Commit ausgeführt wurde. Bevor aufgerufen wird, um das neue oder aktualisierte Blob zu commiten, geben alle Aufrufe von Get Blob den Blobinhalt zurück, ohne dass der Block ohne Commit Put Block List berücksichtigt wird.

Wenn Sie einen Block hochladen, der die gleiche Block-ID wie ein anderer Block besitzt, für den noch kein Commit ausgeführt wurde, wird beim nächsten erfolgreichen Put Block List-Vorgang ein Commit für den zuletzt hochgeladenen Block mit dieser ID ausgeführt.

Nachdem Put Block List aufgerufen wurde, wird für in der Blockliste angegeben Blöcke ohne ausgeführtes Commit ein Commit als Teil des neuen BLOB ausgeführt. Alle Blöcke, für die kein Commit ausgeführt wurde und die nicht in der Blockliste für das BLOB angegeben sind, unterliegen der Garbage Collection und werden aus dem Blob-Dienst entfernt. Alle Blöcke ohne ausgeführten Commit werden ebenfalls vom Garbage Collector erfasst, wenn für dieses BLOB innerhalb einer Woche nach dem letzten erfolgreichen Put Block-Vorgang keine erfolgreichen Aufrufe von Put Block List oder Put Block erfolgen. Wenn Put Blob für das Blob aufgerufen wird, werden alle Blöcke, für die keinCommitted-Block erstellt wurde, vom Garbage Collection-Dienst erfasst.

Wenn das BLOB über eine aktive Lease verfügt, muss der Client zum Schreiben eines Blocks in das BLOB in der Anforderung eine gültige Lease-ID angeben. Wenn der Client keine Lease-ID oder eine ungültige Lease-ID angibt, gibt der Blob-Dienst den Statuscode 412 (Vorbedingung nicht erfüllt) zurück. Wenn der Client eine Lease-ID angibt, aber das BLOB nicht über eine aktive Lease verfügt, gibt der Blob-Dienst ebenfalls Statuscode 412 (Vorbedingung nicht erfüllt) zurück.

In einem bestimmten BLOB müssen alle Block-IDs dieselbe Länge aufweisen. Wenn ein Block mit einer Block-ID einer anderen Länge hochgeladen wird, als die Block-IDs für vorhandene Blöcke ohne ausgeführten Commit aufweisen, gibt der Dienst den Fehlerantwortcode 400 zurück (ungültige Anforderung).

Wenn Sie versuchen, einen Block hochzuladen, der größer als 4000 MiB für Version 2019-12-12 und höher, größer als 100 MiB für Version 2016-05-31 und höher und größer als 4 MiB für ältere Versionen ist, gibt der Dienst den Statuscode 413 (Anforderungsentität zu groß) zurück. Der Dienst gibt in der Antwort zudem weitere Informationen zum Fehler zurück, einschließlich der maximal zulässigen Blockgröße in Bytes.

Beim Aufrufen von Put Block wird die Uhrzeit der letzten Änderung eines vorhandenen BLOB nicht aktualisiert.

Beim Aufruf von Put Block für ein Seiten-BLOB wird ein Fehler zurückgegeben.

Wenn Put Block Sie für ein archiviertes Blob aufrufen, wird ein Fehler zurückgegeben, und beim Blob ändert sich die Hot / Cool Blobebene nicht.

Weitere Informationen

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