Freigeben über


Block von URL anhängen

Der Append Block From URL Vorgang führt einen Commit für einen neuen Datenblock an das Ende eines vorhandenen Anfügeblobs aus.

Der Append Block From URL Vorgang ist nur zulässig, wenn das Blob mit x-ms-blob-type dem Wert von erstellt wurde.AppendBlob Append Block From URL wird nur in Version 2018-11-09 oder höher unterstützt.

Anfrage

Sie können die Append Block From URL Anforderung wie folgt erstellen. HTTPS wird empfohlen. Ersetzen Sie myaccount durch den Namen Ihres Speicherkontos.

Anforderungs-URI der PUT-Methode HTTP-Version
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock HTTP/1.1

Wenn Sie eine Anforderung an den emulierten Speicherdienst senden, geben Sie den Hostnamen des Emulators und den Azure Blob Storage-Port 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=appendblock HTTP/1.1

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

URI-Parameter

Parameter BESCHREIBUNG
timeout Wahlfrei. Der Timeoutparameter wird in Sekunden ausgedrückt. Weitere Informationen finden Sie unter Festlegen von Timeouts für Blob Storage-Vorgänge.

Anforderungsheader

In der folgenden Tabelle werden die erforderlichen und optionalen Anforderungsheader 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 Storage-Dienste.
Content-Length Erforderlich. Gibt die Anzahl der Im Anforderungstext übertragenen Bytes an. Der Wert dieses Headers muss auf Null gesetzt werden. Wenn die Länge nicht Null ist, schlägt der Vorgang mit dem Fehlercode 400 (Ungültige Anforderung) fehl.
x-ms-copy-source:name Erforderlich. Gibt die URL des Quellblobs an. Der Wert kann eine URL mit einer Länge von bis zu 2 KiB sein, 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 Berechtigungsschema und die Signatur für die Kopierquelle an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
Für Microsoft Entra ID wird nur der Schema-Bearer unterstützt.
Dieser Header wird in Version 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 dies nicht angegeben ist, wird der gesamte Inhalt des Quellblobs als einzelner Anfügeblock hochgeladen. Weitere Informationen finden Sie unter Angeben des Bereichsheaders für Blob Storage-Vorgänge .
x-ms-source-content-md5 Wahlfrei. Ein MD5-Hash des Anfügeblockinhalts aus dem URI. Dieser Hash wird verwendet, um die Integrität des Anfügeblocks beim Transport der Daten aus dem URI zu überprüfen. Wenn Sie diesen Header angeben, vergleicht der Speicherdienst den Hash des Inhalts, der von der Copy-Source eingegangen ist, mit diesem Headerwert.

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

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 Anfügeblockinhalts aus dem URI. Dieser Hash wird verwendet, um die Integrität des Anfügeblocks beim Transport der Daten aus dem URI zu überprüfen. Wenn Sie diesen Header angeben, vergleicht der Speicherdienst den Hash des Inhalts, der von der Copy-Source eingegangen ist, mit diesem Headerwert.

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

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 Version 2019-02-02 oder 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 Version 2019-02-02 oder 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-blob-condition-maxsize Optionaler bedingter Header. Die maximal zulässige Länge in Byte für das Anfügeblob. Wenn der Append Block From URL Vorgang dazu führt, dass das Blob diesen Grenzwert überschreitet, oder wenn die Blobgröße bereits größer als der in diesem Header angegebene Wert ist, schlägt die Anforderung mit 412 (Vorbedingung fehlgeschlagen) fehl.
x-ms-blob-condition-appendpos Optionaler bedingter Header, der nur für den Append Block from URL Vorgang verwendet wird. Eine Zahl, die den zu vergleichenden Byteoffset angibt. Append Block from URL Ist nur erfolgreich, wenn die Anfügeposition gleich dieser Zahl ist. Ist dies nicht der Fall, schlägt die Anforderung mit 412 (Vorbedingung fehlgeschlagen) fehl.
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.

Dieser Vorgang unterstützt die Verwendung zusätzlicher, bedingter Header, um sicherzustellen, dass die API nur dann erfolgreich ist, wenn eine bestimmte Bedingung erfüllt ist. Weitere Informationen finden Sie unter Angeben bedingter Header für Blob Storage-Vorgänge.

Anforderungsheader (vom Kunden bereitgestellte Verschlüsselungsschlüssel)

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

Der Anforderungstext enthält den Inhalt des Blocks.

