Blob Batch

  • Artikel

Åtgärden Blob Batch gör att flera API-anrop kan bäddas in i en enda HTTP-begäran. Det här API:et stöder två typer av underbegäranden: Ange blobnivå för blockblobar och Ta bort blob. Svaret som returneras av servern för en batchbegäran innehåller resultatet för varje underbegäran i batchen. Batchbegäran och -svaret använder syntaxen för batchbearbetningsspecifikationen OData , med ändringar i semantiken. Det här API:et är tillgängligt från och med version 2018-11-09.

Förfrågan

Du kan skapa begäran på Blob Batch följande sätt. HTTPS rekommenderas. Ersätt myaccount med namnet på ditt lagringskonto.

Metod URI för förfrågan 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-parametrar

Du kan ange följande ytterligare parametrar för begärande-URI:n.

Parameter Beskrivning
timeout Valfritt. Timeout-parametern uttrycks i sekunder med ett maxvärde på 120 sekunder. Mer information finns i Ställa in tidsgränser för Blob Storage-åtgärder.
restype Valfritt, version 2020-04-08 och senare. Det enda värde som stöds för parametern restype är container. När den här parametern anges måste URI:n innehålla containernamnet. Alla underbegärande måste vara begränsade till samma container.

Begärandehuvuden

I följande tabell beskrivs obligatoriska och valfria begärandehuvuden.

Begärandehuvud Beskrivning
Authorization Krävs. Anger auktoriseringsschema, lagringskontonamn och signatur. Mer information finns i Auktorisera begäranden till Azure Storage.
Date eller x-ms-date Krävs. Anger Coordinated Universal Time (UTC) för begäran. Mer information finns i Auktorisera begäranden till Azure Storage.
x-ms-version Krävs för alla auktoriserade begäranden. Anger vilken version av åtgärden som ska användas för den här begäran. Den här versionen kommer att användas för alla underbegäran. Mer information finns i Versionshantering för Azure Storage-tjänsterna.
Content-Length Krävs. Begärans längd.
Content-Type Krävs. Värdet för det här huvudet måste vara multipart/mixed, med en batchgräns. Exempelhuvudvärde: multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252.
x-ms-client-request-id Valfritt. Tillhandahåller ett klientgenererat, täckande värde med en teckengräns på 1 kibibyte (KiB) som registreras i loggarna när loggning har konfigurerats. Vi rekommenderar starkt att du använder det här huvudet för att korrelera aktiviteter på klientsidan med begäranden som servern tar emot. Mer information finns i Övervaka Azure Blob Storage.

Begärandetext

Begärandetexten för en blobbatch innehåller en lista över alla underbegäranden. Formatet använder syntaxen för batchspecifikationen OData , med ändringar i semantik.

Begärandetexten Content-Transfer-Encoding börjar med en batchgräns, följt av två obligatoriska rubriker: Content-Type huvudet med värdet application/httpoch rubriken med värdet binary. Detta följs av en valfri Content-ID rubrik med ett strängvärde för att spåra varje underbegäran. Svaret innehåller Content-ID huvudet för varje motsvarande underbegärandesvar som ska användas för spårning.

Dessa begärandehuvuden följs av en obligatorisk tom rad och sedan definitionen för varje underbegäran. Brödtexten i varje underbegäran är en fullständig HTTP-begäran med ett verb, URL, rubriker och brödtext som behövs för begäran. Observera följande varningar:

  • Underbegärandena ska inte ha x-ms-version header. Alla underbegäranden körs med batchbegärandeversionen på den högsta nivån.
  • Underbegärande-URL:en bör bara ha sökvägen till URL:en (utan värden).
  • Varje batchbegäran stöder högst 256 underbegäranden.
  • Alla underbegäranden måste vara av samma typ av begäran.
  • Varje underbegäran auktoriseras separat, med den angivna informationen i underbegäran.
  • Varje rad i begärandetexten ska sluta med \r\n tecken.

Exempelbegäran

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

Svarsåtgärder

Svaret innehåller en HTTP-statuskod och en uppsättning svarshuvuden för batchbegäran på den översta nivån. Svaret innehåller även svarsinformation för alla dess underbegäran.

Själva svaret

Batchsvaret är ett multipart/mixed svar som innehåller svaret för varje underbegäran. Svaret är segmenterat. Varje underrespons börjar med Content-Type: application/http rubriken. Rubriken Content-ID följer, om den angavs i begäran. Detta följs av HTTP-svarsstatuskoden och svarshuvudena för varje underbegäran.

Information om rubrikerna som returneras av varje underbegäran finns i dokumentationen för åtgärderna Ta bort blob och Ange blobnivå .

Exempelsvar

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

Statuskod

Om batchbegäran är väl utformad och auktoriserad returnerar åtgärden statuskod 202 (godkänd). Varje underbegäran har sitt eget svar, beroende på resultatet av åtgärden. Status för underbegäran returneras i svarstexten.

Mer information finns i Status och felkoder.

Svarshuvuden

