Condividi tramite

Blocco di accodamento

L'operazione Append Block compromette un nuovo blocco di dati alla fine di un blob di appendenza esistente.

L'operazione Append Block è consentita solo se il blob è stato creato con x-ms-blob-type impostato su AppendBlob. Append Block è supportata solo nella versione 2015-02-21 o successiva.

Richiesta

È possibile costruire la richiesta di Append Block come indicato di seguito. È consigliabile usare 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 fai una richiesta sul servizio di storage emulato, specifica il nome host dell'emulatore e la porta Azure Blob Storage come 127.0.0.1:10000, seguiti dal nome dell'account di storage 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 Description
timeout Optional. Il timeout parametro è espresso in secondi. Per ulteriori informazioni, vedi Impostazione dei timeout per le operazioni di Azure Blob Storage.

Header di richiesta

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

Header di richiesta Description
Authorization Obbligatorio. Specifica lo schema di autorizzazione, il nome dell'account e la firma. Vedi Autorizzare richieste ad Azure Storage per maggiori informazioni.
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. La lunghezza del contenuto del blocco in byte. La dimensione del blocco deve essere inferiore o uguale a 100 MiB (anteprima) per la versione 2022-11-02 e successive. Vedi la sezione Osservazioni per i limiti nelle versioni più vecchie.

Quando la lunghezza non viene fornita, l'operazione fallirà con il codice di stato 411 (Lunghezza richiesta).
Content-MD5 Optional. Un hash MD5 del contenuto del blocco. Questo hash viene utilizzato per verificare l'integrità del blocco durante il trasporto. Quando questo intestaggio viene specificato, il servizio di archiviazione confronta l'hash del contenuto arrivato con questo valore di intestare.

Nota che questo hash MD5 non viene memorizzato con il blob.

Se i due hash non corrispondono, l'operazione fallirà con il codice di errore 400 (Richiesta cattiva).
x-ms-content-crc64 Optional. Un hash CRC64 del contenuto del blocco append. Questo hash viene utilizzato per verificare l'integrità del blocco append durante il trasporto. Quando questo intestaggio viene specificato, il servizio di archiviazione confronta l'hash del contenuto arrivato con questo valore di intestare.

Nota che questo hash CRC64 non viene memorizzato con il blob.

Se i due hash non corrispondono, l'operazione fallirà con il codice di errore 400 (Richiesta cattiva).

Se sono presenti entrambi Content-MD5 e x-ms-content-crc64 le intestazioni, la richiesta fallirà con il codice di errore 400.

Questa intestazione è supportata nelle versioni 2019-02-02 o successive.
x-ms-encryption-scope Optional. Indica l'ambito di crittografia da usare per crittografare il contenuto della richiesta. Questa intestazione è supportata nelle versioni 2019-02-02 o successive.
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 Optional. 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 utilizzare questa intestazione per correlare le attività lato client con le richieste ricevute dal server. Per altre informazioni, vedere Monitorare l'archiviazione BLOB di Azure.
x-ms-blob-condition-maxsize Intestazione condizionale opzionale. Specifica la lunghezza massima in byte consentita per il blob di appendenza. Se l'operazione Append Block fa superare il blob a quel limite, o se la dimensione del blob è già maggiore del valore specificato in questa intestare, la richiesta fallisce con il codice di errore 412 (Precondizione fallita).
x-ms-blob-condition-appendpos Intestazione condizionale opzionale, usata solo per l'operazione Append Block . Un numero indica l'offset di byte da confrontare. Append Block ha successo solo se la posizione di append è uguale a questo numero. Se non lo è, la richiesta fallisce con il codice di errore 412 (Precondizione fallita).

Questa operazione supporta l'uso di intestazioni condizionali aggiuntive per garantire che l'API abbia successo solo se una condizione specificata è soddisfatta. Per ulteriori informazioni, vedi Specificare le intestazioni condizionali per le operazioni di Azure Blob Storage.

Intestazioni richieste (chiavi di crittografia fornite dal cliente)

A partire dalla versione 2019-02-02, puoi specificare le seguenti intestazioni nella richiesta di crittare un blob con una chiave fornita dal cliente. La crittografia con una chiave fornita dal cliente (e il corrispondente insieme di intestazioni) è opzionale.

Header di richiesta Description
x-ms-encryption-key Obbligatorio. La chiave di crittografia AES-256 codificata in Base64.
x-ms-encryption-key-sha256 Obbligatorio. L'hash SHA256 codificato in 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.

