Condividi tramite

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 all'account, una firma di accesso condiviso dell'account o Microsoft Entra. 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 Microsoft Entra. È 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.

Importante

Microsoft consiglia di usare Microsoft Entra ID con identità gestite per autorizzare le richieste ad Archiviazione di Azure. Microsoft Entra ID offre maggiore sicurezza e facilità d'uso rispetto all'autorizzazione con chiave condivisa.

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 usando Microsoft Entra ID, vedere Autorizzare l'accesso ai BLOB usando Microsoft Entra ID.

Autorizzazioni

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

Per altre informazioni sull'assegnazione dei ruoli tramite 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 sottorequesta viene conteggiata anche come una transazione. Per altre informazioni sulla fatturazione per le singole sottoquesthe, vedere la documentazione per le operazioni Elimina BLOB e Imposta livello BLOB .

Le richieste di prezzi possono derivare dai client che usano le API di archiviazione BLOB, direttamente tramite l'API REST dell'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. Nella tabella seguente viene illustrata 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 di 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 vantaggi principali dell'uso di una richiesta batch è la riduzione del numero di connessioni che un client deve aprire. Prendere nota delle restrizioni seguenti:

  • Le sottoquest supportate nel batch sono Set Blob Tier (per i BLOB a blocchi) e Delete Blob.
  • Supporta solo fino a 256 sottoquestre in un singolo batch. Le dimensioni del corpo per una richiesta batch non possono superare i 4 MB.
  • Una richiesta batch vuota non riesce con il codice 400 (richiesta non valida).
  • Non esistono garanzie sull'ordine di esecuzione delle sottoquestre batch.
  • L'esecuzione di subrequest batch non è atomica. Ogni sottorequesto viene eseguito in modo indipendente.
  • Ogni sottoquesto 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.
  • Un corpo della richiesta annidato non è supportato.
  • Se il server non riesce a 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.

Ambito di tutte le sottoquestre a un contenitore specifico

A partire dalla versione REST 2020-04-08, l'API Blob Batch supporta le sottoquestre di ambito in un contenitore specificato. Quando l'URI della richiesta include il nome del contenitore e il restype=container parametro, ogni sottorequest deve essere applicato allo stesso contenitore. Se il nome del contenitore specificato per una subrequest 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 subrequest invia un'intestazione di autorizzazione al servizio.

Vedi anche

Autorizzare le richieste allo stato di archiviazionedi Azure e ai codici di errore diArchiviazione BLOB Codici di erroreImpostazione timeout per le operazioni di archiviazione BLOB