Inserisci blocco da URL

  • Articolo

L'operazione Put Block From URL crea un nuovo blocco di cui eseguire il commit come parte di un BLOB in cui il contenuto viene letto da un URL. Questa API è disponibile a partire dalla versione 2018-03-28.

Richiesta

È possibile costruire la Put Block From URL 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 di essere codificata, le dimensioni della stringa devono essere minori o uguali a 64 byte.

Per un BLOB specificato, la lunghezza del valore specificato 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. Per Put Block From URL, la versione deve essere 2018-03-28 o successiva.
Content-Length Obbligatorio. Specifica il numero di byte trasmessi nel corpo della richiesta. Il valore di questa intestazione deve essere impostato su 0. Quando la lunghezza non è 0, l'operazione ha esito negativo con codice di stato 400 (richiesta non valida).
x-ms-copy-source:name Obbligatorio. Specifica l'URL del BLOB di origine. Il valore può essere un URL di lunghezza massima di 2 kibibyte (KiB) che specifica un BLOB. Il valore deve essere codificato con URL, come appare in un URI di richiesta. Il BLOB di origine deve essere pubblico o autorizzato tramite una firma di accesso condiviso. Se il BLOB di origine è pubblico, non è necessaria alcuna autorizzazione per eseguire l'operazione. Ecco alcuni esempi di URL oggetto di origine:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> facoltativo. Specifica lo schema di autorizzazione e la firma per l'origine di copia. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
Per Azure Active Directory è supportato solo uno schema di connessione.
Questa intestazione è supportata nelle versioni 2020-10-02 e successive.
x-ms-source-range facoltativo. Carica solo i byte del BLOB nell'URL di origine nell'intervallo specificato. Se questa intestazione non viene specificata, l'intero contenuto del BLOB di origine viene caricato come blocco singolo. Per altre informazioni, vedere Specificare l'intestazione dell'intervallo per le operazioni del servizio BLOB.
x-ms-source-content-md5 facoltativo. Hash MD5 del contenuto del blocco dall'URI. Questo hash viene usato per verificare l'integrità del blocco durante il trasporto dei dati dall'URI. Quando questa intestazione viene specificata, il servizio di archiviazione confronta l'hash del contenuto che è arrivato dall'origine di copia con questo valore di 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-source-content-crc64 facoltativo. Hash CRC64 del contenuto del blocco dall'URI. Questo hash viene usato per verificare l'integrità del blocco durante il trasporto dei dati dall'URI. Quando questa intestazione viene specificata, il servizio di archiviazione confronta l'hash del contenuto che è arrivato dall'origine di copia con questo valore di 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 x-ms-source-content-md5 e x-ms-source-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 di origine. 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

Nessuno.

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: 2018-03-28  
x-ms-date: Sat, 31 Mar 2018 14:37:35 GMT    
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-499

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 altre 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. Non è necessariamente uguale al 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. Restituito in modo che il client possa verificare l'integrità del contenuto del messaggio. Il valore di questa intestazione viene calcolato dall'archiviazione BLOB. Non è necessariamente uguale al valore specificato nelle intestazioni della richiesta.

Restituito quando x-ms-source-content-md5 l'intestazione non è presente nella richiesta.
x-ms-request-id Identifica in modo univoco la richiesta effettuata ed è possibile usarla per risolvere i problemi della richiesta. Per altre informazioni, vedere Risolvere i problemi relativi alle operazioni api.
x-ms-version Versione di Archiviazione BLOB usata per eseguire la richiesta.
Date Valore di data/ora UTC generato dal servizio, che indica l'ora di avvio della risposta.
x-ms-request-server-encrypted: true/false Versione 2015-12-11 e successive. Il valore di questa intestazione è impostato su true se il contenuto del blocco 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 successive. Restituito 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 fornita.
x-ms-encryption-scope Versione 2019-02-02 e successive. Restituito se la richiesta ha usato un ambito di crittografia, in modo che il client possa garantire 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 relativi alle richieste e alle 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 sarà presente nella risposta.

