Freigeben über


Block von URL setzen

Der Put Block From URL Vorgang erstellt einen neuen Block, für den ein Commit als Teil eines Blobs ausgeführt wird, in dem der Inhalt aus einer URL gelesen wird. Diese API ist ab Version 28.03.2018 verfügbar.

Anfrage

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

Anforderungs-URI der PUT-Methode 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 senden, geben Sie den Hostnamen des Emulators und den Port des Blob-Diensts als 127.0.0.1:10000an, gefolgt vom Namen des emulierten Speicherkontos:

Anforderungs-URI der 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 des Azurite-Emulators für die lokale Azure Storage-Entwicklung.

URI-Parameter

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

Für ein angegebenes Blob muss die Länge des angegebenen Werts für den blockid Parameter für jeden Block gleich groß sein.

Hinweis: Die Base64-Zeichenfolge muss URL-codiert sein.
timeout Wahlfrei. Der parameter timeout wird in Sekunden ausgedrückt. Weitere Informationen finden Sie unter Festlegen von Timeouts für Blob-Dienstvorgänge.

Anforderungsheader

Die erforderlichen und optionalen Anforderungsheader werden in der folgenden Tabelle beschrieben:

Anforderungs-Kopfzeile 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 (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 Vorgangs an, der für diese Anforderung verwendet werden soll. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste. Für Put Block From URLmuss die Version 2018-03-28 oder höher sein.
Content-Length Erforderlich. Gibt die Anzahl der Im Anforderungstext übertragenen Bytes an. Der Wert dieses Headers muss auf 0 gesetzt werden. Wenn die Länge nicht 0 ist, schlägt der Vorgang mit dem Statuscode 400 (Ungültige Anforderung) fehl.
x-ms-copy-source:name Erforderlich. Gibt die URL des Quellblobs an. Bei dem Wert kann es sich um eine URL mit einer Länge von bis zu 2 Kibibyte (KiB) handeln, die ein Blob angibt. Der Wert sollte URL-codiert sein, wie er in einem Anforderungs-URI angezeigt wird. Das Quellblob muss entweder öffentlich sein oder über eine Shared Access Signature autorisiert sein. Wenn das Quellblob öffentlich ist, ist keine Autorisierung erforderlich, um den Vorgang auszuführen. Hier sind einige Beispiele für Quellobjekt-URLs:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> Wahlfrei. Gibt das Autorisierungsschema und die Signatur für die Kopierquelle an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.

Hinweis: Für Microsoft Endra wird nur ein Bearerschema unterstützt.

Hinweis: Wenn das Quellobjekt öffentlich zugänglich ist oder sich das Quellobjekt in einem Speicherkonto befindet und Sie ein SAS-Token verwenden, das übergeben x-ms-copy-source:namewird, ist dieser Header nicht erforderlich.

Dieser Header wird in den Versionen 2020-10-02 und höher unterstützt.
x-ms-source-range Wahlfrei. Lädt nur die Bytes des Blobs in der Quell-URL im angegebenen Bereich hoch. Wenn dieser Header nicht angegeben ist, wird der gesamte Inhalt des Quellblobs als einzelner Block hochgeladen. Weitere Informationen finden Sie unter Angeben des Bereichsheaders für Blob-Dienstvorgänge.
x-ms-source-content-md5 Wahlfrei. Ein MD5-Hash des Blockinhalts aus dem URI. Dieser Hash wird verwendet, um die Integrität des Blocks während des Transports der Daten aus dem URI zu überprüfen. Wenn dieser Header angegeben wird, vergleicht der Speicherdienst den Hash des Inhalts, der von der Copy-Source eingegangen ist, mit diesem Headerwert.

Hinweis: Dieser MD5-Hash wird nicht mit dem Blob gespeichert.

Wenn die beiden Hashes nicht übereinstimmen, schlägt der Vorgang mit dem Fehlercode 400 (Ungültige Anforderung) fehl.
x-ms-source-content-crc64 Wahlfrei. Ein CRC64-Hash des Blockinhalts aus dem URI. Dieser Hash wird verwendet, um die Integrität des Blocks während des Transports der Daten aus dem URI zu überprüfen. Wenn dieser Header angegeben wird, vergleicht der Speicherdienst den Hash des Inhalts, der von der Copy-Source eingegangen ist, mit diesem Headerwert.

Hinweis: Dieser CRC64-Hash wird nicht mit dem Blob gespeichert.

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

Wenn sowohl als auch x-ms-source-content-md5x-ms-source-content-crc64 Header vorhanden sind, schlägt die Anforderung mit einem 400 (Bad Request) fehl.

Dieser Header wird in den Versionen 2019-02-02 und höher unterstützt.
x-ms-encryption-scope Wahlfrei. Gibt den Verschlüsselungsbereich an, der zum Verschlüsseln des Quellinhalts verwendet werden soll. Dieser Header wird in den Versionen 2019-02-02 und höher unterstützt.
x-ms-lease-id:<ID> Erforderlich, wenn das Blob über eine aktive Pacht 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 Wahlfrei. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem 1-Kibibyte-Zeichenlimit (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 von Azure Blob Storage.
x-ms-file-request-intent Erforderlich, wenn x-ms-copy-source es sich bei dem Header um eine Azure-Datei-URL handelt und x-ms-copy-source-authorization der Header ein OAuth-Token angibt. Zulässiger Wert ist backup. Dieser Header gibt an, dass die Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action oder Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action gewährt werden sollen, wenn sie in der RBAC-Richtlinie enthalten sind, die der Identität zugewiesen ist, die mithilfe des x-ms-copy-source-authorization-Headers autorisiert ist. Verfügbar für Version 2025-07-05 und höher.

Anforderungsheader (vom Kunden bereitgestellte Verschlüsselungsschlüssel)

Ab Version 2019-02-02 können die folgenden Header in der 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.

Anforderungs-Kopfzeile 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.

Anfragekörper

Keiner.

Musteranforderung

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: 2018-03-28  
x-ms-date: Sat, 31 Mar 2018 14:37:35 GMT    
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-499

Antwort

Die Antwort enthält einen HTTP-Statuscode und eine Reihe von Antwortheadern.

Statuscode

Ein erfolgreicher Vorgang gibt den Statuscode 201 (Erstellt) zurück.

Weitere Informationen zu Statuscodes finden Sie unter Status- und Fehlercodes.

Antwortkopfzeilen

Die Antwort für diesen Vorgang enthält die folgenden Header. Die Antwort kann auch zusätzliche Standard-HTTP-Header enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Antwortkopfzeile BESCHREIBUNG
Content-MD5 Wird zurückgegeben, sodass der Client auf die Integrität von Nachrichteninhalten überprüfen kann. Der Wert dieses Headers wird von Blob Storage berechnet. Er ist nicht notwendigerweise identisch mit dem Wert, der in den Anforderungsheadern angegeben ist. Für die 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 die Versionen 2019-02-02 und höher. Wird zurückgegeben, sodass der Client auf die Integrität von Nachrichteninhalten überprüfen kann. Der Wert dieses Headers wird von Blob Storage berechnet. Er ist nicht unbedingt identisch mit dem Wert, der in den Anforderungsheadern angegeben ist.

Wird zurückgegeben, wenn x-ms-source-content-md5 der Header in der Anforderung nicht vorhanden ist.
x-ms-request-id Identifiziert die anforderung eindeutig, die durchgeführt wurde, und Sie können sie verwenden, um die Anforderung zu beheben. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge.
x-ms-version Die Blob Storage-Version, die zum Ausführen der Anforderung verwendet wurde.
Date Ein UTC-Datums-/Uhrzeitwert, der vom Dienst generiert wird, der die Uhrzeit angibt, zu der 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 den Wert gesetzt, wenn der Inhalt des Blocks mit dem angegebenen Algorithmus erfolgreich verschlüsselt wurde. Andernfalls wird der Wert auf falsefestgelegt.
x-ms-encryption-key-sha256 Version 2019-02-02 und höher. Wird zurückgegeben, wenn für die Anforderung ein vom Kunden bereitgestellter Schlüssel für die Verschlüsselung verwendet wurde, damit der Client sicherstellen kann, dass der Inhalt der Anforderung mithilfe des bereitgestellten Schlüssels erfolgreich verschlüsselt wird.
x-ms-encryption-scope Version 2019-02-02 und höher. Wird zurückgegeben, wenn für die Anforderung ein Verschlüsselungsbereich verwendet wurde, sodass der Client sicherstellen kann, dass der Inhalt der Anforderung mithilfe des Verschlüsselungsbereichs erfolgreich verschlüsselt wird.
x-ms-client-request-id Kann verwendet werden, um Anfragen 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.

Beispielantwort

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

Autorisierung

Die Autorisierung ist beim Aufrufen eines Datenzugriffsvorgangs in Azure Storage erforderlich. Sie können den Put Block From URL Vorgang wie unten beschrieben autorisieren.

Von Bedeutung

Microsoft empfiehlt die Verwendung der Microsoft Entra-ID mit verwalteten Identitäten, um Anforderungen an Azure Storage zu autorisieren. Die Microsoft Entra-ID bietet eine bessere Sicherheit und Benutzerfreundlichkeit im Vergleich zur Shared Key-Autorisierung.

Azure Storage unterstützt die Verwendung der Microsoft Entra-ID zum Autorisieren von Anforderungen an BLOB-Daten. Mit Der Microsoft Entra-ID können Sie azure role-based access control (Azure RBAC) verwenden, um Berechtigungen für einen Sicherheitsprinzipal zu erteilen. Der Sicherheitsprinzipal kann ein Benutzer, eine Gruppe, ein Anwendungsdienstprinzipal oder eine von Azure verwaltete Identität sein. Der Sicherheitsprinzipal wird von der Microsoft Entra-ID authentifiziert, um ein OAuth 2.0-Token zurückzugeben. Das Token kann dann verwendet werden, um eine Anforderung gegen den Blob-Dienst zu autorisieren.

Weitere Informationen zur Autorisierung mithilfe der Microsoft Entra-ID finden Sie unter Autorisieren des Zugriffs auf Blobs mithilfe von Microsoft Entra ID.

Erlaubnisse

Nachfolgend sind die RBAC-Aktion aufgeführt, die für einen Microsoft Entra-Benutzer, eine Gruppe, eine verwaltete Identität oder einen Dienstprinzipal erforderlich ist, um den Put Block From URL Vorgang aufzurufen, und die integrierte Azure RBAC-Rolle, die diese Aktion enthält:

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

Bemerkungen

Put Block From URL Lädt einen Block für die zukünftige Aufnahme in ein Blockblob hoch. Ein Blockblob kann maximal 50.000 Blöcke enthalten. Jeder Block kann eine andere Größe haben. Die maximale Größe für einen Block, der mit Put Block From URL hochgeladen wird, beträgt 100 Mebibyte (MiB). Informationen zum Hochladen größerer Blöcke (bis zu 4.000 MiB) finden Sie unter Put Block.

In Version 2020-10-02 und höher wird die Microsoft Entra-Autorisierung für die Quelle des Kopiervorgangs unterstützt.

Ein Blob kann jeweils maximal 100.000 nicht festgeschriebene Blöcke enthalten. Wenn dieser Maximalwert überschritten wird, gibt der Dienst den Statuscode 409 (RequestEntityTooLargeBlockCountExceedsLimit) zurück.

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

Dienstversion Maximale Blockgröße (über Put Block From URL) Maximale Blob-Größe (über Put Block List) Maximale Blobgröße über einen einzelnen Schreibvorgang (über Put Blob From URL)
Version 2020-04-08 und höher 4.000 MiB Ca. 190,7 Tebibyte (TiB) (4.000 MiB × 50.000 Blöcke) 5.000 MiB
Versionen vor dem 08.04.2020 100 MiB Ca. 4,75 TiB (100 MiB × 50.000 Blöcke) 256 MiB

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

Wenn Sie ein Blob aufrufen Put Block From URL , das noch nicht vorhanden ist, wird ein neues Blockblob mit einer Inhaltslänge von 0 erstellt. Dieses Blob wird vom List Blobs Vorgang aufgelistet, wenn die include=uncommittedblobs Option angegeben wird. Für die hochgeladenen Blöcke wird erst ein Commit ausgeführt, wenn Sie das neue Blob aufrufen Put Block List . Ein auf diese Weise erstelltes Blob wird eine Woche lang auf dem Server verwaltet. Wenn Sie dem Blob innerhalb dieses Zeitraums keine weiteren Blöcke hinzugefügt oder Blöcke mit Commit ausgeführt haben, wird das Blob von der Garbage Collection erfasst.

Ein Block, der erfolgreich mit dem Put Block From URL Vorgang hochgeladen wurde, wird erst dann Teil eines Blobs, wenn er mit Put Block Listausgeführt wird. Bevor Put Block List ein Commit für das neue oder aktualisierte Blob aufgerufen wird, geben alle Aufrufe von Get Blob den Blobinhalt zurück, ohne dass der Block ohne Commit eingeschlossen wird.

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

Nach Put Block List dem Aufruf wird für alle in der Sperrliste angegebenen Blöcke ohne Commit ein Commit als Teil des neuen Blobs ausgeführt. Alle Blöcke ohne Commit, für die kein Commit ausgeführt wurde, werden von der Garbage Collection erfasst und aus Blob Storage entfernt. Alle Blöcke, für die kein Commit ausgeführt wurde, werden auch dann von der Garbage Collection erfasst, wenn innerhalb einer Woche nach dem letzten erfolgreichen Put Block From URL Vorgang keine erfolgreichen Aufrufe von Put Block List oder Put Block From URL für dasselbe Blob vorhanden sind. Wenn Put Blob für das Blob aufgerufen wird, werden alle Blöcke, für die kein Commit ausgeführt wurde, von der Garbage Collection erfasst.

Wenn das Blob über eine aktive Lease verfügt, muss der Client eine gültige Lease-ID in der 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 den Statuscode 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 den Statuscode 412 (Vorbedingung fehlgeschlagen) zurück.

Für ein angegebenes Blob müssen alle Block-IDs die gleiche Länge haben. Wenn ein Block mit einer Block-ID hochgeladen wird, die sich von der Länge der Block-IDs für vorhandene Blöcke ohne Commit unterscheidet, gibt der Dienst den Fehlerantwortcode 400 (Ungültige Anforderung) zurück.

Durch den Aufruf Put Block From URL wird der Zeitpunkt der letzten Änderung eines vorhandenen Blobs nicht aktualisiert.

Beim Aufrufen Put Block From URL eines Seitenblobs wird ein Fehler zurückgegeben.

Beim Aufrufen Put Block From URL eines "Archiv"-Blobs wird ein Fehler zurückgegeben, und beim Aufrufen hot eines ODER-Blobs cool wird die Blobebene nicht geändert.

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. Diese Anforderungen anfallen Gebühren pro Transaktion. Der Transaktionstyp wirkt sich auf die Belastung des Kontos aus. Lesen Sie z. B. Transaktionen, die einer anderen Abrechnungskategorie als dem Schreiben von Transaktionen zugerechnet werden. Die folgende Tabelle zeigt die Abrechnungskategorie für Put Block From URL Anforderungen basierend auf dem Speicherkontotyp:

Vorgang Speicherkontotyp Abrechnungskategorie
Block von URL einfügen (Zielkonto1) Premium, Blockblob
Standard „Allgemein v2“
Standard „Allgemein v1“
Schreibvorgänge
Block von URL einfügen (Quellkonto2) Premium, Blockblob
Standard „Allgemein v2“
Standard „Allgemein v1“
Lesevorgänge

1Das Zielkonto wird mit einer Transaktion belastet, um den Schreibvorgang zu initiieren.
arabische ZifferDas Quellkonto führt für jede Leseanforderung an das Quellobjekt eine Transaktion aus.

Wenn sich das Quell- und das Zielkonto in unterschiedlichen Regionen befinden (z. B. "USA, Norden" und "USA, Süden"), wird die Bandbreite, die zum Übertragen der Anforderung verwendet wird, dem Quellspeicherkonto als ausgehender Datenverkehr in Rechnung gestellt. Der Ausgang zwischen Konten innerhalb derselben Region ist kostenlos.

Weitere Informationen zu den Preisen für die angegebenen Abrechnungskategorien finden Sie unter Azure Blob Storage – Preise.

Siehe auch