Blob Batch

Artikel
05/15/2024

Å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. Batch-begäran och -svaret använder syntaxen för batchbearbetningsspecifikationen OData , med ändringar i semantik. 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. Tidsgränsparametern uttrycks i sekunder, med ett maximalt värde på 120 sekunder. Mer information finns i Ange tidsgränser för Blob Storage-åtgärder.
`restype`	Valfritt, version 2020-04-08 och senare. Det enda värdet som stöds för parametern `restype` är `container`. När den här parametern anges måste URI:n innehålla containernamnet. Alla underfrågor 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 används för alla underbegäran. Mer information finns i Versionshantering för Azure Storage-tjänsterna.
`Content-Length`	Krävs. Längden på begäran.
`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 loggningen 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 börjar med en batchgräns, följt av två obligatoriska rubriker: Content-Type huvudet med värdet application/httpoch Content-Transfer-Encoding huvudet med värdet binary. Detta följs av ett valfritt Content-ID huvud med ett strängvärde för att spåra vart och ett av underbegärandena. 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 för varje underbegäran är en fullständig HTTP-begäran med ett verb, en URL, rubriker och en brödtext som krävs för begäran. Observera följande varningar:

Underbegäran bör inte ha x-ms-version header. Alla underbegäranden körs med batchbegärans version på den översta nivån.
Underbegärande-URL:en ska 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 ha 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 underfrågor.

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 svarshuvuden för varje underbegäran.

Information om rubrikerna som returneras av varje underbegäran finns i dokumentationen för åtgärderna Ta bort blobb 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 också innehålla ytterligare standard-HTTP-huvuden. 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 eller Microsoft Entra. 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 Microsoft Entra. 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.

Viktigt

Microsoft rekommenderar att du använder Microsoft Entra ID med hanterade identiteter för att auktorisera begäranden till Azure Storage. Microsoft Entra ID ger överlägsen säkerhet och användarvänlighet jämfört med auktorisering av delad nyckel.

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, hanterad identitet 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:

Azure RBAC-åtgärd:Microsoft.Storage/storageAccounts/blobServices/containers/blobar/write
Minst privilegierad inbyggd roll:Storage Blob Data-deltagare

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

En signatur för delad åtkomst (SAS) ger säker delegerad åtkomst till resurser i ett lagringskonto. Med en SAS har du detaljerad kontroll över hur en klient kan komma åt data. Du kan ange vilken resurs klienten kan komma åt, vilka behörigheter de har till dessa resurser och hur länge SAS är giltigt.

Den Blob Batch överordnade begäran stöder signaturer för delad åtkomst för följande scenarier:

När restype=container utelämnas: Konto-SAS stöds
När restype=container ingår i begäran: Sas för användardelegering, tjänst-SAS och konto-SAS stöds

Vi rekommenderar att du använder Microsoft Entra autentiseringsuppgifter i stället för lagringskontonyckeln, vilket är enklare att kompromettera. Om din programdesign kräver signaturer för delad åtkomst använder du Microsoft Entra autentiseringsuppgifter för att skapa en SAS för användardelegering när det är möjligt.

När åtkomst med delad nyckel inte tillåts för lagringskontot tillåts inte en SAS-token för tjänsten eller en SAS-kontotoken för en begäran till Blob Storage. Mer information finns i Förstå hur nekande av delad nyckel påverkar SAS-token.

SAS för användardelegering

En SAS för användardelegering skyddas med Microsoft Entra autentiseringsuppgifter och även av de behörigheter som anges för SAS.

En Blob Batch överordnad begäran med en SAS-token som delegerats till en container eller blobresurs kräver behörigheten Skriv (w) som en del av SAS-token för användardelegering.

Mer information om SAS för användardelegering finns i Skapa en SAS för användardelegering.

Tjänst-SAS

En tjänst-SAS skyddas med lagringskontonyckeln. En tjänst-SAS delegerar åtkomst till en resurs i en enda Azure Storage-tjänst, till exempel bloblagring.

En Blob Batch överordnad begäran med en SAS-token som delegerats till en container eller blobresurs kräver behörigheten Skriv (w) som en del av tjänstens SAS-token.

Mer information om sas-tjänsten finns i Skapa en tjänst-SAS.

Konto-SAS

Ett SAS-konto skyddas med lagringskontonyckeln. En konto-SAS delegerar åtkomst till resurser i en eller flera av lagringstjänsterna. Alla åtgärder som är tillgängliga via en tjänst eller sas för användardelegering är också tillgängliga via ett konto-SAS.

Följande tabell anger den signerade resurstypen och signerade behörigheter som ska anges när åtkomst delegeras:

Åtgärd	Signerad tjänst	Signerad resurstyp	Signerad behörighet
Blob Batch (överordnad begäran)	Blob (b)	Objekt (o)	Skriva (w)

Mer information om kontots SAS finns i Skapa ett KONTO-SAS.

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 Azure Storage-status och felkoder Blob Storage-felkoder Ange tidsgränser för Blob Storage-åtgärder

Dela via