Blob Batch

  • Articolo

L'operazione Blob Batch consente l'incorporamento di più chiamate API in una singola richiesta HTTP. Questa API supporta due tipi di sottoquery: Impostare il livello BLOB per i BLOB in blocchi ed Eliminare BLOB. La risposta restituita dal server per una richiesta batch contiene i risultati per ogni sottoquery nel batch. La richiesta e la risposta batch usano la sintassi della OData specifica di elaborazione batch, con modifiche alla semantica. Questa API è disponibile a partire dalla versione 2018-11-09.

Richiesta

È possibile costruire la Blob Batch richiesta come indicato di seguito. È consigliato il protocollo HTTPS. Sostituire myaccount con il nome dell'account di archiviazione.

Metodo URI richiesta Versione HTTP
POST https://myaccount.blob.core.windows.net/?comp=batch

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

Parametri URI

È possibile specificare i parametri aggiuntivi seguenti nell'URI della richiesta.

Parametro Descrizione
timeout Facoltativa. Il parametro di timeout è espresso in secondi, con un valore massimo di 120 secondi. Per altre informazioni, vedere Impostazione dei timeout per le operazioni di archiviazione BLOB.
restype Facoltativo, versione 2020-04-08 e successive. L'unico valore supportato per il restype parametro è container. Quando questo parametro viene specificato, l'URI deve includere il nome del contenitore. Qualsiasi sottoquery deve avere come ambito lo stesso contenitore.

Intestazioni della richiesta

Nella seguente tabella vengono descritte le intestazioni di richiesta obbligatorie e facoltative.

Intestazione della richiesta Descrizione
Authorization Obbligatorio. Specifica lo schema di autorizzazione, il nome dell'account di archiviazione e la firma. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
Date o x-ms-date Obbligatorio. Specifica la data per la richiesta nel fuso orario UTC (Coordinated Universal Time). Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
x-ms-version Obbligatorio per tutte le richieste autorizzate. Specifica la versione dell'operazione da usare per questa richiesta. Questa versione verrà usata per tutte le sottoquery. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
Content-Length Obbligatorio. Lunghezza della richiesta.
Content-Type Obbligatorio. Il valore di questa intestazione deve essere multipart/mixed, con un limite batch. Valore di intestazione di esempio: multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252.
x-ms-client-request-id facoltativo. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log al momento della configurazione della registrazione. È consigliabile usare questa intestazione per correlare le attività lato client alle richieste ricevute dal server. Per altre informazioni, vedere Monitorare Archiviazione BLOB di Azure.

Testo della richiesta

Il corpo della richiesta per un batch BLOB contiene un elenco di tutte le sottoquery. Il formato usa la sintassi della OData specifica batch, con modifiche alla semantica.

Il corpo della richiesta inizia con un limite batch, seguito da due intestazioni obbligatorie: l'intestazione Content-Type con il valore application/httpe l'intestazione Content-Transfer-Encoding con il valore binary. Viene seguita da un'intestazione facoltativa Content-ID , con un valore stringa per tenere traccia di ogni sottoquery. La risposta contiene l'intestazione Content-ID per ogni risposta di sottoquery corrispondente da usare per il rilevamento.