Svaret för den här åtgärden innehåller följande rubriker. Svaret kan även innehålla ytterligare HTTP-standardhuvuden. Alla standardhuvuden överensstämmer med http/1.1-protokollspecifikationen.

Auktorisering

När restype=container utelämnas måste du auktorisera den överordnade batchbegäran med hjälp av en delad nyckel. Du kan använda kontoåtkomstnyckeln, en signatur för delad åtkomst för kontot eller Azure Active Directory. Information om specifika auktoriseringsmekanismer som visas nedan.

När restype=container ingår i begäran kan du auktorisera den överordnade batchbegäran via en delad nyckel eller Azure Active Directory. Du kan också auktorisera med en signatur för delad åtkomst som är signerad av någon av dessa auktoriseringsmekanismer. Information om specifika auktoriseringsmekanismer som visas nedan.

Varje underbegäran auktoriseras separat. En underbegäran stöder samma auktoriseringsmekanismer som åtgärden stöder när den inte ingår i en batchåtgärd.

Azure Storage stöder användning av Microsoft Entra ID för att auktorisera begäranden till blobdata. Med Microsoft Entra ID kan du använda rollbaserad åtkomstkontroll i Azure (Azure RBAC) för att bevilja behörigheter till ett säkerhetsobjekt. Säkerhetsobjektet kan vara en användare, grupp, programtjänstens huvudnamn eller en hanterad Azure-identitet. Säkerhetsobjektet autentiseras av Microsoft Entra ID för att returnera en OAuth 2.0-token. Token kan sedan användas för att auktorisera en begäran mot Blob-tjänsten.

Mer information om auktorisering med Microsoft Entra ID finns i Auktorisera åtkomst till blobar med Microsoft Entra ID.

Behörigheter

Nedan visas den RBAC-åtgärd som krävs för att en Microsoft Entra användare, grupp eller tjänstens huvudnamn ska kunna göra en Blob Batch överordnad begäran och den minst privilegierade inbyggda Azure RBAC-rollen som innehåller den här åtgärden:

Mer information om hur du tilldelar roller med Azure RBAC finns i Tilldela en Azure-roll för åtkomst till blobdata.

Fakturering

Blob Batch REST-begäran räknas som en transaktion och varje enskild underbegäran räknas också som en transaktion. Mer information om fakturering för enskilda underbegäranden finns i dokumentationen för åtgärderna Ta bort blobb och Ange blobnivå .

Prisbegäranden kan komma från klienter som använder Blob Storage-API:er, antingen direkt via REST-API:et för Blob Storage eller från ett Azure Storage-klientbibliotek. Dessa begäranden ackumulerar avgifter per transaktion. Typen av transaktion påverkar hur kontot debiteras. Lästransaktioner till exempel tillfaller en annan faktureringskategori än skrivtransaktioner. I följande tabell visas faktureringskategorin för en Blob Batch överordnad begäran baserat på lagringskontotypen:

Åtgärd Typ av lagringskonto Faktureringskategori
Blob Batch (ange blobnivå) Premium-blockblob
Standard generell användning v2		 Andra åtgärder

Mer information om priser för den angivna faktureringskategorin finns i Azure Blob Storage Prissättning.

Kommentarer

En av de största fördelarna med att använda en batchbegäran är minskningen av antalet anslutningar som en klient måste öppna. Observera följande begränsningar:

  • Underbegäran som stöds i batchen är Set Blob Tier (för blockblobar) och Delete Blob.
  • Stöder endast upp till 256 underbegäran i en enda batch. Storleken på brödtexten för en batchbegäran får inte överstiga 4 MB.
  • En tom batchbegäran misslyckas med kod 400 (felaktig begäran).
  • Det finns inga garantier för körningsordningen för batchunderbegäran.
  • Körning av batchunderbegäran är inte atomisk. Varje underbegäran körs oberoende av varandra.
  • Varje underbegäran måste vara för en resurs i samma lagringskonto. En enda batchbegäran har inte stöd för att köra begäranden från olika lagringskonton.
  • En kapslad begärandetext stöds inte.
  • Om servern inte parsar begärandetexten misslyckas hela batchen och ingen begäran körs.
  • Observera att konto-SAS är den enda signaturtypen för delad åtkomst som stöds av Blob Batch, när batchen inte använder restype=container.

Omfång för alla underfrågor till en specifik container

Från och med REST version 2020-04-08 stöder API:et Blob Batch omfångsunderbegäran till en angiven container. När begärans URI innehåller containernamnet och parametern restype=container måste varje underbegäran tillämpas på samma container. Om containernamnet som angetts för en underbegäran inte matchar containernamnet som anges i URI returnerar tjänsten felkoden 400 (felaktig begäran).

Alla auktoriseringsmekanismer som stöds för en container är giltiga för en Blob Batch åtgärd som är begränsad till containern. Varje underbegäran skickar ett auktoriseringshuvud till tjänsten.

Se även

Auktorisera begäranden till AzureStorage-status och felkoderBlob Storage-felkoderAnge tidsgränser för Blob Storage-åtgärder