Musteranforderung

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock  HTTP/1.1  

Request Headers:  
x-ms-version: 2018-11-09  
x-ms-date: <date>  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0 
If-Match: "0x8CB172A360EC34B"  

Antwort

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

Statuscode

Ein erfolgreicher Vorgang gibt den Statuscode 201 (Erstellt) zurück. 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
Etag Enthält ETag einen Wert in Anführungszeichen. Der Client verwendet den Wert, um bedingte PUT Vorgänge mithilfe des Anforderungsheaders If-Match auszuführen.
Last-Modified Das Datum/die Uhrzeit, zu der das Blob zuletzt geändert wurde. Das Datumsformat folgt RFC 1123. Weitere Informationen finden Sie unter Darstellung von Datums-/Uhrzeitwerten in Kopfzeilen.

Jeder Schreibvorgang für das Blob (einschließlich Aktualisierungen der Metadaten oder Eigenschaften des Blobs) ändert den Zeitpunkt der letzten Änderung des Blobs.
Content-MD5 Dieser Header wird zurückgegeben, damit der Client auf die Nachrichteninhaltsintegrität überprüfen kann. Blob Storage berechnet den Wert dieses Headers. Es handelt sich nicht unbedingt um denselben Wert, der in den Anforderungsheadern angegeben ist. Für Version 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 Version 2019-02-02 oder höher. Dieser Header wird zurückgegeben, damit der Client auf die Nachrichteninhaltsintegrität überprüfen kann. Blob Storage berechnet den Wert dieses Headers. Es handelt sich nicht unbedingt um denselben Wert, der in den Anforderungsheadern angegeben ist.

Dieser Header wird zurückgegeben, wenn der x-ms-source-content-md5 Header in der Anforderung nicht vorhanden ist.
x-ms-request-id Dieser Header identifiziert die anforderung eindeutig und kann für die Problembehandlung der Anforderung verwendet werden.
x-ms-version Gibt die Version von Blob Storage an, die zum Ausführen der Anforderung verwendet wird. Dieser Header wird für Anforderungen zurückgegeben, die mit Version 2009-09-19 und höher vorgenommen wurden.
Date Ein UTC-Datums-/Uhrzeitwert, der vom Dienst generiert wird, der die Uhrzeit angibt, zu der die Antwort initiiert wurde.
x-ms-blob-append-offset Dieser Antwortheader wird nur für Anfügevorgänge zurückgegeben. Er gibt den Offset zurück, bei dem der Block in Bytes zugesichert wurde.
x-ms-blob-committed-block-count Die Anzahl der zugesicherten Blöcke, die im Blob vorhanden sind. Auf diese Weise können Sie steuern, wie viele weitere Anfügungen ausgeführt werden können.
x-ms-request-server-encrypted: true/false Version 2015-12-11 oder höher. Der Wert dieses Headers wird auf true festgelegt, wenn der Inhalt der Anforderung mithilfe des angegebenen Algorithmus erfolgreich verschlüsselt wird. Andernfalls wird der Wert auf falsefestgelegt.
x-ms-encryption-key-sha256 Version 2019-02-02 oder höher. Dieser Header wird zurückgegeben, wenn für die Anforderung ein vom Kunden bereitgestellter Schlüssel für die Verschlüsselung verwendet wurde. Der Client kann dann sicherstellen, dass der Inhalt der Anforderung mithilfe des bereitgestellten Schlüssels erfolgreich verschlüsselt wird.
x-ms-encryption-scope Version 2019-02-02 oder höher. Dieser Header wird zurückgegeben, wenn die Anforderung einen Verschlüsselungsbereich verwendet hat. Der Client kann dann sicherstellen, dass der Inhalt der Anforderung mithilfe des Verschlüsselungsbereichs erfolgreich verschlüsselt wird.

Beispielantwort

Response Status:  
HTTP/1.1 201 Created  

Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-blob-append-offset: 2097152  
x-ms-blob-committed–block-count: 1000  

Autorisierung

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

Die Autorisierungsdetails in diesem Abschnitt gelten für das Kopierziel. Weitere Informationen zur Berechtigung zum Kopieren von Quellen finden Sie in den Details zum Request-Header x-ms-copy-source.

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

Append Block From URL Lädt einen Block an das Ende eines vorhandenen Anfügeblobs hoch. Der Datenblock ist sofort verfügbar, nachdem der Aufruf auf dem Server erfolgreich war. Für jedes Anfügeblob sind maximal 50.000 Anfügungen zulässig. Jeder Block kann unterschiedlich groß sein.

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

