Delen via

Blobbatch

  • Artikel

Met Blob Batch de bewerking kunnen meerdere API-aanroepen worden ingesloten in één HTTP-aanvraag. Deze API ondersteunt twee typen subverzoeken: Blob-laag instellen voor blok-blobs en Blob verwijderen. Het antwoord dat door de server voor een batchaanvraag wordt geretourneerd, bevat de resultaten voor elke subaanvraag in de batch. De batchaanvraag en het antwoord maken gebruik van de syntaxis van de OData specificatie voor batchverwerking, met wijzigingen in de semantiek. Deze API is beschikbaar vanaf versie 2018-11-09.

Aanvraag

U kunt de Blob Batch aanvraag als volgt samenstellen. HTTPS wordt aanbevolen. Vervang myaccount door de naam van uw opslagaccount.

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

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

URI-parameters

U kunt de volgende aanvullende parameters opgeven voor de aanvraag-URI.

Parameter Beschrijving
timeout Optioneel. De time-outparameter wordt uitgedrukt in seconden, met een maximumwaarde van 120 seconden. Zie Time-outs instellen voor Blob Storage-bewerkingen voor meer informatie.
restype Optioneel, versie 2020-04-08 en hoger. De enige waarde die wordt ondersteund voor de restype parameter is container. Wanneer deze parameter is opgegeven, moet de URI de containernaam bevatten. Subverzoeken moeten zijn gericht op dezelfde container.

Aanvraagheaders

In de volgende tabel worden vereiste en optionele aanvraagheaders beschreven.

Aanvraagheader Beschrijving
Authorization Vereist. Hiermee geeft u het autorisatieschema, de naam van het opslagaccount en de handtekening op. Zie Aanvragen autoriseren voor Azure Storage voor meer informatie.
Date of x-ms-date Vereist. Geef de Coordinated Universal Time (UTC) op voor de aanvraag. Zie Aanvragen autoriseren voor Azure Storage voor meer informatie.
x-ms-version Vereist voor alle geautoriseerde aanvragen. Hiermee geeft u de versie van de bewerking te gebruiken voor deze aanvraag. Deze versie wordt gebruikt voor alle subverzoeken. Zie Versiebeheer voor de Azure Storage-services voor meer informatie.
Content-Length Vereist. De lengte van de aanvraag.
Content-Type Vereist. De waarde van deze header moet zijn multipart/mixed, met een batchgrens. Voorbeeld van headerwaarde: multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252.
x-ms-client-request-id Optioneel. Biedt een door de client gegenereerde, ondoorzichtige waarde met een limiet van 1 kibibyte (KiB) die wordt vastgelegd in de logboeken wanneer logboekregistratie is geconfigureerd. We raden u ten zeerste aan deze header te gebruiken om activiteiten aan de clientzijde te correleren met aanvragen die de server ontvangt. Zie Azure Blob Storage bewaken voor meer informatie.

Aanvraagbody

De aanvraagbody voor een blobbatch bevat een lijst met alle subaanvragen. De indeling maakt gebruik van de syntaxis van de OData batchspecificatie, met wijzigingen in de semantiek.

De aanvraagbody begint met een batchgrens, gevolgd door twee verplichte headers: de Content-Type header met de waarde application/httpen de Content-Transfer-Encoding header met de waarde binary. Dit wordt gevolgd door een optionele Content-ID header, met een tekenreekswaarde om elk van de subvragen bij te houden. Het antwoord bevat de Content-ID header voor elk corresponderend subverzoekantwoord dat moet worden gebruikt voor het bijhouden.

