Put Block

  • Articolo

Tramite l'operazione Put Block viene creato un nuovo blocco di cui eseguire il commit come parte di un Blob.

Richiesta

È possibile costruire la Put Block richiesta come indicato di seguito. È consigliabile usare HTTPS. Sostituire myaccount con il nome dell'account di archiviazione:

URI della richiesta del metodo PUT Versione HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=id HTTP/1.1

Richiesta di servizio di archiviazione emulata

Quando si effettua una richiesta per il servizio di archiviazione emulato, specificare il nome host dell'emulatore e la porta del servizio BLOB come 127.0.0.1:10000, seguito dal nome dell'account di archiviazione emulato:

URI della richiesta del metodo PUT Versione HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=block&blockid=id HTTP/1.1

Per altre informazioni, vedere Usare l'emulatore Azurite per lo sviluppo locale di Archiviazione di Azure.

Parametri URI

Parametro Descrizione
blockid Obbligatorio. Valore stringa con codifica Base64 valido che identifica il blocco. Prima della codifica, la stringa deve essere minore o uguale a 64 byte.

Per un BLOB specificato, la lunghezza del valore per il blockid parametro deve essere la stessa dimensione per ogni blocco.

Nota: la stringa Base64 deve essere codificata con URL.
timeout facoltativo. Il parametro timeout viene espresso in secondi. Per altre informazioni, vedere Impostare i timeout per le operazioni del servizio BLOB.

Intestazioni della richiesta

Le intestazioni di richiesta obbligatorie e facoltative sono descritte nella tabella seguente:

Intestazione della richiesta Descrizione
Authorization Obbligatorio. Specifica lo schema di autorizzazione, il nome dell'account 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. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
Content-Length Obbligatorio. Lunghezza del contenuto del blocco in byte. Il blocco deve essere minore o uguale a 4.000 mebibyte (MiB) per la versione 2019-12-12 e successive. Vedere la sezione Osservazioni per i limiti nelle versioni precedenti.

Quando la lunghezza non viene specificata, l'operazione ha esito negativo con il codice di stato 411 (Lunghezza obbligatoria).
Content-MD5 facoltativo. Hash MD5 del contenuto del blocco. Questo hash viene utilizzato per verificare l'integrità del blocco durante il trasporto. Quando questa intestazione viene specificata, il servizio di archiviazione confronta l'hash del contenuto ricevuto con il valore di questa intestazione.

Nota: questo hash MD5 non viene archiviato con il BLOB.

Se i due hash non corrispondono, l'operazione non riesce con codice di errore 400 (richiesta non valida).
x-ms-content-crc64 facoltativo. Hash CRC64 del contenuto del blocco. Questo hash viene utilizzato per verificare l'integrità del blocco durante il trasporto. Quando questa intestazione viene specificata, il servizio di archiviazione confronta l'hash del contenuto ricevuto con il valore di questa intestazione.

Nota: questo hash CRC64 non viene archiviato con il BLOB.

Se i due hash non corrispondono, l'operazione non riesce con codice di errore 400 (richiesta non valida).

Se sono presenti intestazioni Content-MD5 e x-ms-content-crc64, la richiesta ha esito negativo con 400 (richiesta non valida).

Questa intestazione è supportata nelle versioni 2019-02-02 e successive.
x-ms-encryption-scope facoltativo. Indica l'ambito di crittografia da usare per crittografare il contenuto della richiesta. Questa intestazione è supportata nelle versioni 2019-02-02 e successive.
x-ms-lease-id:<ID> Obbligatoria se il Blob presenta un lease attivo. Per eseguire questa operazione su un Blob con un lease attivo, specificare l'ID lease valido per questa intestazione.
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.

Intestazioni di richiesta (chiavi di crittografia fornite dal cliente)

A partire dalla versione 2019-02-02, è possibile specificare le intestazioni seguenti nella richiesta di crittografare un BLOB con una chiave fornita dal cliente. La crittografia con una chiave fornita dal cliente (e il set corrispondente di intestazioni) è facoltativa.

Intestazione della richiesta Descrizione
x-ms-encryption-key Obbligatorio. Chiave di crittografia AES-256 con codifica Base64.
x-ms-encryption-key-sha256 Obbligatorio. Hash SHA256 con codifica Base64 della chiave di crittografia.
x-ms-encryption-algorithm: AES256 Obbligatorio. Specifica l'algoritmo da utilizzare per la crittografia. Il valore di questa intestazione deve essere AES256.

Testo della richiesta

