Blobbatch

  • Artikel

Mit Blob Batch dem Vorgang können mehrere API-Aufrufe in eine einzelne HTTP-Anforderung eingebettet werden. Diese API unterstützt zwei Arten von Unterquests: Festlegen der Blobebene für Blockblobs und Löschen von Blobs. Die vom Server für eine Batchanforderung zurückgegebene Antwort enthält die Ergebnisse für jede Teilanforderung im Batch. Die Batchanforderung und -antwort verwendet die Syntax der OData Batchverarbeitungsspezifikation mit Änderungen an der Semantik. Diese API ist ab Version 2018-11-09 verfügbar.

Anforderung

Sie können die Blob Batch Anforderung wie folgt erstellen. HTTPS wird empfohlen. Ersetzen Sie myaccount durch den Namen Ihres Speicherkontos.

Methode Anforderungs-URI HTTP-Version
POST https://myaccount.blob.core.windows.net/?comp=batch

https://myaccount.blob.core.windows.net/containername?restype=container&comp=batch		 HTTP/1.1

URI-Parameter

Sie können die folgenden zusätzlichen Parameter für den Anforderungs-URI angeben.

Parameter BESCHREIBUNG
timeout Optional. Der Timeoutparameter wird in Sekunden mit einem Maximalwert von 120 Sekunden ausgedrückt. Weitere Informationen finden Sie unter Festlegen von Timeouts für Blob Storage-Vorgänge.
restype Optional, Version 2020-04-08 und höher. Der einzige für den restype -Parameter unterstützte Wert ist container. Wenn dieser Parameter angegeben wird, muss der URI den Containernamen enthalten. Alle Unterabfragen müssen auf denselben Container festgelegt werden.

Anforderungsheader

In der folgenden Tabelle werden erforderliche und optionale Anforderungsheader beschrieben.

Anforderungsheader BESCHREIBUNG
Authorization Erforderlich. Gibt das Autorisierungsschema, den Namen des Speicherkontos 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. Diese Version wird für alle Unterquests verwendet. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste.
Content-Length Erforderlich. Die Länge der Anforderung.
Content-Type Erforderlich. Der Wert dieses Headers muss mit einer Batchgrenze sein multipart/mixed. Beispielheaderwert: multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252.
x-ms-client-request-id Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (KiB) bereit, der beim Konfigurieren der Protokollierung in den Protokollen aufgezeichnet wird. 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.

Anforderungstext

Der Anforderungstext für einen Blobbatch enthält eine Liste aller Unteranforderungen. Das Format verwendet die Syntax der OData Batchspezifikation mit Änderungen an der Semantik.

Der Anforderungstext beginnt mit einer Batchgrenze, gefolgt von zwei obligatorischen Headern: dem Content-Type Header mit dem Wert application/httpund dem Content-Transfer-Encoding Header mit dem Wert binary. Darauf folgt ein optionaler Content-ID Header mit einem Zeichenfolgenwert zum Nachverfolgen jeder Unteranforderung. Die Antwort enthält den Content-ID Header für jede entsprechende Unteranforderungsantwort, die für die Nachverfolgung verwendet werden soll.

Auf diese Anforderungsheader folgt eine obligatorische Leerzeile und dann die Definition für jede Unteranforderung. Der Text jeder Unteranforderung ist eine vollständige HTTP-Anforderung mit einem Verb, einer URL, Headern und text, die für die Anforderung erforderlich sind. Beachten Sie die folgenden Einschränkungen:

  • Die Unterabfragen sollten nicht enthalten x-ms-version header. Alle Unteranforderungen werden mit der Batchanforderungsversion der obersten Ebene ausgeführt.
  • Die Unteranforderungs-URL sollte nur den Pfad der URL (ohne host) aufweisen.
  • Jede Batchanforderung unterstützt maximal 256 Unteranforderungen.
  • Alle Unteranforderungen müssen denselben Anforderungstyp aufweisen.
  • Jede Unteranforderung wird separat autorisiert, mit den bereitgestellten Informationen in der Unteranforderung.
  • Jede Zeile im Anforderungstext sollte mit \r\n Zeichen enden.

Beispiel für eine Anforderung

POST http://account.blob.core.windows.net/?comp=batch HTTP/1.1 
Content-Type: multipart/mixed; boundary=batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
x-ms-version: 2018-11-09 
Authorization: SharedKey account:QvaoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI=
Host: 127.0.0.1:10000 
Content-Length: 1569 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 0 

DELETE /container0/blob0 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:G4jjBXA7LI/RnWKIOQ8i9xH4p76pAQ+4Fs4R1VxasaE= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 1 

DELETE /container1/blob1 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:IvCoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 2 

DELETE /container2/blob2 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:S37N2JTjcmOQVLHLbDmp2johz+KpTJvKhbVc4M7+UqI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525--

Antwort

Die Antwort enthält einen HTTP-status-Code und eine Reihe von Antwortheadern für die Batchanforderung der obersten Ebene. Die Antwort enthält auch Antwortinformationen für alle ihre Unterabfragen.

Antworttext

Die Batchantwort ist eine multipart/mixed Antwort, die die Antwort für jede Teilanforderung enthält. Die Antwort ist blockiert. Jede Unterresponse beginnt mit dem Content-Type: application/http Header. Der Content-ID Header folgt, wenn er in der Anforderung angegeben wurde. Darauf folgen die HTTP-Antwort status Code und Antwortheader für jede Teilanforderung.

Informationen zu den Headern, die von jeder Teilanforderung zurückgegeben werden, finden Sie in der Dokumentation zu den Vorgängen Blob löschen und Blobebene festlegen .

Beispiel für eine Antwort