Deze aanvraagheaders worden gevolgd door een verplichte lege regel en vervolgens de definitie voor elke subaanvraag. De hoofdtekst van elke subaanvraag is een volledige HTTP-aanvraag met een werkwoord, URL, headers en hoofdtekst die nodig zijn voor de aanvraag. Let op de volgende opmerkingen:

  • De subvragen mogen niet de x-ms-version headerhebben. Alle subaanvragen worden uitgevoerd met de batchaanvraagversie op het hoogste niveau.
  • De subaanvraag-URL mag alleen het pad van de URL hebben (zonder de host).
  • Elke batchaanvraag ondersteunt maximaal 256 subaanvragen.
  • Alle subaanvragen moeten van hetzelfde aanvraagtype zijn.
  • Elke subaanvraag wordt afzonderlijk geautoriseerd, met de opgegeven informatie in de subaanvraag.
  • Elke regel in de aanvraagtekst moet eindigen met \r\n tekens.

Voorbeeldaanvraag

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

Antwoord

Het antwoord bevat een HTTP-statuscode en een set antwoordheaders voor de batchaanvraag op het hoogste niveau. Het antwoord bevat ook antwoordinformatie voor alle subvragen.

Hoofdtekst van de reactie

Het batchantwoord is een multipart/mixed antwoord, dat het antwoord voor elke subaanvraag bevat. Het antwoord is gesegmenteerd. Elk subantwoord begint met de Content-Type: application/http header. De Content-ID header volgt, als deze is opgegeven in de aanvraag. Dit wordt gevolgd door de http-antwoordstatuscode en antwoordheaders voor elke subaanvraag.

Zie de documentatie voor de bewerkingen Blob verwijderen en Blob-laaginstellen voor informatie over de headers die door elke subaanvraag worden geretourneerd.

Voorbeeldantwoord

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

Als de batchaanvraag goed is opgemaakt en geautoriseerd, retourneert de bewerking statuscode 202 (Geaccepteerd). Elke subaanvraag heeft een eigen antwoord, afhankelijk van het resultaat van de bewerking. De status van de subaanvraag wordt geretourneerd in de hoofdtekst van het antwoord.

Zie Status en foutcodes voor meer informatie.

Antwoordheaders

Het antwoord voor deze bewerking bevat de volgende headers. Het antwoord kan ook extra standaard-HTTP-headers bevatten. Alle standaardheaders voldoen aan de HTTP/1.1-protocolspecificatie.

Autorisatie

Wanneer restype=container wordt weggelaten, moet u de bovenliggende batchaanvraag autoriseren met behulp van een gedeelde sleutel. U kunt de toegangssleutel van het account, een handtekening voor gedeelde toegang van een account of Microsoft Entra gebruiken. Details voor specifieke autorisatiemechanismen die hieronder worden weergegeven.

Wanneer restype=container is opgenomen in de aanvraag, kunt u de bovenliggende batchaanvraag autoriseren via een gedeelde sleutel of Microsoft Entra. U kunt ook autoriseren met een Shared Access Signature die is ondertekend door een van deze autorisatiemechanismen. Details voor specifieke autorisatiemechanismen die hieronder worden weergegeven.

Elke subaanvraag wordt afzonderlijk geautoriseerd. Een subaanvraag ondersteunt dezelfde autorisatiemechanismen die de bewerking ondersteunt wanneer deze geen deel uitmaakt van een batchbewerking.

Belangrijk

Microsoft raadt het gebruik van Microsoft Entra ID met beheerde identiteiten aan om aanvragen voor Azure Storage te autoriseren. Microsoft Entra ID biedt superieure beveiliging en gebruiksgemak in vergelijking met autorisatie met gedeelde sleutels.

Azure Storage ondersteunt het gebruik van Microsoft Entra ID om aanvragen voor blobgegevens te autoriseren. Met Microsoft Entra ID kunt u op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC) gebruiken om machtigingen te verlenen aan een beveiligingsprincipal. De beveiligingsprincipal kan een gebruiker, groep, toepassingsservice-principal of beheerde Azure-identiteit zijn. De beveiligingsprincipal wordt geverifieerd door Microsoft Entra ID om een OAuth 2.0-token te retourneren. Het token kan vervolgens worden gebruikt om een aanvraag voor de Blob-service te autoriseren.

Zie Toegang tot blobs autoriseren met Microsoft Entra ID voor meer informatie over autorisatie met behulp van Microsoft Entra ID.