Il corpo della richiesta contiene il contenuto del blocco.

Richiesta di esempio

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Sun, 25 Sep 2011 14:37:35 GMT  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048576

Risposta

Nella risposta sono inclusi un codice di stato HTTP e un set di intestazioni per la risposta.

Codice stato

Un'operazione completata correttamente restituisce il codice di stato 201 (Creato).

Per informazioni sui codici di stato, vedere Codici di stato e di errore.

Intestazioni di risposta

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

Intestazione risposta Descrizione
Content-MD5 Restituito in modo che il client possa verificare l'integrità del contenuto del messaggio. Il valore di questa intestazione viene calcolato dall'archiviazione BLOB e non è necessariamente lo stesso valore specificato nelle intestazioni della richiesta. Per le versioni 2019-02-02 e successive, questa intestazione viene restituita solo quando la richiesta ha questa intestazione.
x-ms-content-crc64 Per le versioni 2019-02-02 e successive, questa intestazione viene restituita in modo che il client possa verificare l'integrità del contenuto del messaggio. Il valore di questa intestazione viene calcolato dall'archiviazione BLOB e non è necessariamente lo stesso valore specificato nelle intestazioni della richiesta.

Questa intestazione viene restituita quando Content-md5 l'intestazione non è presente nella richiesta.
x-ms-request-id Identifica in modo univoco la richiesta effettuata e puoi usarla per risolvere la risoluzione dei problemi della richiesta. Per altre informazioni, vedere Risolvere i problemi relativi alle operazioni api.
x-ms-version Indica la versione di archiviazione BLOB usata per eseguire la richiesta. Questa intestazione viene restituita per le richieste effettuate rispetto alla versione 2009-09-19 o successiva.
Date Valore di data/ora UTC generato dal servizio, che indica quando è stata avviata la risposta.
x-ms-request-server-encrypted: true/false Versione 2015-12-11 e versioni successive. Il valore di questa intestazione è impostato su true se il contenuto della richiesta viene crittografato correttamente usando l'algoritmo specificato. In caso contrario, il valore è impostato su false.
x-ms-encryption-key-sha256 Versione 2019-02-02 e successiva. Questa intestazione viene restituita se la richiesta ha usato una chiave fornita dal cliente per la crittografia, in modo che il client possa assicurarsi che il contenuto della richiesta venga crittografato correttamente usando la chiave specificata.
x-ms-encryption-scope Versione 2019-02-02 e successiva. Questa intestazione viene restituita se la richiesta ha usato un ambito di crittografia, in modo che il client possa assicurarsi che il contenuto della richiesta venga crittografato correttamente usando l'ambito di crittografia.
x-ms-client-request-id Può essere usato per risolvere i problemi delle richieste e delle relative risposte corrispondenti. Il valore di questa intestazione è uguale al valore dell'intestazione x-ms-client-request-id se presente nella richiesta e il valore non contiene più di 1.024 caratteri ASCII visibili. Se l'intestazione x-ms-client-request-id non è presente nella richiesta, non è presente nella risposta.

Risposta di esempio

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

Autorizzazione

L'autorizzazione è necessaria quando si chiama qualsiasi operazione di accesso ai dati in Archiviazione di Azure. È possibile autorizzare l'operazione Put Block come descritto di seguito.

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, un gruppo o un'entità servizio di Microsoft Entra per chiamare l'operazione Put Block 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.

Commenti

Put Block consente di caricare un blocco per l'inclusione futura di un Blob in blocchi. Ogni blocco in un BLOB a blocchi può essere una dimensione diversa. Un BLOB a blocchi può includere un massimo di 50.000 blocchi di commit.

Nella tabella seguente vengono descritte le dimensioni massime consentite per blocchi e BLOB, in base alla versione del servizio:

Versione del servizio Dimensioni massime del blocco (tramite Put Block) Dimensioni massime del BLOB (tramite Put Block List) Dimensioni massime del BLOB tramite un'operazione di scrittura singola (tramite Put Blob)
Versione 2019-12-12 e successive 4.000 MiB Circa 190.7 tebibyte (TiB) (4.000 MiB × 50.000 blocchi) 5.000 MiB
Versioni 2016-05-31 fino al 2019-07-07 100 MiB Circa 4,75 TiB (100 MiB × 50.000 blocchi) 256 MiB
Versioni precedenti al 2016-05-31 4 MiB Circa 195 gibibyte (GiB) (4 MiB × 50.000 blocchi) 64 MiB

