Esporta (0) Stampa
Espandi tutto

Put Page

Aggiornamento: gennaio 2014

Tramite l'operazione Put Page viene scritto un intervallo di pagine in un Blob di pagine.

La richiesta Put Page può essere costruita nel modo seguente. Si consiglia di utilizzare 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=page

HTTP/1.1

Quando si effettua una richiesta nel servizio di archiviazione emulato, specificare il nome host dell'emulatore e la porta del servizio Blob come 127.0.0.1:10000, seguiti 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=page

HTTP/1.1

Per altre informazioni, vedere Uso dell'emulatore di archiviazione di Azure per lo sviluppo e il test.

Nell'URI della richiesta è possibile specificare i parametri aggiuntivi seguenti.

 

Parametro Descrizione

timeout

Facoltativo. Il parametro timeout viene espresso in secondi. Per altre informazioni, vedere Impostazione di timeout per le operazioni del servizio Blob.

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

 

Intestazione della richiesta Descrizione

Authorization

Obbligatorio. Specifica lo schema di autenticazione, il nome dell'account e la firma. Per altre informazioni, vedere Autenticazione per i servizi di archiviazione di Azure.

Date o x-ms-date

Obbligatorio. Specifica l'ora UTC (Coordinated Universal Time) per la richiesta. Per altre informazioni, vedere Autenticazione per i servizi di archiviazione di Azure.

x-ms-version

Obbligatoria per tutte le richieste autenticate. Specifica la versione dell'operazione da utilizzare per questa richiesta. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.

Range

Range o x-ms-range è obbligatorio.

Specifica l'intervallo di byte da scrivere come pagina. È necessario specificare l'inizio e la fine dell'intervallo. Questa intestazione è definita nella specifica del protocollo HTTP/1.1.

Per un'operazione di aggiornamento di pagine, le dimensioni dell'intervallo possono estendersi fino a 4 MB. Per un'operazione di cancellazione di pagine, le dimensioni dell'intervallo possono estendersi fino al valore delle dimensioni totali del Blob.

Considerando che le pagine devono essere allineate a limiti di 512 byte, l'offset iniziale deve essere un modulo di 512, mentre quello finale deve essere un modulo di 512 – 1. Sono esempi di intervalli di byte validi 0-511, 512-1023 e così via.

Il servizio Blob accetta solo un singolo intervallo di byte per l'intestazione Range e l'intervallo di byte deve essere specificato nel formato seguente: bytes=startByte-endByte.

Se Range e x-ms-range sono entrambi specificati, il servizio utilizza il valore di x-ms-range. Per altre informazioni, vedere Specifica dell'intestazione di intervallo per le operazioni del servizio Blob.

x-ms-range

Range o x-ms-range è obbligatorio.

Specifica l'intervallo di byte da scrivere come pagina. È necessario specificare l'inizio e la fine dell'intervallo. Questa intestazione è definita nella specifica del protocollo HTTP/1.1.

Per un'operazione di aggiornamento di pagine, le dimensioni dell'intervallo possono estendersi fino a 4 MB. Per un'operazione di cancellazione di pagine, le dimensioni dell'intervallo possono estendersi fino al valore delle dimensioni totali del Blob.

Considerando che le pagine devono essere allineate a limiti di 512 byte, l'offset iniziale deve essere un modulo di 512, mentre quello finale deve essere un modulo di 512 – 1. Sono esempi di intervalli di byte validi 0-511, 512-1023 e così via.

Il servizio Blob accetta solo un singolo intervallo di byte per l'intestazione x-ms-range e l'intervallo di byte deve essere specificato nel formato seguente: bytes=startByte-endByte.

Se Range e x-ms-range sono entrambi specificati, il servizio utilizza il valore di x-ms-range. Per altre informazioni, vedere Specifica dell'intestazione di intervallo per le operazioni del servizio Blob.

Content-Length

Obbligatorio. Specifica il numero di byte trasmessi nel corpo della richiesta. Quando l'intestazione x-ms-page-write è impostata su clear, il suo valore deve essere impostato su zero.

Content-MD5

Facoltativo. Hash MD5 del contenuto della pagina. Questo hash viene utilizzato per verificare l'integrità della pagina durante il trasporto. Quando questa intestazione viene specificata, il servizio di archiviazione confronta l'hash del contenuto ricevuto con il valore dell'intestazione inviato. Se i due hash non corrispondono, l'operazione ha esito negativo e restituisce il codice di errore 400 (Richiesta non valida).

