Aggiungi blocco da URL

  • Articolo

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 impostato su AppendBlob. Append Block From URL è supportato solo nella versione 2018-11-09 o successiva.

Richiesta

È possibile costruire la Append Block From URL richiesta come indicato di seguito. È consigliato il protocollo 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=appendblock HTTP/1.1

Quando si effettua una richiesta per il servizio di archiviazione emulato, specificare il nome host dell'emulatore e Archiviazione BLOB di Azure porta 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=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 Facoltativa. Il parametro timeout viene espresso in secondi. Per altre informazioni, vedere Impostazione dei timeout per le operazioni di archiviazione BLOB.

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 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. Specifica il numero di byte trasmessi nel corpo della richiesta. Il valore di questa intestazione deve essere impostato su zero. Quando la lunghezza non è zero, l'operazione avrà esito negativo con 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 con URL, come appare 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 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 ID è supportato solo il bearer di schema.
Questa intestazione è supportata nella versione 2020-10-02 e successive.
x-ms-source-range facoltativo. Carica solo i byte del BLOB nell'URL di origine nell'intervallo specificato. Se non viene specificato, l'intero contenuto del BLOB di origine viene caricato come blocco di accodamento singolo. Per altre informazioni, vedere Specifica dell'intestazione dell'intervallo per le operazioni di archiviazione BLOB .
x-ms-source-content-md5 facoltativo. 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 che è arrivato dall'origine di 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 non riesce con codice di errore 400 (richiesta non valida).
x-ms-source-content-crc64 facoltativo. 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 che è arrivato dall'origine di 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 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 nella versione 2019-02-02 o successiva.
x-ms-encryption-scope facoltativo. Indica l'ambito di crittografia da usare per crittografare il contenuto di origine. Questa intestazione è supportata nella versione 2019-02-02 o successiva.
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.
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 valore 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 di byte da confrontare. Append Block from URL ha esito positivo solo se la posizione di accodamento è uguale a questo numero. In caso contrario, la richiesta ha esito negativo con un valore 412 (precondizione non riuscita).

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 delle intestazioni condizionali per le operazioni di archiviazione BLOB.

Intestazioni di richiesta (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 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 usare 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=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

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; Nella risposta possono anche essere incluse intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.

Intestazione risposta Descrizione
Etag Contiene ETag un valore nelle virgolette. Il client usa il valore per eseguire operazioni condizionali PUT usando l'intestazione della If-Match richiesta.
Last-Modified Data e ora dell'ultima modifica del Blob. Il formato data è conforme a RFC 1123. Per altre informazioni, vedere Rappresentazione dei valori data-ora nelle intestazioni.

Qualsiasi operazione di scrittura nel BLOB (inclusi gli aggiornamenti dei metadati o delle 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 dell'archiviazione BLOB usata per eseguire la richiesta. Questa intestazione viene restituita per le richieste effettuate nella versione 2009-09-19 e successive.
Date Valore data/ora UTC generato dal servizio che indica l'ora in cui è stata avviata la risposta.
x-ms-blob-append-offset Questa intestazione di risposta viene restituita solo per le operazioni di accodamento. Restituisce l'offset in corrispondenza del quale il blocco è stato eseguito il commit, in byte.
x-ms-blob-committed-block-count Numero di blocchi di commit presenti nel BLOB. È possibile usare questa operazione per controllare il numero di accodamenti che possono essere eseguiti.
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 usato una chiave fornita dal cliente per la crittografia. Il client può quindi assicurarsi che il contenuto della richiesta venga crittografato correttamente usando la chiave specificata.
x-ms-encryption-scope Versione 2019-02-02 o successiva. Questa intestazione viene restituita se la richiesta ha usato un ambito di crittografia. Il client può quindi assicurarsi che il contenuto della richiesta venga crittografato correttamente usando 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 qualsiasi operazione di accesso ai dati in Archiviazione di Azure. È possibile autorizzare l'operazione Append Block From URL come descritto di seguito.

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

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 Append Block From URL 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

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 ha esito positivo nel server. È consentito un massimo di 50.000 accodamenti per ogni BLOB di accodamento, dove. Ogni blocco può essere di dimensioni diverse.

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 Append Block From URL) Dimensioni massime dei BLOB
Versione 2022-11-02 e successive 100 MiB (anteprima) Circa 4,75 TiB (100 MiB × 50.000 blocchi)
Versioni precedenti alla versione 2022-11-02 4 MiB Circa 195 gibibyte (GiB) (4 MiB × 50.000 blocchi)

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

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

I BLOB caricati tramite Append Block From URL non espongono ID blocchi, quindi non è possibile chiamare Get Block List su un BLOB di accodamento. In questo modo si verifica un errore.

È possibile specificare le intestazioni condizionali facoltative seguenti nella richiesta:

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

    I client che usano un singolo writer possono usare questa intestazione per determinare se un'operazione Append Block From URL ha avuto esito positivo, nonostante un errore di rete.

  • x-ms-blob-condition-maxsize: i client possono usare questa intestazione per garantire che le operazioni di accodamento non aumentino le dimensioni del BLOB oltre le dimensioni massime previste in byte. Se la condizione non riesce, la richiesta ha esito negativo con codice di errore 412 (precondizione non riuscita).

Se si tenta di caricare un blocco maggiore delle dimensioni consentite, il servizio restituisce il codice di errore HTTP 413 (Entità richiesta troppo grande). Nella risposta vengono restituite informazioni aggiuntive sull'errore, incluse le dimensioni massime 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 presenta un lease attivo, il client deve specificare un ID lease valido nella richiesta per poter scrivere un blocco sul Blob. Se il client non specifica un ID lease o specifica un ID lease non valido, 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 su 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 su un BLOB inesistente, il servizio restituisce il codice di errore 404 (Non trovato).

Evitare appendhe duplicate o ritardate

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

In uno scenario con più writer, ogni client può usare intestazioni condizionali. Questo potrebbe non essere ottimale per le prestazioni. Per la velocità effettiva di accodamento simultanea più elevata, le applicazioni devono gestire le appendhe ridondanti e le aggiunte ritardate nel livello dell'applicazione. Ad esempio, le applicazioni possono aggiungere periodi o numeri di sequenza nei dati aggiunti.

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

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

Operazione Tipo di account di archiviazione Categoria di fatturazione
Append Block From URL (account di destinazione1) BLOB in blocchi Premium
Utilizzo generico v2 Standard
Standard per utilizzo generico v1		 Operazioni di scrittura
Aggiungi blocco da 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'origine.