Il numero massimo di blocchi non inviati che possono essere associati a un BLOB è pari a 100.000. Se questo numero viene superato, il servizio restituisce il codice di stato 409 (RequestEntityTooLargeBlockCountExceedsLimit).

Dopo aver caricato un set di blocchi, è possibile creare o aggiornare il BLOB nel server da questo set chiamando l'operazione Put Block List . Ogni blocco nel set viene identificato da un ID di blocco univoco all'interno di tale BLOB. Gli ID di blocco sono con ambito in un BLOB specifico, in modo che i BLOB diversi possano avere blocchi con gli stessi ID.

Se si chiama Put Block un BLOB che non esiste ancora, viene creato un nuovo BLOB a blocchi con una lunghezza di contenuto pari a 0. Questo Blob viene enumerato dall'operazione List Blobs se l'opzione include=uncommittedblobs è specificata. Il blocco o i blocchi caricati non vengono caricati finché non si chiama Put Block List il nuovo BLOB. Un BLOB creato in questo modo viene mantenuto nel server per una settimana. Se non sono stati aggiunti più blocchi o blocchi di cui è stato eseguito il commit nel BLOB entro tale periodo di tempo, il BLOB viene sottoposto a Garbage Collection.

Un blocco caricato correttamente con l'operazione Put Block non diventa parte di un BLOB finché non viene eseguito il commit con Put Block List. Prima di Put Block List essere chiamato per eseguire il commit del BLOB nuovo o aggiornato, tutte le chiamate a Recupera BLOB restituiscono il contenuto del BLOB senza includere il blocco di cui non è stato eseguito il commit.

Se si carica un blocco con lo stesso ID blocco di un altro blocco che non è ancora stato eseguito il commit, verrà eseguito il commit dell'ultimo blocco caricato con tale ID alla successiva operazione completata Put Block List .

Dopo Put Block List la chiamata, viene eseguito il commit di tutti i blocchi di cui non è stato eseguito il commit nell'elenco di blocchi come parte del nuovo BLOB. Tutti i blocchi di cui non è stato eseguito il commit non specificati nell'elenco di blocchi per il BLOB vengono raccolti e rimossi dall'archiviazione BLOB. Qualsiasi blocco di cui non è stato eseguito il commit viene eseguito anche il Garbage Collection se non sono presenti chiamate riuscite a Put Block o Put Block List nello stesso BLOB entro una settimana dopo l'ultima operazione riuscita Put Block . Se il BLOB Put viene chiamato nel BLOB, tutti i blocchi di cui non è stato eseguito il commit vengono raccolti tramite Garbage Collection.

Se il BLOB ha un lease attivo, il client deve specificare un ID lease valido nella richiesta per scrivere un blocco nel BLOB. Se il client non specifica un ID lease o specifica un ID lease non valido, Archiviazione BLOB restituisce il codice di stato 412 (Precondizione non riuscita). Se il client specifica un ID lease ma il BLOB non ha un lease attivo, Archiviazione BLOB restituisce anche il codice di stato 412 (precondizione non riuscita).

Per un BLOB specificato, tutti gli ID di blocco devono avere la stessa lunghezza. Se un blocco viene caricato con un ID di lunghezza diversa rispetto agli ID di eventuali blocchi di cui non è stato eseguito il commit, il servizio restituisce il codice di errore 400 (Richiesta non valida).

Se si tenta di caricare un blocco maggiore di 4.000 MiB per la versione 2019-12-12 o successiva, maggiore di 100 MiB per la versione 2016-05-31 o successiva o superiore a 4 MiB per le versioni precedenti, il servizio restituisce il codice di stato 413 (Entità richiesta troppo grande). Il servizio restituisce anche informazioni aggiuntive sull'errore nella risposta, incluse le dimensioni massime consentite del blocco, in byte.

La chiamata Put Block non aggiorna l'ora dell'ultima modifica di un BLOB esistente.

La chiamata a Put Block in un Blob di pagine restituisce un errore.

La chiamata Put Block a un BLOB archiviato restituisce un errore e la chiamata a un hot BLOB o cool non modifica il livello BLOB.

Fatturazione

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 Put Block le richieste in base al tipo di account di archiviazione:

Operazione Tipo di account di archiviazione Categoria di fatturazione
Put Block BLOB in blocchi Premium
Utilizzo generico v2 Standard
Standard per utilizzo generico v1		 Operazioni di scrittura

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

Vedi anche

Autorizzare le richieste ad Archiviazione di Azure
Stato e codici errore
Codici di errore del servizio BLOB
Impostare i timeout per le operazioni del servizio BLOB