L'intestazione Content-MD5 non è consentita se l'intestazione x-ms-page-write è impostata su clear. Se viene inclusa con la richiesta, il servizio Blob restituisce il codice di stato 400 (Richiesta non valida).

x-ms-page-write: {update | clear}

Obbligatorio. È possibile specificare una delle opzioni seguenti:

  • Update: scrive i byte specificati dal corpo della richiesta nell'intervallo specificato. Per eseguire l'aggiornamento, è necessario che le intestazioni Range e Content-Length corrispondano.

  • Clear: cancella l'intervallo specificato e libera lo spazio utilizzato nell'archiviazione per tale intervallo. Per cancellare un intervallo, impostare l'intestazione Content-Length su zero e l'intestazione Range su un valore che indica l'intervallo da cancellare, fino alle dimensioni massime del Blob.

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-if-sequence-number-le: <num>

Facoltativo. Se il numero di sequenza del Blob è minore o uguale al valore specificato, la richiesta continua. In caso contrario, avrà esito negativo e verrà restituito l'errore SequenceNumberConditionNotMet (codice di stato HTTP 412 - Condizione preliminare non riuscita).

x-ms-if-sequence-number-lt: <num>

Facoltativo. Se il numero di sequenza del Blob è minore al valore specificato, la richiesta continua. In caso contrario, avrà esito negativo e verrà restituito l'errore SequenceNumberConditionNotMet (codice di stato HTTP 412 - Condizione preliminare non riuscita).

x-ms-if-sequence-number-eq: <num>

Facoltativo. Se il numero di sequenza del Blob è uguale al valore specificato, la richiesta continua. In caso contrario, avrà esito negativo e verrà restituito l'errore SequenceNumberConditionNotMet (codice di stato HTTP 412 - Condizione preliminare non riuscita).

If-Modified-Since

Facoltativo. Valore DateTime. Specificare questa intestazione condizionale per scrivere la pagina solo se il Blob è stato modificato dopo la data e l'ora specificate. Se il Blob non è stato modificato, il servizio Blob restituisce il codice di stato 412 (Condizione preliminare non riuscita).

If-Unmodified-Since

Facoltativo. Valore DateTime. Specificare questa intestazione condizionale per scrivere la pagina solo se il Blob non è stato modificato dopo la data e l'ora specificate. Se il Blob è stato modificato, il servizio Blob restituisce il codice di stato 412 (Condizione preliminare non riuscita).

If-Match

Facoltativo. Valore ETag. Specificare un valore ETag per questa intestazione condizionale per scrivere la pagina solo se il valore ETag del Blob corrisponde al valore specificato. Se i valori non corrispondono, il servizio Blob restituisce il codice di stato 412 (Condizione preliminare non riuscita).

If-None-Match

Facoltativo. Valore ETag.

Specificare un valore ETag per questa intestazione condizionale per scrivere la pagina solo se il valore ETag del Blob non corrisponde al valore specificato. Se i valori sono identici, tramite il servizio Blob viene restituito il codice di stato 412 (Condizione preliminare non riuscita).

x-ms-client-request-id

Facoltativo. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 KB che viene registrato nei log di analisi quando la registrazione di Analisi archiviazione è abilitata. L'utilizzo di questa intestazione è consigliato per la correlazione tra le attività sul lato client e le richieste ricevute dal server. Per altre informazioni vedere Informazioni sulla registrazione di Analisi archiviazione e l'articolo relativo all'utilizzo di log per tenere traccia delle richiesta di archiviazione nella registrazione di Azure.

Questa operazione supporta l'utilizzo delle intestazioni condizionali per eseguire l'operazione solo se viene soddisfatta una determinata condizione. Per altre informazioni, vedere Specifica di intestazioni condizionali per le operazioni del servizio Blob.

Il corpo della richiesta contiene il contenuto della pagina.


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

Request Headers:
x-ms-page-write: update
x-ms-date: Fri, 16 Sep 2011 22:15:50 GMT
x-ms-version: 2011-08-18
x-ms-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536


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

Request Headers:
Range: bytes=1024-2048
x-ms-page-write: clear
x-ms-date: Sun, 25 Sep 2011 23:37:35 GMT
x-ms-version: 2011-08-18
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=

Nella risposta sono inclusi un codice di stato HTTP e un set di intestazioni per la risposta.

Un'operazione completata correttamente restituisce il codice di stato 201 (Creato).

Per informazioni sui codici di stato, vedere Codici ed errori di stato.

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.

 