Machtigingen

Hieronder vindt u de RBAC-actie die nodig is voor een Microsoft Entra gebruiker, groep, beheerde identiteit of service-principal om een Blob Batch bovenliggende aanvraag te doen, en de ingebouwde Azure RBAC-rol met de minste bevoegdheden die deze actie omvat:

Zie Een Azure-rol toewijzen voor toegang tot blobgegevens voor meer informatie over het toewijzen van rollen met behulp van Azure RBAC.

Billing

De Blob Batch REST-aanvraag wordt geteld als één transactie en elke afzonderlijke subaanvraag wordt ook geteld als één transactie. Zie de documentatie voor de bewerkingen Blob verwijderen en Blob-laaginstellen voor meer informatie over facturering voor de afzonderlijke subverzoeken.

Prijsaanvragen kunnen afkomstig zijn van clients die gebruikmaken van Blob Storage-API's, rechtstreeks via de Blob Storage REST API of vanuit een Azure Storage-clientbibliotheek. Met deze aanvragen worden kosten per transactie in rekening gebracht. Het type transactie is van invloed op de manier waarop de rekening in rekening wordt gebracht. Leestransacties hebben bijvoorbeeld een andere factureringscategorie dan schrijftransacties. In de volgende tabel ziet u de factureringscategorie voor een Blob Batch bovenliggende aanvraag op basis van het type opslagaccount:

Bewerking Type opslagaccount Factureringscategorie
BlobBatch (bloblaag instellen) Premium blok-blob
Standaard v2 voor algemeen gebruik		 Andere bewerkingen

Zie prijzen voor Azure Blob Storage voor meer informatie over prijzen voor de opgegeven factureringscategorie.

Opmerkingen

Een van de belangrijkste voordelen van het gebruik van een batchaanvraag is de vermindering van het aantal verbindingen dat een client moet openen. Houd rekening met de volgende beperkingen:

  • Ondersteunde subverzoeken in de batch zijn Set Blob Tier (voor blok-blobs) en Delete Blob.
  • Ondersteunt maximaal 256 subverzoeken in één batch. De grootte van de hoofdtekst voor een batchaanvraag mag niet groter zijn dan 4 MB.
  • Een lege batchaanvraag mislukt met code 400 (ongeldige aanvraag).
  • Er zijn geen garanties voor de volgorde van uitvoering van de batchsubvragen.
  • Uitvoering van batchsubrequest is niet atomisch. Elke subaanvraag wordt onafhankelijk uitgevoerd.
  • Elke subaanvraag moet betrekking hebben op een resource in hetzelfde opslagaccount. Eén batchaanvraag biedt geen ondersteuning voor het uitvoeren van aanvragen van verschillende opslagaccounts.
  • Een geneste aanvraagbody wordt niet ondersteund.
  • Als de server de aanvraagbody niet kan parseren, mislukt de hele batch en wordt er geen aanvraag uitgevoerd.
  • Houd er rekening mee dat account-SAS het enige shared access signature-type is dat wordt ondersteund door Blob Batch, wanneer de batch niet wordt gebruikt restype=container.

Bereik van alle subvragen naar een specifieke container

Vanaf REST-versie 2020-04-08 ondersteunt de Blob Batch API het bereik van subvragen naar een opgegeven container. Wanneer de aanvraag-URI de containernaam en de restype=container parameter bevat, moet elke subaanvraag van toepassing zijn op dezelfde container. Als de containernaam die is opgegeven voor een subaanvraag niet overeenkomt met de containernaam die in de URI is opgegeven, retourneert de service foutcode 400 (Ongeldige aanvraag).

Alle autorisatiemechanismen die voor een container worden ondersteund, zijn geldig voor een Blob Batch bewerking die is gericht op de container. Elke subaanvraag verzendt een autorisatieheader naar de service.

Zie ook

Aanvragen autoriseren voor Azure Storage-statusen foutcodesBlob Storage-foutcodesTime-outs instellen voor Blob Storage-bewerkingen