Put Block

Artikel
02/03/2024

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

Anforderung

Sie können die Put Block Anforderung wie folgt erstellen. Es wird empfohlen, HTTPS zu verwenden. Ersetzen Sie myaccount durch den Namen Ihres Speicherkontos:

PUT-Methodenanforderungs-URI	HTTP-Version
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=id`	HTTP/1.1

Emulierte Speicherdienstanforderung

Wenn Sie eine Anforderung an den emulierten Speicherdienst stellen, geben Sie den Emulatorhostnamen und den Blobdienstport als 127.0.0.1:10000an, gefolgt vom Namen des emulierten Speicherkontos:

PUT-Methodenanforderungs-URI	HTTP-Version
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=block&blockid=id`	HTTP/1.1

Weitere Informationen finden Sie unter Verwenden des Azurite-Emulators für lokale Azure Storage-Entwicklung.

URI-Parameter

Parameter	BESCHREIBUNG
`blockid`	Erforderlich. Ein gültiger Base64-Zeichenfolgenwert, der den Block bezeichnet. Bevor sie codiert wird, muss die Zeichenfolge kleiner als oder gleich 64 Bytes sein. Für ein angegebenes Blob muss die Länge des Werts für den `blockid` Parameter die gleiche Größe für jeden Block aufweisen. Hinweis: Die Base64-Zeichenfolge muss URL-codiert sein.
`timeout`	Optional. Der `timeout`-Parameter wird in Sekunden angegeben. Weitere Informationen finden Sie unter Festlegen von Timeouts für Blobdienstvorgänge.

Anforderungsheader

Die erforderlichen und optionalen Anforderungsheader werden in der folgenden Tabelle 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-Dienste.
`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 Mebibyte (MiB) sein. Einschränkungen in älteren Versionen finden Sie im Abschnitt Hinweise . Wenn die Länge nicht angegeben wird, schlägt der Vorgang mit dem status Code 411 (Länge erforderlich) fehl.
`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. Hinweis: Dieser MD5-Hash wird nicht im Blob gespeichert. Wenn die beiden Hashes nicht übereinstimmen, schlägt der Vorgang mit dem 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. Hinweis: Dieser CRC64-Hash wird nicht im Blob gespeichert. 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 einer 400 (ungültige Anforderung) fehl. Dieser Header wird in Versionen 2019-02-02 und 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 Versionen 2019-02-02 und 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, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (KiB) bereit, der in den Protokollen aufgezeichnet wird, wenn die Protokollierung konfiguriert ist. Es wird dringend empfohlen, diesen Header zu verwenden, um clientseitige Aktivitäten mit Anforderungen zu korrelieren, die der Server empfängt. Weitere Informationen finden Sie unter Überwachen Azure Blob Storage.

Anforderungsheader (vom Kunden bereitgestellte Verschlüsselungsschlüssel)

Ab Version 2019-02-02 können die folgenden Header für die Anforderung angegeben werden, um 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 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.