Sintassi Descrizione

ETag

Valore ETag per il Blob. Se la versione della richiesta è 2011-08-18 o successive, il valore ETag sarà racchiuso tra virgolette. Il valore ETag può essere utilizzato per eseguire un'operazione Put Page condizionale specificando il relativo valore per l'intestazione della richiesta If-Match o If-None-Match.

Last-Modified

Data e ora dell'ultima modifica del Blob. Il formato data è conforme a RFC 1123. Per altre informazioni, vedere Rappresentazione di valori di data e ora nelle intestazioni.

Qualsiasi operazione di scrittura sul Blob, inclusi aggiornamenti dei metadati o delle proprietà del Blob, comporta la modifica dell'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. Il valore di questa intestazione viene calcolato dal servizio Blob e non è necessariamente lo stesso valore che è stato specificato nelle intestazioni della richiesta.

x-ms-blob-sequence-number

Numero di sequenza corrente per il Blob di pagine.

x-ms-request-id

Questa intestazione identifica in modo univoco la richiesta effettuata e può essere utilizzata per risolvere i problemi relativi alla richiesta. Per altre informazioni, vedere Risoluzione dei problemi relativi alle operazioni dell'API.

x-ms-version

Indica la versione del servizio Blob utilizzata 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.

Response Status:
HTTP/1.1 201 Created

Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
Date: Sun, 25 Sep 2011 22:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Sun, 25 Sep 2011 12:13:31 GMT
x-ms-version: 2011-08-18
x-ms-blob-sequence-number: 0
Content-Length: 0
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

Questa operazione può essere chiamata dal proprietario dell'account e da qualsiasi altro utente che utilizza una firma di accesso condiviso con l'autorizzazione di scrittura per il Blob o il contenitore.

Tramite l'operazione Put Page viene scritto un intervallo di pagine in un Blob di pagine. Questa operazione può essere chiamata solo su un Blob di pagine esistente. Non può essere chiamata per creare un nuovo Blob di pagine, né su un Blob in blocchi. Se si chiama Put Page con un nome di Blob che non esiste, viene restituito l'errore BlobNotFound (codice di stato HTTP 404 - Non trovato).

Per creare un nuovo Blob di pagine, chiamare Put Blob e specificare il tipo di Blob da creare come Blob di pagine. Le dimensioni di un Blob di pagine possono estendersi al massimo a 1 TB.

Se il Blob presenta un lease attivo, il client deve specificare un ID lease valido nella richiesta per scrivere una pagina.

Operazioni di aggiornamento di pagine

Se si chiama Put Page con l'opzione Update, si esegue una scrittura sul posto sul Blob di pagine specificato. Il contenuto della pagina specificata viene sovrascritto con l'aggiornamento.

ImportantImportante
Se si verifica un timeout del server o la connessione viene chiusa durante Put Page, l'aggiornamento della pagina potrebbe anche non venire completato. È pertanto consigliabile tentare l'aggiornamento finché non si riceve una risposta che indica l'esito positivo.

Ogni intervallo di pagine inviate con Put Page per un'operazione di aggiornamento non può superare le dimensioni di 4 MB. L'inizio e la fine dell'intervallo di pagine devono essere allineati al limite di 512 byte. Se si tenta di caricare un intervallo di pagine di dimensioni superiori a 4 MB, il servizio restituisce il codice di stato 413 (Entità della richiesta troppo grande).

Operazioni di cancellazione di pagine

Se si chiama Put Page con l'opzione Clear si libera lo spazio di archiviazione utilizzato dalla pagina specificata. Le pagine che sono state cancellate non vengono più rilevate come parte del Blob di pagine.

Le pagine che sono state cancellate non rappresentano più un costo per l'account di archiviazione, in quanto le relative risorse di archiviazione sono state rilasciate. Fa eccezione il caso in cui esistono snapshot del Blob di pagine. Le pagine negli snapshot implicano un costo se queste stesse pagine non esistono più come parte del Blob di origine.

Gestione dei problemi di concorrenza