HTTP/1.1 202 Accepted 
Transfer-Encoding: chunked 
Content-Type: multipart/mixed; boundary=batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
x-ms-request-id: 778fdc83-801e-0000-62ff-033467000000 
x-ms-version: 2018-11-09 

409
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 0 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e284f 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 1 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2851 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 2 

HTTP/1.1 404 The specified blob does not exist. 
x-ms-error-code: BlobNotFound 
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2852 
x-ms-version: 2018-11-09 
Content-Length: 216 
Content-Type: application/xml 

<?xml version="1.0" encoding="utf-8"?> 
<Error><Code>BlobNotFound</Code><Message>The specified blob does not exist. 
RequestId:778fdc83-801e-0000-62ff-0334671e2852 
Time:2018-06-14T16:46:54.6040685Z</Message></Error> 
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed-- 
0

Statuscode

Wenn die Batchanforderung wohlgeformt und autorisiert ist, gibt der Vorgang status Code 202 (Akzeptiert) zurück. Jede Unteranforderung hat je nach Ergebnis des Vorgangs eine eigene Antwort. Die Unteranforderung status wird im Antworttext zurückgegeben.

Weitere Informationen 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.

Authorization

Wenn restype=container nicht angegeben wird, müssen Sie die übergeordnete Batchanforderung mithilfe eines freigegebenen Schlüssels autorisieren. Sie können den Kontozugriffsschlüssel, eine kontoseitig freigegebene Zugriffssignatur oder Azure Active Directory verwenden. Details zu bestimmten Autorisierungsmechanismen finden Sie unten.

Wenn restype=container die Anforderung enthalten ist, können Sie die übergeordnete Batchanforderung über einen freigegebenen Schlüssel oder Azure Active Directory autorisieren. Sie können auch eine Autorisierung mit einer Shared Access Signature durchführen, die von einem dieser Autorisierungsmechanismen signiert ist. Details zu bestimmten Autorisierungsmechanismen finden Sie unten.

Jede Unteranforderung wird separat autorisiert. Eine Unteranforderung unterstützt dieselben Autorisierungsmechanismen, die der Vorgang unterstützt, wenn er nicht Teil eines Batchvorgangs ist.

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 eine Blob Batch übergeordnete Anforderung zu stellen, und die integrierte Azure RBAC-Rolle mit den geringsten Berechtigungen, 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 Blobdaten.

Abrechnung

Die Blob Batch REST-Anforderung wird als eine Transaktion gezählt, und jede einzelne Teilanforderung wird ebenfalls als eine Transaktion gezählt. Weitere Informationen zur Abrechnung für die einzelnen Unterabfragen finden Sie in der Dokumentation zu den Vorgängen Blob löschen und Blobebene festlegen .

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 Abrechnung des Kontos aus. Beispielsweise werden Lesetransaktionen einer anderen Abrechnungskategorie zugeordnet als Schreibtransaktionen. Die folgende Tabelle zeigt die Abrechnungskategorie für eine Blob Batch übergeordnete Anforderung basierend auf dem Speicherkontotyp:

Vorgang Speicherkontotyp Abrechnungskategorie
Blobbatch (Blobebene festlegen) Premium, Blockblob
Standard „Allgemein v2“		 Weitere Vorgänge

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

Hinweise

Einer der Standard Vorteile der Verwendung einer Batchanforderung ist die Verringerung der Anzahl von Verbindungen, die ein Client öffnen muss. Beachten Sie folgende Einschränkungen:

  • Unterstützte Unterabfragen im Batch sind Set Blob Tier (für Blockblobs) und Delete Blob.
  • Unterstützt nur bis zu 256 Unterabfragen in einem einzelnen Batch. Die Größe des Textkörpers für eine Batchanforderung darf 4 MB nicht überschreiten.
  • Eine leere Batchanforderung schlägt mit Code 400 (ungültige Anforderung) fehl.
  • Es gibt keine Garantien für die Reihenfolge der Ausführung der Batchunterabfragen.
  • Die Batch-Unteranforderungsausführung ist nicht atomar. Jede Unteranforderung wird unabhängig ausgeführt.
  • Jede Unteranforderung muss für eine Ressource innerhalb desselben Speicherkontos sein. Eine einzelne Batchanforderung unterstützt keine Ausführung von Anforderungen aus verschiedenen Speicherkonten.
  • Ein geschachtelter Anforderungstext wird nicht unterstützt.
  • Wenn der Server den Anforderungstext nicht analysiert, schlägt der gesamte Batch fehl, und es wird keine Anforderung ausgeführt.
  • Beachten Sie, dass die Konto-SAS der einzige Shared Access Signature-Typ ist, der von Blob Batchunterstützt wird, wenn der Batch nicht verwendet restype=container.

Bereich aller Unterabfragen für einen bestimmten Container

Ab REST-Version 2020-04-08 unterstützt die API das Blob Batch Eingrenzen von Teilabfragen an einen angegebenen Container. Wenn der Anforderungs-URI den Containernamen und den restype=container Parameter enthält, muss jede Unteranforderung für denselben Container gelten. Wenn der für eine Unteranforderung angegebene Containername nicht mit dem im URI angegebenen Containernamen übereinstimmt, gibt der Dienst den Fehlercode 400 (Ungültige Anforderung) zurück.

Alle für einen Container unterstützten Autorisierungsmechanismen sind für einen Blob Batch Vorgang gültig, der auf den Container ausgerichtet ist. Jede Teilanforderung sendet einen Autorisierungsheader an den Dienst.

Weitere Informationen

Autorisieren von Anforderungen an AzureStorage-Status und FehlercodesBlob Storage-FehlercodesFestlegen von Timeouts für Blob Storage-Vorgänge