Inserisci blocco da URL

Articolo
05/15/2024

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 Microsoft Entra è 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.

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

Autorizzazioni

Di seguito è riportata l'azione di controllo degli accessi in base al ruolo necessaria per un Microsoft Entra utente, un gruppo, un gruppo, un'identità gestita o un'entità servizio 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:

Azione controllo degli accessi in base al ruolo di Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Ruolo predefinito con privilegi minimi:Collaboratore ai dati dei BLOB di archiviazione

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.

Una firma di accesso condiviso fornisce accesso delegato sicuro alle risorse in un account di archiviazione. Con una firma di accesso condiviso è possibile controllare in modo granulare il modo in cui un client può accedere ai dati. È possibile specificare la risorsa a cui il client può accedere, le autorizzazioni necessarie per tali risorse e il periodo di validità della firma di accesso condiviso.

L'operazione Put Block From URL supporta tre tipi di firme di accesso condiviso: firma di accesso condiviso delega utente, firma di accesso condiviso del servizio e firma di accesso condiviso dell'account.

Come procedura consigliata per la sicurezza, è consigliabile usare le credenziali Microsoft Entra anziché la chiave dell'account di archiviazione, che può essere compromessa più facilmente. Se la progettazione dell'applicazione richiede firme di accesso condiviso, usare Microsoft Entra credenziali per creare una firma di accesso condiviso della delega utente, quando possibile.

Quando l'accesso con chiave condivisa non è consentito per l'account di archiviazione, non sarà consentito un token di firma di accesso condiviso del servizio o un token di firma di accesso condiviso dell'account in una richiesta di archiviazione BLOB. Per altre informazioni, vedere Informazioni su come impedire la chiave condivisa influisce sui token di firma di accesso condiviso.

Firma di accesso condiviso di delega utente

Una firma di accesso condiviso della delega utente è protetta con credenziali Microsoft Entra e anche dalle autorizzazioni specificate per la firma di accesso condiviso.

Per chiamare l'operazione Put Block From URL usando un token di firma di accesso condiviso delegato a un contenitore o a una risorsa BLOB, è necessaria l'autorizzazione Scrittura (w) come parte del token di firma di accesso condiviso della delega utente.

Per altre informazioni sulla firma di accesso condiviso della delega utente, vedere Create una firma di accesso condiviso della delega utente.

Firma di accesso condiviso del servizio

Una firma di accesso condiviso del servizio è protetta con la chiave dell'account di archiviazione. Una firma di accesso condiviso del servizio delega l'accesso a una risorsa in un singolo servizio di archiviazione di Azure, ad esempio l'archiviazione BLOB.

Per altre informazioni sulla firma di accesso condiviso del servizio, vedere Create una firma di accesso condiviso del servizio.

Firma di accesso condiviso dell'account

Una firma di accesso condiviso dell'account è protetta con la chiave dell'account di archiviazione. Una firma di accesso condiviso dell'account delega l'accesso alle risorse in uno o più servizi di archiviazione. Tutte le operazioni disponibili tramite una firma di accesso condiviso del servizio o di delega utente sono disponibili anche tramite una firma di accesso condiviso dell'account.

La tabella seguente indica il tipo di risorsa firmata e le autorizzazioni firmate per specificare quando si delega l'accesso:

Operazione	Servizio firmato	Tipo di risorsa firmato	Autorizzazione firmata
Inserisci blocco da URL	BLOB (b)	Oggetto (o)	Scrittura (w)

Per altre informazioni sulla firma di accesso condiviso dell'account, vedere Create una firma di accesso condiviso dell'account.

L'operazione Put Block From URL supporta l'autorizzazione con chiave condivisa. L'autorizzazione con le chiavi dell'account non è consigliata per la maggior parte degli scenari, perché è meno sicura.

Microsoft consiglia di non consentire l'autorizzazione di chiave condivisa per l'account di archiviazione quando possibile. Per altre informazioni, vedere Impedire l'autorizzazione con chiave condivisa.

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 Microsoft Entra'autorizzazione è 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 massimo viene superato, il servizio restituisce il codice di stato 409 (RequestEntityTooLargeBlockCountExceedsLimit).

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 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 versioni successive	4.000 MiB	Circa 190.7 tebibyte (TiB) (4.000 MiB × 50.000 blocchi)	5.000 MiB
Versioni precedenti al 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 viene identificato da un ID di 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 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 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 commit al BLOB entro quel periodo di tempo, il BLOB viene 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 Put Block List di essere chiamato per eseguire il commit del BLOB nuovo o aggiornato, tutte le chiamate a Recupera BLOB restituiscono il contenuto del BLOB senza l'inclusione del blocco non commesso.

Se si carica un blocco con lo stesso ID blocco di un altro blocco che non è ancora stato eseguito il commit, l'ultimo blocco caricato con tale ID viene eseguito il commit nell'operazione successiva 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 non inviati non specificati nell'elenco di blocchi per il BLOB sono garbage collection e rimossi dall'archiviazione BLOB. Tutti i blocchi non inviati vengono anche 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 non generati vengono 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, l'archiviazione BLOB restituisce il codice di stato 412 (Precondizione non riuscita). Se il client specifica un ID lease, ma il BLOB non dispone di un lease attivo, l'archiviazione BLOB restituisce anche il codice di stato 412 (Precondizione non riuscita).

Per un BLOB specificato, tutti gli ID di blocco devono essere la stessa lunghezza. Se un blocco viene caricato con un ID di blocco diverso da quello degli ID di blocco per eventuali blocchi non inviati esistenti, il servizio restituisce il codice di risposta di errore 400 (richiesta non valida).

La chiamata Put Block From URL non aggiorna l'ultima volta modificata 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 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 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 destinazione¹)	BLOB di blocchi Premium Utilizzo generico v2 Standard Utilizzo generico standard v1	Operazioni di scrittura
Put Block From URL (account di origine²)	BLOB di blocchi Premium Utilizzo generico v2 Standard Utilizzo generico standard v1	Operazioni di lettura

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

Inoltre, se gli account di origine e di destinazione risiedono 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 Archiviazione BLOB di Azure.

Condividi tramite