Queste intestazioni di richiesta sono seguite da una riga vuota obbligatoria e quindi dalla definizione per ogni sottoquery. Il corpo di ogni sottoquery è una richiesta HTTP completa con verbo, URL, intestazioni e corpo necessari per la richiesta. Si notino le avvertenze seguenti:

  • Le sottoquery non devono avere .x-ms-version header Tutte le sottoquery vengono eseguite con la versione di richiesta batch di primo livello.
  • L'URL della sottoquery deve avere solo il percorso dell'URL (senza l'host).
  • Ogni richiesta batch supporta un massimo di 256 sottoquery.
  • Tutte le sottoquery devono essere dello stesso tipo di richiesta.
  • Ogni sottoquery viene autorizzata separatamente, con le informazioni fornite nella sottoquery.
  • Ogni riga nel corpo della richiesta deve terminare con \r\n caratteri.

Richiesta di esempio

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

Risposta

La risposta include un codice di stato HTTP e un set di intestazioni di risposta per la richiesta batch di primo livello. La risposta include anche informazioni sulla risposta per tutte le relative sottoquery.

Corpo della risposta

La risposta batch è una multipart/mixed risposta che contiene la risposta per ogni sottoquery. La risposta è in blocchi. Ogni sottorisponse inizia con l'intestazione Content-Type: application/http . L'intestazione Content-ID segue, se è stata specificata nella richiesta. Questo è seguito dal codice di stato della risposta HTTP e dalle intestazioni di risposta per ogni sottoquery.

Per informazioni sulle intestazioni restituite da ogni sottoquery, vedere la documentazione per le operazioni Elimina BLOB e Imposta livello BLOB .

Risposta di esempio

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

Codice stato

Se la richiesta batch è ben formata e autorizzata, l'operazione restituisce il codice di stato 202 (accettato). Ogni sottoquery ha una propria risposta, a seconda del risultato dell'operazione. Lo stato della sottoquery viene restituito nel corpo della risposta.

Per altre informazioni, vedere Codici di stato e di errore.

Intestazioni di risposta

Nella risposta per questa operazione sono incluse le intestazioni riportate di seguito; Nella risposta possono anche essere incluse intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.

Autorizzazione

Quando restype=container viene omesso, è necessario autorizzare la richiesta batch padre usando una chiave condivisa. È possibile usare la chiave di accesso dell'account, una firma di accesso condiviso dell'account o Azure Active Directory. Dettagli per meccanismi di autorizzazione specifici illustrati di seguito.

Quando restype=container viene incluso nella richiesta, è possibile autorizzare la richiesta batch padre tramite una chiave condivisa o Azure Active Directory. È anche possibile autorizzare con una firma di accesso condiviso firmata da uno di questi meccanismi di autorizzazione. Dettagli per meccanismi di autorizzazione specifici illustrati di seguito.

Ogni sottoquery viene autorizzata separatamente. Una sottoquery supporta gli stessi meccanismi di autorizzazione supportati dall'operazione quando non fa parte di un'operazione batch.

Archiviazione di Azure supporta l'uso di Microsoft Entra ID per autorizzare le richieste ai dati BLOB. Con Microsoft Entra ID è possibile usare il controllo degli accessi in base al ruolo di Azure per concedere le autorizzazioni a un'entità di sicurezza. L'entità di sicurezza può essere un utente, un gruppo, un'entità servizio applicazione o un'identità gestita di Azure. L'entità di sicurezza viene autenticata da Microsoft Entra ID per restituire un token OAuth 2.0. Il token può quindi essere usato per autorizzare una richiesta relativa al servizio BLOB.

Per altre informazioni sull'autorizzazione tramite Microsoft Entra ID, vedere Autorizzare l'accesso ai BLOB usando Microsoft Entra ID.

Autorizzazioni

Di seguito è riportata l'azione controllo degli accessi in base al ruolo necessaria per un utente, un gruppo o un'entità servizio di Microsoft Entra per effettuare una Blob Batch richiesta padre e il ruolo controllo degli accessi in base al ruolo di Azure con privilegi minimi che include questa azione:

Per altre informazioni sull'assegnazione dei ruoli tramite il controllo degli accessi in base al ruolo di Azure, vedere Assegnare un ruolo di Azure per l'accesso ai dati BLOB.

Fatturazione

La Blob Batch richiesta REST viene conteggiata come una transazione e ogni singola sottoquery viene conteggiata anche come una transazione. Per altre informazioni sulla fatturazione per le singole sottoquery, vedere la documentazione per le operazioni Elimina BLOB e Imposta livello BLOB .

Le richieste di determinazione dei prezzi possono provenire dai client che usano le API di archiviazione BLOB, direttamente tramite l'API REST di Archiviazione BLOB o da una libreria client di Archiviazione di Azure. Queste richieste accumulano addebiti per transazione. Il tipo di transazione influisce sul modo in cui viene addebitato l'account. Ad esempio, le transazioni di lettura si accumulano in una categoria di fatturazione diversa rispetto alle transazioni di scrittura. La tabella seguente illustra la categoria di fatturazione per una Blob Batch richiesta padre in base al tipo di account di archiviazione:

Operazione Tipo di account di archiviazione Categoria di fatturazione
Blob Batch (imposta livello BLOB) BLOB in blocchi Premium
Utilizzo generico v2 Standard		 Altre operazioni

Per informazioni sui prezzi per la categoria di fatturazione specificata, vedere prezzi Archiviazione BLOB di Azure.

Commenti

Uno dei principali vantaggi dell'uso di una richiesta batch è la riduzione del numero di connessioni che un client deve aprire. Prendere nota delle restrizioni seguenti:

  • Le sottoquery supportate nel batch sono Set Blob Tier (per i BLOB in blocchi) e Delete Blob.
  • Supporta solo fino a 256 sottoquery in un singolo batch. Le dimensioni del corpo per una richiesta batch non possono superare i 4 MB.
  • Una richiesta batch vuota ha esito negativo con codice 400 (richiesta non valida).
  • Non esistono garanzie sull'ordine di esecuzione delle sottoquery batch.
  • L'esecuzione di sottoquery batch non è atomica. Ogni sottoquery viene eseguita in modo indipendente.
  • Ogni sottoquery deve essere per una risorsa all'interno dello stesso account di archiviazione. Una singola richiesta batch non supporta l'esecuzione di richieste da account di archiviazione diversi.
  • Il corpo di una richiesta annidata non è supportato.
  • Se il server non riesce ad analizzare il corpo della richiesta, l'intero batch ha esito negativo e non verrà eseguita alcuna richiesta.
  • Si noti che la firma di accesso condiviso dell'account è l'unico tipo di firma di accesso condiviso supportato da Blob Batch, quando il batch non usa restype=container.

Definire l'ambito di tutte le sottoquery in un contenitore specifico

A partire dalla versione REST 2020-04-08, l'API supporta la definizione dell'ambito Blob Batch delle sottoquery in un contenitore specificato. Quando l'URI della richiesta include il nome del contenitore e il restype=container parametro , ogni sottoquery deve essere applicata allo stesso contenitore. Se il nome del contenitore specificato per una sottoquery non corrisponde al nome del contenitore specificato nell'URI, il servizio restituisce il codice di errore 400 (richiesta non valida).

Tutti i meccanismi di autorizzazione supportati per un contenitore sono validi per un'operazione Blob Batch con ambito nel contenitore. Ogni sottoquery invia un'intestazione di autorizzazione al servizio.

Vedi anche

Autorizzare le richieste allo stato dell'archiviazione di Azuree ai codici di erroredell'archiviazione BLOB Codici di erroreImpostazione dei timeout per le operazioni di archiviazione BLOB