Intestazioni di richiesta (corpo strutturato)

A partire dalla versione 2025-01-05, le seguenti intestazioni possono essere specificate nella richiesta per sfruttare il formato strutturato del corpo.

Header di richiesta Description
Content-Length Obbligatorio. Deve essere la lunghezza della richiesta codificata (non solo la lunghezza del contenuto del blocco).

Se il valore dell'intestazione non corrisponde alla lunghezza attesa della richiesta codificata, l'operazione fallisce con il codice di errore 400 (Richiesta Mala).
x-ms-structured-body Obbligatorio. Deve essere incluso se il formato del messaggio è strutturato. Il valore di questa intestazione contiene la versione e le proprietà dello schema del messaggio.

Attualmente, l'unico valore supportato è XSM/1.0; properties=crc64, indicando che la richiesta utilizza segmenti di checksum crc64 nel messaggio codificato. Se il valore non corrisponde a questo, l'operazione fallisce con il codice errore 400 (Richiesta Difettosa). La richiesta fallirà anche se il contenuto fornito nella richiesta non corrisponde al checksum fornito per un dato segmento.
x-ms-structured-content-length Obbligatorio. Deve essere incluso se il formato del messaggio è strutturato. Il valore di questa intestazione è la lunghezza del contenuto del blocco e sarà sempre inferiore al Content-Length valore dell'intestazione a causa della codifica del messaggio.

Se il valore dell'intestazione non corrisponde alla lunghezza del contenuto del blocco fornito nella richiesta, l'operazione fallisce con il codice di errore 400 (Richiesta Sbagliata).

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: 2015-02-21  
x-ms-date: <date>  
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048  
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 alle specifiche del protocollo HTTP/1.1.

Intestazione della risposta Description
ETag Contiene ETag un valore tra virgolette. Il client può utilizzare il valore per eseguire operazioni condizionali PUT utilizzando l'intestazione If-Match della richiesta.
Last-Modified La data e l'ora in cui il blob è stato modificato l'ultima volta. Il formato della data segue la RFC 1123. Per maggiori informazioni, vedi Rappresentazione dei valori data-ora nelle intestazioni.

Qualsiasi operazione di scrittura sul blob (inclusi gli aggiornamenti sui metadati o le proprietà del blob) modifica il tempo dell'ultima modifica del blob.
Content-MD5 Questa intestazione viene restituita in modo che il client possa verificare l'integrità del contenuto del messaggio. Il valore di questa intestazione viene calcolato da Blob Storage. Non è necessariamente lo stesso valore specificato nelle intestazioni delle richieste. Per le versioni 2019-02-02 o successive, questa intestazione viene restituita solo quando la richiesta ha questa interia.
x-ms-content-crc64 Per le versioni 2019-02-02 o successive, questa intestazione viene restituita affinché il client possa verificare l'integrità del contenuto dei messaggi. Il valore di questa intestazione viene calcolato da Blob Storage. Non è necessariamente lo stesso valore specificato nelle intestazioni delle richieste.

Questo header viene restituito quando non è Content-md5 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 di data/ora UTC che indica l'ora in cui è stata avviata la risposta. Il servizio genera questo valore.
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. Puoi usarlo per controllare quante altre appendici si possono fare.
x-ms-request-server-encrypted: true/false Versione 2015-12-11 o successiva. Il valore di questa intestazione è impostato a true se il contenuto della richiesta viene criptato con successo utilizzando l'algoritmo specificato. Altrimenti, il valore è impostato a false.
x-ms-encryption-key-sha256 Versione 2019-02-02 o successiva. Questa intestazione viene restituita se la richiesta utilizza una chiave fornita dal cliente per la cifratura. Il client può quindi assicurarsi che il contenuto della richiesta venga criptato con successo 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 cifratura. Il client può quindi assicurarsi che il contenuto della richiesta venga criptato con successo utilizzando l'ambito di crittografia.
x-ms-client-request-id È possibile usare questa intestazione 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. Il valore è al massimo 1024 caratteri ASCII visibili. Se l'intestazione x-ms-client-request-id non è presente nella richiesta, questa intestazione non è presente nella risposta.
x-ms-structured-body Restituito se la richiesta è stata elaborata come una richiesta strutturata del corpo. Il valore di questa intestazione è uguale al valore inviato nella richiesta, che attualmente deve essere XSM/1.0; properties=crc64.

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

