Aggiungi blocco dall'URL

Articolo
2024-02-13

L'operazione Append Block From URL esegue il commit di un nuovo blocco di dati alla fine di un BLOB di accodamento esistente.

L'operazione Append Block From URL è consentita solo se il BLOB è stato creato con x-ms-blob-type l'impostazione su AppendBlob. Append Block From URL è supportato solo nella versione 2018-11-09 o successiva.

Richiesta

È possibile costruire la richiesta di Append Block From URL come indicato di seguito. Si consiglia HTTPS. Sostituire myaccount con il nome dell'account di archiviazione.

URI di richiesta del metodo PUT	Versione HTTP
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock`	HTTP/1.1

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

URI di richiesta del metodo PUT	Versione HTTP
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=appendblock`	HTTP/1.1

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

Parametri URI

Parametro	Descrizione
`timeout`	Opzionale. Il parametro di timeout è espresso in secondi. Per altre informazioni, vedere Impostazione dei timeout per le operazioni di archiviazione BLOB.

Header di richiesta

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

Header di 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 l'ora UTC (Coordinated Universal Time) per la richiesta. 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 utilizzare per questa richiesta. Per ulteriori informazioni, consultare Controllo delle versioni per i servizi di Archiviazione di Azure.
`Content-Length`	Obbligatorio. Specifica il numero di byte trasmessi nel corpo della richiesta. Il valore di questa intestazione deve essere impostato su zero. Quando la lunghezza è diversa da zero, l'operazione avrà esito negativo con il codice di errore 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 KiB che specifica un BLOB. Il valore deve essere codificato in URL, come apparirebbe in un URI di richiesta. Il BLOB di origine deve essere pubblico o deve essere 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 di oggetti 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>`	Opzionale. Specifica lo schema di autorizzazione e la firma per l'origine della copia. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure. Per l'ID Microsoft Entra è supportato solo il portatore dello schema. Questa intestazione è supportata nella versione 2020-10-02 e successive.
`x-ms-source-range`	Opzionale. Carica solo i byte del BLOB nell'URL di origine nell'intervallo specificato. Se questa opzione non viene specificata, l'intero contenuto del BLOB di origine viene caricato come un singolo blocco di accodamento. Per altre informazioni, vedere Specifica dell'intestazione dell'intervallo per le operazioni di archiviazione BLOB .
`x-ms-source-content-md5`	Opzionale. Hash MD5 del contenuto del blocco di accodamento dall'URI. Questo hash viene usato per verificare l'integrità del blocco di accodamento durante il trasporto dei dati dall'URI. Quando si specifica questa intestazione, il servizio di archiviazione confronta l'hash del contenuto arrivato dall'origine copia con questo valore di intestazione. Si noti che questo hash MD5 non viene archiviato con il BLOB. Se i due hash non corrispondono, l'operazione ha esito negativo con il codice di errore 400 (richiesta non valida).
`x-ms-source-content-crc64`	Opzionale. Hash CRC64 del contenuto del blocco di accodamento dall'URI. Questo hash viene usato per verificare l'integrità del blocco di accodamento durante il trasporto dei dati dall'URI. Quando si specifica questa intestazione, il servizio di archiviazione confronta l'hash del contenuto arrivato dall'origine copia con questo valore di intestazione. Si noti che questo hash CRC64 non viene archiviato con il BLOB. Se i due hash non corrispondono, l'operazione ha esito negativo con il codice di errore 400 (richiesta non valida). Se sono presenti entrambe `x-ms-source-content-md5` le intestazioni e `x-ms-source-content-crc64` , la richiesta ha esito negativo con un 400 (Richiesta non valida). Questa intestazione è supportata nella versione 2019-02-02 o successiva.
`x-ms-encryption-scope`	Opzionale. Indica l'ambito di crittografia da utilizzare per crittografare il contenuto di origine. Questa intestazione è supportata nella versione 2019-02-02 o successiva.
`x-ms-lease-id:<ID>`	Obbligatorio se il blob ha un contratto d'affitto 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`	Opzionale. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log quando viene configurata la registrazione. È consigliabile usare questa intestazione per correlare le attività sul lato client alle richieste ricevute dal server. Per altre informazioni, vedere Monitorare l'archiviazione BLOB di Azure.
`x-ms-blob-condition-maxsize`	Intestazione condizionale facoltativa. Lunghezza massima in byte consentita per il BLOB di accodamento. Se l'operazione `Append Block From URL` causa il superamento di tale limite da parte del BLOB o se le dimensioni del BLOB sono già maggiori del valore specificato in questa intestazione, la richiesta ha esito negativo con un errore 412 (Precondizione non riuscita).
`x-ms-blob-condition-appendpos`	Intestazione condizionale facoltativa, usata solo per l'operazione `Append Block from URL` . Numero che indica l'offset dei byte da confrontare. `Append Block from URL` ha esito positivo solo se la posizione di aggiunta è uguale a questo numero. In caso contrario, la richiesta ha esito negativo con un errore 412 (Precondizione non riuscita).
`x-ms-file-request-intent`	Obbligatorio se `x-ms-copy-source` l'intestazione è un URL di file di Azure e `x-ms-copy-source-authorization` l'intestazione specifica un token OAuth. Il valore accettabile è `backup`. Questa intestazione specifica che il `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` o `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` deve essere concesso se sono inclusi nei criteri di controllo degli accessi in base al ruolo assegnati all'identità autorizzata usando l'intestazione `x-ms-copy-source-authorization`. Disponibile per la versione 2025-07-05 e successive.