Dienstversion Maximale Blockgröße (über Append Block From URL) Maximale Blobgröße
Version 2022-11-02 und höher 100 MiB (Vorschau) Ca. 4,75 TiB (100 MiB × 50.000 Blöcke)
Versionen vor dem 02.11.2022 4 MiB Ca. 195 Gibibyte (GiB) (4 MiB × 50.000 Blöcke)

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

Append Block From URL Dies ist nur erfolgreich, wenn das Blob bereits vorhanden ist.

Blobs, die mithilfe Append Block From URL hochgeladen werden, machen keine Block-IDs verfügbar, sodass Sie Get Block List nicht für ein Anfügeblob aufrufen können. Dies führt zu einem Fehler.

Sie können die folgenden optionalen, bedingten Header für die Anforderung angeben:

  • x-ms-blob-condition-appendpos: Sie können diesen Header auf einen Byte-Offset setzen, bei dem der Client erwartet, den Block anzuhängen. Die Anforderung ist nur erfolgreich, wenn der aktuelle Offset mit dem vom Client angegebenen Offset übereinstimmt. Andernfalls schlägt die Anforderung mit dem Fehlercode 412 (Vorbedingung fehlgeschlagen) fehl.

    Clients, die einen einzelnen Writer verwenden, können diesen Header verwenden, um zu bestimmen, ob ein Append Block From URL Vorgang trotz Netzwerkfehler erfolgreich war.

  • x-ms-blob-condition-maxsize: Clients können diesen Header verwenden, um sicherzustellen, dass Anfügevorgänge die Blobgröße nicht über eine erwartete maximale Größe in Byte hinaus erhöhen. Wenn die Bedingung fehlschlägt, schlägt die Anforderung mit dem Fehlercode 412 (Vorbedingung fehlgeschlagen) fehl.

Wenn Sie versuchen, einen Block hochzuladen, der größer als die zulässige Größe ist, gibt der Dienst den HTTP-Fehlercode 413 (Request Entity Too Large) zurück. Der Dienst gibt auch zusätzliche Informationen über den Fehler in der Antwort zurück, einschließlich der maximal zulässigen Blockgröße in Bytes. Wenn Sie versuchen, mehr als 50.000 Blöcke hochzuladen, gibt der Dienst den Fehlercode 409 (Konflikt) zurück.

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 keine Lease-ID oder eine ungültige Lease-ID angibt, gibt Blob Storage den Fehlercode 412 (Fehler bei der Vorbedingung) zurück. Wenn der Client eine Lease-ID angibt, das Blob jedoch nicht über eine aktive Lease verfügt, gibt der Dienst den Fehlercode 412 zurück.

Wenn Sie ein vorhandenes Blockblob oder Seitenblob aufrufen Append Block From URL , gibt der Dienst den Fehlercode 409 (Konflikt) zurück. Wenn Sie ein nicht vorhandenes Blob aufrufen Append Block From URL , gibt der Dienst den Fehlercode 404 (Nicht gefunden) zurück.

Vermeiden Sie doppelte oder verzögerte Anhänge

In einem Szenario mit einem einzelnen Schreibvorgang kann der Client doppelte Anfügungen oder verzögerte Schreibvorgänge vermeiden, indem er den x-ms-blob-condition-appendpos bedingten Header verwendet, um den aktuellen Offset zu überprüfen. Der Client kann Duplikate oder Verzögerungen auch vermeiden, indem er die ETag bedingte Überprüfung mit If-Match.

In einem Szenario mit mehreren Schreibern kann jeder Client bedingte Header verwenden. Dies ist möglicherweise nicht optimal für die Leistung. Um den höchsten Durchsatz beim gleichzeitigen Anhängen zu erzielen, sollten Anwendungen redundante und verzögerte Anhänge in ihrer Anwendungsschicht verarbeiten. Anwendungen können z. B. Epochen oder Sequenznummern in den angehängten Daten hinzufügen.

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

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 Append Block From URL Anforderungen basierend auf dem Speicherkontotyp:

Vorgang Speicherkontotyp Abrechnungskategorie
Block von URL anhängen (Zielkonto1) Premium, Blockblob
Standard „Allgemein v2“
Standard „Allgemein v1“
Schreibvorgänge
Block von URL anhängen (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 die Quelle eine Transaktion aus.