Authorization

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

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.

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

Permissions

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 e il ruolo controllo degli accessi in base al ruolo di Azure con privilegi minimi che include questa azione:

Per altre informazioni sull'assegnazione di ruoli tramite il controllo degli accessi in base al ruolo di Azure, vedere Assegnare un ruolo di Azure per l'accesso ai dati BLOB.

Osservazioni:

Append Block carica un blocco alla fine di un blob di append esistente. Il blocco di dati è immediatamente disponibile dopo che la chiamata è andata a termine sul server. Sono consentiti un massimo di 50.000 appendici per ogni blocco di appendi. Ogni blocco può avere dimensioni diverse.

La tabella seguente descrive le dimensioni massime consentite di blocchi e blob, per versione del servizio:

Versione del servizio Dimensione massima del blocco (tramite Append Block) Dimensione massima 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)

Append Block ha successo solo se il blob esiste già.

I blob caricati usando Append Block non espongono gli ID dei blocchi. Non puoi chiamare Get Block List contro un blob di appendi. Facendo così si traduce in un errore.

Puoi specificare le seguenti intestazioni opzionali e condizionate nella richiesta:

  • x-ms-blob-condition-appendpos: Puoi impostare questo header su un offset di byte al quale il client si aspetta di aggiungere il blocco. La richiesta ha successo solo se lo offset corrente corrisponde a quello specificato dal client. Altrimenti, la richiesta fallisce con il codice di errore 412 (Precondizione fallita).

    I client che utilizzano un singolo scrittore possono utilizzare questa intestazione per determinare se un'operazione Append Block è andata a buon fine, nonostante un guasto di rete.

  • x-ms-blob-condition-maxsize: I client possono utilizzare questa intestazione per assicurarsi che le operazioni di append non aumentino la dimensione del blob oltre una dimensione massima attesa in byte. Se la condizione fallisce, la richiesta fallisce con il codice di errore 412 (Precondizione fallita).

Se tenti di caricare un blocco superiore alla dimensione consentita, il servizio restituisce il codice di errore 413 (Request Entity Too Large). Il servizio restituisce inoltre ulteriori informazioni sull'errore nella risposta, inclusa la dimensione massima del blocco consentita in byte. Se tenti 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 di locazione valido nella richiesta per poter scrivere un blocco al blob. Se il client non specifica un ID di leasing, o indica un ID di leasing non valido, Blob Storage restituisce il codice di errore 412 (Precondizione fallita). Se il client specifica un ID di leasing, ma il blob non ha un lease attivo, Blob Storage restituisce anche il codice di errore 412.

Se richiami Append Block un blob di blocco o di pagina esistente, il servizio restituisce un errore di conflitto. Se chiami Append Block un blob inesistente, il servizio restituisce anche un errore.

Evitare aggiunte duplicate o ritardate

In uno scenario con singolo scrittore, il client può evitare aggiunzioni duplicate o scritture ritardate usando l'intestazione *x-ms-blob-condition-appendpos condizionale per verificare lo offset corrente. Il client può anche evitare duplicati o ritardi controllando condizionalmente la ETag situazione, usando If-Match.

In uno scenario con scrittore multiplo, ogni client può usare intestazioni condizionali, ma questo potrebbe non essere ottimale per le prestazioni. Per la più alta velocità di attacco concorrente, le applicazioni dovrebbero gestire appendi ridondanti e appendi ritardati nel livello applicativo. Ad esempio, l'applicazione può aggiungere epoche o numeri di sequenza nei dati che vengono aggiunti.

Billing

Le richieste di prezzi possono provenire da 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 il conto. Ad esempio, le transazioni di lettura vengono attribuite a una categoria di fatturazione diversa rispetto alle transazioni di scrittura. La tabella seguente illustra la categoria di fatturazione per Append Block le richieste in base al tipo di account di archiviazione:

Operation Tipo di account di archiviazione Categoria di fatturazione
Blocco di accodamento BLOB blocchi Premium
Utilizzo generico v2 Standard
Standard per utilizzo generico v1		 Operazioni di scrittura

Gli Append Blocks non supportano il tier a livello di oggetto ma deducono il loro livello di accesso dall'impostazione predefinita dell'account access tier e vengono fatturati di conseguenza. Per saperne di più sull'impostazione predefinita del tier dell'account, consulta Access Tiers per i dati blob - Azure Storage.

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

  • Last updated on