Questa operazione supporta l'uso di intestazioni condizionali aggiuntive, per garantire che l'API abbia esito positivo solo se viene soddisfatta una condizione specificata. Per altre informazioni, vedere Specifica di intestazioni condizionali per le operazioni di archiviazione BLOB.

Intestazioni delle richieste (chiavi di crittografia fornite dal cliente)

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

Header di 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.

Esempio di richiesta

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock  HTTP/1.1  

Request Headers:  
x-ms-version: 2018-11-09  
x-ms-date: <date>  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0 
If-Match: "0x8CB172A360EC34B"

Risposta

La risposta include un codice di stato HTTP e un set di intestazioni di risposta.

Codice di stato

Un'operazione riuscita restituisce il codice di stato 201 (Creato). Per informazioni sui codici di stato, vedere Stato e codici di errore.

Intestazioni di risposta

La risposta per questa operazione include le intestazioni seguenti. La risposta può includere anche intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1 .

Intestazione della risposta	Descrizione
`Etag`	Contiene `ETag` un valore tra virgolette. Il client utilizza il valore per eseguire operazioni condizionali `PUT` utilizzando l'intestazione della `If-Match` richiesta.
`Last-Modified`	Data/ora dell'ultima modifica del BLOB. Il formato della data segue RFC 1123. Per altre informazioni, vedere Rappresentazione dei valori di data e ora nelle intestazioni. Qualsiasi operazione di scrittura sul BLOB (inclusi gli aggiornamenti sui metadati o sulle proprietà del BLOB) modifica l'ora dell'ultima modifica del BLOB.
`Content-MD5`	Questa intestazione viene restituita in modo che il client possa verificare l'integrità del contenuto del messaggio. Archiviazione BLOB calcola il valore di questa intestazione. Non è necessariamente lo stesso valore specificato nelle intestazioni della richiesta. Per la versione 2019-02-02 o successiva, questa intestazione viene restituita solo quando la richiesta ha questa intestazione.
`x-ms-content-crc64`	Per la versione 2019-02-02 o successiva. Questa intestazione viene restituita in modo che il client possa verificare l'integrità del contenuto del messaggio. Archiviazione BLOB calcola il valore di questa intestazione. Non è necessariamente lo stesso valore specificato nelle intestazioni della richiesta. Questa intestazione viene restituita quando l'intestazione `x-ms-source-content-md5` non è presente nella richiesta.
`x-ms-request-id`	Questa intestazione identifica in modo univoco la richiesta effettuata e può essere usata per la risoluzione dei problemi della richiesta.
`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 e successive.
`Date`	Valore di data/ora UTC generato dal servizio che indica l'ora di avvio della risposta.
`x-ms-blob-append-offset`	Questa intestazione di risposta viene restituita solo per le operazioni di accodamento. Restituisce l'offset in base al quale è stato eseguito il commit del blocco, in byte.
`x-ms-blob-committed-block-count`	Numero di blocchi di cui è stato eseguito il commit presenti nel BLOB. È possibile utilizzare questa opzione per controllare il numero di aggiunte aggiuntive che possono essere eseguite.
`x-ms-request-server-encrypted: true/false`	Versione 2015-12-11 o successiva. 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 o successiva. Questa intestazione viene restituita se la richiesta ha utilizzato una chiave fornita dal cliente per la crittografia. Il client può quindi assicurarsi che il contenuto della richiesta venga crittografato correttamente utilizzando la chiave fornita.
`x-ms-encryption-scope`	Versione 2019-02-02 o successiva. Questa intestazione viene restituita se la richiesta ha utilizzato un ambito di crittografia. Il client può quindi assicurarsi che il contenuto della richiesta venga crittografato correttamente utilizzando l'ambito di crittografia.

Risposta di esempio

Response Status:  
HTTP/1.1 201 Created  

Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-blob-append-offset: 2097152  
x-ms-blob-committed–block-count: 1000

Autorizzazione

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

I dettagli dell'autorizzazione in questa sezione si applicano alla destinazione della copia. Per ulteriori informazioni sull'autorizzazione dell'origine di copia, consulta i dettagli per l'intestazione x-ms-copy-sourcedella richiesta.

Importante

Microsoft consiglia di usare l'ID Microsoft Entra 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.

Microsoft Entra ID (scelta consigliata)
firme di accesso condiviso
chiave condivisa

Archiviazione di Azure supporta l'uso di Microsoft Entra ID per autorizzare le richieste di accesso 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 al fine di 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 con 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, un'identità gestita o un'entità servizio di Microsoft Entra per chiamare l'operazione di Append 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/add/action o 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 quale risorsa può accedere al client, quali autorizzazioni hanno per tali risorse e per quanto tempo la firma di accesso condiviso è valida.

L'operazione di supporta tre tipi di firme di accesso condiviso: delega utente sas, firma di accesso condiviso del servizio e account sas.

Come procedura consigliata per la sicurezza, è consigliabile usare le credenziali di 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 le credenziali di Microsoft Entra per creare una firma di accesso condiviso di delega utente, quando possibile.

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

Firma di accesso condiviso di delega utente

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

La chiamata all'operazione Append Block From URL usando un token di firma di accesso condiviso delegato a un contenitore o a una risorsa BLOB richiede l'autorizzazione Aggiungi (a) o Scrittura (w) come parte del token di firma di accesso condiviso di delega utente:

Per altre informazioni sulla firma di accesso condiviso della delega utente, vedere Creare una firma di accesso condiviso di 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.

La chiamata all'operazione Append Block From URL usando un token di firma di accesso condiviso delegato a un contenitore o a una risorsa BLOB richiede l'autorizzazione Add (a) o Write (w) come parte del token di firma di accesso condiviso del servizio.

Per altre informazioni sulla firma di accesso condiviso del servizio, vedere Creare 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
Aggiungi blocco dall'URL	BLOB (b)	Oggetto (o)	Aggiungere (a) o scrivere (w)

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

L'operazione di Append Block From URL supporta 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 della chiave condivisa per l'account di archiviazione, quando possibile. Per altre informazioni, vedere Impedire l'autorizzazione con chiave condivisa.

Osservazioni:

Append Block From URL Carica un blocco alla fine di un BLOB di accodamento esistente. Il blocco di dati è immediatamente disponibile dopo che la chiamata è riuscita sul server. Per ogni BLOB di accodamento è consentito un massimo di 50.000 accodamenti. Ogni blocco può essere di dimensioni diverse.

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

Versione del servizio	Dimensione massima del blocco (tramite `Append Block From URL`)	Dimensioni massime del BLOB
Versione 2022-11-02 e successive	100 MiB (anteprima)	Circa 4,75 TiB (100 MiB × 50.000 blocchi)
Versioni precedenti al 2022-11-02	4 MiB	Circa 195 gibibyte (GiB) (4 MiB × 50.000 blocchi)

Nella versione 2020-10-02 e successive, l'autorizzazione dell'ID Microsoft Entra è supportata per l'origine dell'operazione di copia.

Append Block From URL ha esito positivo solo se il BLOB esiste già.

I BLOB caricati usando Append Block From URL non espongono gli ID blocco, quindi non è possibile chiamare Get Block List su un BLOB di accodamento. In caso contrario, si verifica un errore.

È possibile specificare le intestazioni condizionali facoltative seguenti per la richiesta:

x-ms-blob-condition-appendpos: è possibile impostare questa intestazione su un offset di byte al quale il client prevede di aggiungere il blocco. La richiesta ha esito positivo solo se l'offset corrente corrisponde a quello specificato dal client. In caso contrario, la richiesta ha esito negativo con il codice di errore 412 (Precondizione non riuscita).

I client che utilizzano un singolo writer possono utilizzare questa intestazione per determinare se un'operazione ha avuto esito positivo, nonostante l'errore Append Block From URL di rete.
x-ms-blob-condition-maxsize: i client possono usare questa intestazione per assicurarsi che le operazioni di accodamento non aumentino le dimensioni del BLOB oltre una dimensione massima prevista in byte. Se la condizione ha esito negativo, la richiesta ha esito negativo con il codice di errore 412 (Precondizione non riuscita).

Se si tenta di caricare un blocco di dimensioni superiori a quelle consentite, il servizio restituisce il codice di errore HTTP 413 (Request Entity Too Large). Il servizio restituisce inoltre informazioni aggiuntive sull'errore nella risposta, inclusa la dimensione massima consentita del blocco in byte. Se si tenta di caricare più di 50.000 blocchi, il servizio restituisce il codice di errore 409 (Conflitto).

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 errore 412 (precondizione non riuscita). Se il client specifica un ID lease ma il BLOB non ha un lease attivo, il servizio restituisce il codice di errore 412.

Se si chiama Append Block From URL un BLOB in blocchi o un BLOB di pagine esistente, il servizio restituisce il codice di errore 409 (Conflitto). Se si chiama Append Block From URL un BLOB inesistente, il servizio restituisce il codice di errore 404 (Non trovato).

Evitare accodaggi duplicati o ritardati

In uno scenario con un singolo writer, il client può evitare accodaggi duplicati o scritture ritardate utilizzando l'intestazione x-ms-blob-condition-appendpos condizionale per controllare l'offset corrente. Il client può anche evitare duplicati o ritardi controllando il ETag condizionale, utilizzando If-Match.

In uno scenario con più writer, ogni client può utilizzare intestazioni condizionali. Questo potrebbe non essere ottimale per le prestazioni. Per ottenere la massima velocità effettiva di accodamento simultaneo, le applicazioni devono gestire gli accodaggi ridondanti e ritardati nel livello dell'applicazione. Ad esempio, le applicazioni possono aggiungere epoche o numeri di sequenza nei dati da aggiungere.

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

Fatturazione

Le richieste di prezzi possono provenire 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 sulla modalità di addebito dell'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 Append Block From URL richieste in base al tipo di account di archiviazione:

Operazione	Tipo di account di archiviazione	Categoria di fatturazione
Aggiungi blocco dall'URL (account di destinazione¹)	BLOB in blocchi Premium Utilizzo generico v2 Standard Utilizzo generico v1 Standard	Operazioni di scrittura
Aggiungi blocco dall'URL (account di origine²)	BLOB in blocchi Premium Utilizzo generico v2 Standard Utilizzo generico v1 Standard	Operazioni di lettura

¹Al conto di destinazione viene addebitata una transazione per avviare la scrittura.
^{numero arabo}L'account di origine esegue una transazione per ogni richiesta di lettura all'origine.

Condividi tramite