Il servizio Blob gestisce sequenzialmente le operazioni di scrittura simultanee nelle pagine che si sovrappongono, quindi l'ultima pagina elaborata dal servizio determina il contenuto del BLOB. Di conseguenza, per garantire l'integrità del contenuto del Blob, il client deve gestire le scritture sulle pagine sovrapposte utilizzando uno o più dei modi seguenti:

  • È possibile controllare il valore dell'intestazione della risposta Last-Modified per ogni chiamata completata a Put Page. L'ordine delle risposte restituite dal servizio Blob non corrisponde necessariamente all'ordine in cui sono state eseguite dal servizio. Tuttavia, il valore di Last-Modified indica sempre l'ordine in cui il servizio ha elaborato le richieste.

  • È possibile eseguire gli aggiornamenti in modo condizionale in base al valore ETag del Blob o all'ora dell'ultima modifica utilizzando la concorrenza ottimistica. Questo approccio è la soluzione appropriata se il numero di scritture simultanee è relativamente basso. Utilizzare le intestazioni di richiesta condizionali If-Match, If-None-Match, If-Modified-Since e If-Unmodified-Since a questo scopo.

  • È possibile chiamare Lease Blob per bloccare il Blob su altre scritture per un periodo di un minuto o più se il lease viene rinnovato.

  • È possibile utilizzare il numero di sequenza del Blob per assicurarsi che il nuovo tentativo di effettuare una richiesta che non ha ricevuto risposta non comporti aggiornamenti simultanei. Questo approccio è da preferire per i client che richiedono una velocità effettiva elevata per la scrittura di pagine. Viene descritto in dettaglio nella sezione seguente.

Utilizzo del numero di sequenza del Blob di pagine per ritentare le richieste

Quando si verifica il timeout di una chiamata a Put Page o non viene restituita alcuna risposta, non è possibile sapere con certezza se la richiesta ha avuto esito positivo. È pertanto necessario ritentare la richiesta. Tuttavia, a causa della natura distribuita dei servizi di archiviazione di Azure, è possibile che la richiesta originale venga elaborata dopo che la nuova richiesta ha avuto esito positivo. La richiesta originale ritardata può sovrascrivere altri aggiornamenti e restituire un risultato imprevisto. Nella sequenza seguente viene illustrata questa situazione:

  1. Si verifica il timeout di una richiesta Put Page per scrivere il valore "X" sulla pagina 0 oppure non viene restituita alcuna risposta.

  2. Una nuova richiesta per scrivere il valore "X" sulla pagina 0 ha esito positivo.

  3. Una richiesta per scrivere il valore "Y" sulla pagina 0 ha esito positivo.

  4. La richiesta originale ha esito positivo, quindi viene scritto il valore "X" sulla pagina 0.

  5. La lettura della pagina 0 restituisce il valore "X", anche se il client a questo punto si aspettava il valore "Y".

Questo tipo di conflitto può verificarsi quando la richiesta originale non restituisce un codice di stato compreso tra 100-499, ovvero 503 (Server occupato). Se viene restituito uno di questi codici di stato, si può sapere con sicurezza se la richiesta ha avuto esito positivo o negativo. Se invece il servizio restituisce un codice di stato non compreso in questo intervallo, non vi è modo di conoscere lo stato della richiesta originale.

Per evitare questo tipo di conflitto, è possibile utilizzare il numero di sequenza del Blob di pagine per assicurarsi che quando si ritenta una richiesta, la richiesta originale non avrà esito positivo in un momento successivo. A tale scopo, incrementare il numero di sequenza prima di ritentare la richiesta originale. È quindi possibile utilizzare le intestazioni condizionali del numero di sequenza per assicurarsi che la richiesta abbia esito negativo se il relativo numero di sequenza non corrisponde a quello previsto. Nella sequenza seguente viene illustrato questo approccio:

  1. Il client crea un Blob di pagine con Put Blob e imposta il relativo numero di sequenza su 0.

  2. Si verifica il timeout di una richiesta Put Page per scrivere il valore "X" sulla pagina 0 con l'intestazione if-sequence-number-lt impostata su 1 oppure non viene restituita alcuna risposta.

  3. Il client chiama Set Blob Properties per aggiornare il numero di sequenza a 1.

  4. Una nuova richiesta per scrivere il valore "X" sulla pagina 0 con if-sequence-number-lt impostato su 2 ha esito positivo.

  5. Una richiesta per scrivere il valore "Y" sulla pagina 0 con if-sequence-number-lt impostato su 2 ha esito positivo.

  6. La richiesta originale viene infine elaborata, ma ha esito negativo perché specifica la condizione secondo cui il numero di sequenza deve essere minore di 1 (intestazione if-sequence-num-lt impostata su 1). L'errore è SequenceNumberConditionNotMet (codice di stato HTTP 412 – Condizione preliminare non riuscita).

  7. La lettura della pagina 0 restituisce il valore "Y" previsto.

Mostra:
© 2015 Microsoft