Risposta di esempio

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

Autorizzazione

L'autorizzazione è necessaria quando si chiama un'operazione di accesso ai dati in Archiviazione di Azure. È possibile autorizzare l'operazione Put Block From URL 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 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 chiamare l'operazione Put Block From URL 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.

Commenti

Put Block From URL consente di caricare un blocco per l'inclusione futura di un Blob in blocchi. Un BLOB in blocchi può includere un massimo di 50.000 blocchi. Ogni blocco può essere di dimensioni diverse. La dimensione massima per un blocco caricato con Put Block From URL è di 100 mebibyte (MiB). Per caricare blocchi di dimensioni maggiori (fino a 4.000 MiB), vedere Put Block.

Nella versione 2020-10-02 e successive, l'autorizzazione di Azure Active Directory è supportata per l'origine dell'operazione di copia.

Un BLOB può avere un massimo di 100.000 blocchi di cui non è stato eseguito il commit in qualsiasi momento. Se questo valore massimo viene superato, il servizio restituisce il codice di stato 409 (RequestEntityTooLargeBlockCountExceedsLimit).

La tabella seguente descrive le dimensioni massime consentite per blocchi e BLOB, in base alla versione del servizio:

Versione del servizio Dimensioni massime del blocco (tramite Put Block From URL) Dimensioni massime del BLOB (tramite Put Block List) Dimensioni massime del BLOB tramite un'operazione di scrittura singola (tramite Put Blob From URL)
Versione 2020-04-08 e successive 4.000 MiB Circa 190,7 tebibyte (TiB) (4.000 MiB × 50.000 blocchi) 5.000 MiB
Versioni precedenti alla versione 2020-04-08 100 MiB Circa 4,75 TiB (100 MiB × 50.000 blocchi) 256 MiB

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 è identificato da un ID blocco univoco all'interno di tale BLOB. L'ambito degli ID blocco viene definito in un Blob, pertanto Blob diversi possono contenere blocchi con gli stessi ID.

Se si chiama Put Block From URL su un BLOB che non esiste ancora, viene creato un nuovo BLOB in 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 sottoposti a commit finché non si chiama Put Block List sul 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 From URL 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, viene eseguito il commit dell'ultimo blocco caricato con tale ID alla successiva operazione riuscita Put Block List .

Dopo la chiamata a Put Block List, tutti i blocchi di cui non è stato eseguito il commit specificati nell'elenco di blocchi verranno sottoposti a commit 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 From URL o Put Block List nello stesso BLOB entro una settimana dopo l'ultima operazione riuscita Put Block From URL . 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 blocco di lunghezza diversa da quello degli ID blocco per eventuali blocchi di cui non è stato eseguito il commit esistente, il servizio restituisce il codice di risposta di errore 400 (richiesta non valida).

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

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

La chiamata Put Block From URL a un BLOB di archivio 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 From URL le richieste in base al tipo di account di archiviazione:

Operazione Tipo di account di archiviazione Categoria di fatturazione
Put Block From URL (account di destinazione1) BLOB in blocchi Premium
Utilizzo generico v2 Standard
Standard per utilizzo generico v1		 Operazioni di scrittura
Put Block From URL (account di origine2) BLOB in blocchi Premium
Utilizzo generico v2 Standard
Standard per utilizzo generico v1		 Operazioni di lettura

1L'account di destinazione viene addebitato per una transazione per avviare la scrittura.
2L'account di origine comporta una transazione per ogni richiesta di lettura all'oggetto di origine.

Inoltre, se gli account di origine e di destinazione si trovano in aree diverse (ad esempio, Stati Uniti settentrionali e Stati Uniti meridionali), la larghezza di banda usata per trasferire la richiesta viene addebitata all'account di archiviazione di origine come uscita. L'uscita tra account della stessa area geografica è gratuita.

Per informazioni sui prezzi per le categorie di fatturazione specificate, vedere prezzi di Archiviazione BLOB di Azure.

Vedi anche