Antwortheader	BESCHREIBUNG
`Content-MD5`	Wird zurückgegeben, damit der Client die Integrität des Nachrichteninhalts überprüfen kann. Der Wert dieses Headers wird von Blob Storage berechnet, und es ist nicht notwendigerweise derselbe Wert, der in den Anforderungsheadern angegeben wird. Für Versionen 2019-02-02 und höher wird dieser Header nur zurückgegeben, wenn die Anforderung über diesen Header verfügt.
`x-ms-content-crc64`	Für Versionen 2019-02-02 und höher wird dieser Header zurückgegeben, damit der Client die Integrität des Nachrichteninhalts überprüfen kann. Der Wert dieses Headers wird von Blob Storage berechnet, und es ist nicht notwendigerweise derselbe Wert, der in den Anforderungsheadern angegeben wird. Dieser Header wird zurückgegeben, wenn `Content-md5` der Header in der Anforderung nicht vorhanden ist.
`x-ms-request-id`	Identifiziert die durchgeführte Anforderung eindeutig, und Sie können sie zur Problembehandlung für die Anforderung verwenden. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge.
`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 oder höher ausgeführt wurden.
`Date`	Ein UTC-Datums-/Uhrzeitwert, der vom Dienst generiert wird, der angibt, wann die Antwort initiiert wurde.
`x-ms-request-server-encrypted: true/false`	Version 2015-12-11 und höher. Der Wert dieses Headers wird auf `true` festgelegt, wenn der Inhalt der Anforderung mithilfe des angegebenen Algorithmus erfolgreich verschlüsselt wurde. Andernfalls wird der Wert auf `false` festgelegt.
`x-ms-encryption-key-sha256`	Version 2019-02-02 und höher. 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 mithilfe des bereitgestellten Schlüssels erfolgreich verschlüsselt wurde.
`x-ms-encryption-scope`	Version 2019-02-02 und höher. Dieser Header wird zurückgegeben, wenn die Anforderung einen Verschlüsselungsbereich verwendet hat, sodass der Client sicherstellen kann, dass der Inhalt der Anforderung mithilfe des Verschlüsselungsbereichs erfolgreich verschlüsselt wurde.
`x-ms-client-request-id`	Kann zur Problembehandlung von Anforderungen und deren entsprechenden Antworten verwendet werden. 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.

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

Authorization

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

Azure Storage unterstützt die Verwendung von Microsoft Entra ID zum Autorisieren von Anforderungen für Blobdaten. Mit Microsoft Entra ID können Sie die rollenbasierte Zugriffssteuerung von Azure (Azure RBAC) 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 mithilfe von Microsoft Entra ID.

Berechtigungen

Unten sind die RBAC-Aktion aufgeführt, die für einen Microsoft Entra Benutzer, eine Gruppe oder einen Dienstprinzipal erforderlich ist, um den Put Block 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/write
Integrierte Rolle mit den geringsten Berechtigungen:Mitwirkender an Storage-Blobdaten

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

Eine Shared Access Signature (SAS) 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, über welche Berechtigungen er für diese Ressourcen verfügt und wie lange die SAS gültig ist.

Der Put Block Vorgang unterstützt drei Arten von Shared Access Signatures: Sas für die Benutzerdelegierung, 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 mit gemeinsam genutzten Schlüsseln für das Speicherkonto nicht zulässig ist, ist ein Sas-Diensttoken oder ein Konto-SAS-Token bei einer Anforderung an Blob Storage nicht zulässig. Weitere Informationen finden Sie unter Grundlegendes dazu, wie sich die Aufhebung der Verwendung gemeinsam genutzter Schlüssel auf SAS-Token auswirkt.

SAS für die Benutzerdelegierung

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

Für das Aufrufen des Put Block Vorgangs mit einem SAS-Token, das an einen Container oder eine Blobressource delegiert wird, ist die Schreibberechtigung (w) als Teil des SAS-Tokens für die Benutzerdelegierung erforderlich.

Weitere Informationen zur SAS für die Benutzerdelegierung finden Sie unter Erstellen einer SAS für die Benutzerdelegierung.

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. BlobSpeicher.

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 Typ der signierten Ressource und die signierten Berechtigungen angegeben, die beim Delegieren des Zugriffs angegeben werden sollen:

Vorgang	Signierter Dienst	Signierter Ressourcentyp	Signierte Berechtigung
Put Block	Blob (b)	Objekt (o)	Schreiben (w)

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

Der Put Block Vorgang unterstützt die Autorisierung mit gemeinsam verwendeten Schlüsseln. Die Autorisierung mit Kontoschlüsseln wird für die meisten Szenarien nicht empfohlen, da sie weniger sicher ist.

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

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 aufweisen. Ein Blockblob kann maximal 50.000 committete Blöcke enthalten.

In der folgenden Tabelle werden die maximal zulässigen Block- und Blobgrößen nach Dienstversion beschrieben:

Dienstversion	Maximale Blockgröße (über `Put Block`)	Maximale Blobgröße (über `Put Block List`)	Maximale Blobgröße über einen einzelnen Schreibvorgang (über `Put Blob`)
Ab Version 2019-12-12	4.000 MiB	Ca. 190,7 Tebibyte (TiB) (4.000 MiB × 50.000 Blöcke)	5.000 MiB
Versionen 2016-05-31 bis 2019-07-07	100 MiB	Ca. 4,75 TiB (100 MiB × 50.000 Blöcke)	256 MiB
Versionen vor 31.05.2016	4 MiB	Ca. 195 Gibibyte (GiB) (4 MiB × 50.000 Blöcke)	64 MiB

Die maximale Anzahl von Blöcken ohne Commit, die einem Blob zugeordnet sein können, beträgt 100.000. Wenn diese Zahl überschritten wird, gibt der Dienst status Code 409 (RequestEntityTooLargeBlockCountExceedsLimit) zurück.

Nachdem Sie eine Reihe von Blöcken hochgeladen haben, können Sie das Blob auf dem Server aus dieser Gruppe erstellen oder aktualisieren, indem Sie den Vorgang Put Block List aufrufen. Jeder Block im Satz wird durch eine Block-ID identifiziert, die innerhalb dieses Blobs eindeutig ist. Block-IDs sind auf ein bestimmtes Blob ausgerichtet, sodass verschiedene Blobs Blöcke mit denselben IDs aufweisen können.

Wenn Sie für ein Blob aufrufen Put Block , das noch nicht vorhanden ist, wird ein neues Blockblob mit einer Inhaltslänge von 0 erstellt. Wenn die include=uncommittedblobs-Option angegeben wurde, wird das BLOB mit dem Vorgang List Blobs aufgelistet. Der oder die hochgeladenen Blöcke werden erst dann committet, wenn Sie für das neue Blob aufrufen Put Block List . Ein auf diese Weise erstelltes Blob wird eine Woche lang auf dem Server verwaltet. Wenn Sie innerhalb dieses Zeitraums keine weiteren Blöcke oder Commits für das Blob hinzugefügt haben, wird das Blob mit Müll gesammelt.

Ein Block, der mit dem Put Block Vorgang erfolgreich hochgeladen wurde, wird erst Dann Teil eines Blobs, wenn er mit Put Block Listcommittet wird. Bevor Put Block List aufgerufen wird, um das neue oder aktualisierte Blob zu commiten, geben alle Aufrufe von Get Blob den Blobinhalt zurück, ohne den nicht festgeschriebenen Block einzubeziehen.

Wenn Sie einen Block hochladen, der dieselbe Block-ID wie ein anderer Block aufweist, der noch nicht committet wurde, wird der letzte hochgeladene Block mit dieser ID beim nächsten erfolgreichen Put Block List Vorgang committet.

Nachdem Put Block List aufgerufen wurde, werden alle nicht gebundenen Blöcke, die in der Blockliste angegeben sind, als Teil des neuen Blobs committet. Alle nicht belegten Blöcke, die nicht in der Blockliste für das Blob angegeben wurden, werden gesammelt und aus Blob Storage entfernt. Alle nicht freigegebenen Blöcke werden ebenfalls mit Müll gesammelt, wenn innerhalb einer Woche nach dem letzten erfolgreichen Put Block Vorgang keine erfolgreichen Aufrufe Put Block für oder Put Block List für dasselbe Blob ausgeführt werden. Wenn Put Blob für das Blob aufgerufen wird, werden alle nicht freigegebenen Blöcke mit Müll gesammelt.

Wenn das Blob über eine aktive Lease verfügt, muss der Client eine gültige Lease-ID für die Anforderung angeben, um einen Block in das Blob zu schreiben. Wenn der Client entweder keine Lease-ID oder eine ungültige Lease-ID angibt, gibt Blob Storage status Code 412 (Vorbedingung fehlgeschlagen) zurück. Wenn der Client eine Lease-ID angibt, das Blob jedoch nicht über eine aktive Lease verfügt, gibt Blob Storage auch status Code 412 (Vorbedingung fehlgeschlagen) zurück.

Für ein angegebenes Blob müssen alle Block-IDs die gleiche 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 4.000 MiB für Version 2019-12 oder höher, größer als 100 MiB für Version 2016-05-31 oder höher oder größer als 4 MiB für ältere Versionen ist, gibt der Dienst status Code 413 (Request Entity Too Large) zurück. Der Dienst gibt auch zusätzliche Informationen zum Fehler in der Antwort zurück, einschließlich der maximal zulässigen Blockgröße, in Bytes.

Beim Aufrufen Put Block wird der Zeitpunkt der letzten Änderung eines vorhandenen Blobs nicht aktualisiert.

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

Das Aufrufen Put Block eines archivierten Blobs gibt einen Fehler zurück, und das Aufrufen des Blobs in einem hot Oder-Blob cool ändert die Blobebene nicht.

Abrechnung

Preisanforderungen können von Clients stammen, die Blob Storage-APIs verwenden, entweder direkt über die Blob Storage-REST-API oder aus einer Azure Storage-Clientbibliothek. Für diese Anforderungen fallen Gebühren pro Transaktion an. Die Art der Transaktion wirkt sich auf die Belastung des Kontos aus. Beispielsweise werden Lesetransaktionen in eine andere Abrechnungskategorie als das Schreiben von Transaktionen angewendet. Die folgende Tabelle zeigt die Abrechnungskategorie für Put Block Anforderungen basierend auf dem Speicherkontotyp:

Vorgang	Speicherkontotyp	Abrechnungskategorie
Put Block	Premium, Blockblob Standard „Allgemein v2“ Standard „Allgemein v1“	Schreibvorgänge

Weitere Informationen zu Preisen für die angegebene Abrechnungskategorie finden Sie unter Azure Blob Storage Preise.

Weitere Informationen

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