Come usare l'archiviazione delle code da C++
Suggerimento
Provare Esplora archivi Microsoft Azure
Microsoft Azure Storage Explorer è un'app autonoma gratuita di Microsoft che consente di rappresentare facilmente dati di Archiviazione di Azure in Windows, macOS e Linux.
Panoramica
Questa guida illustra come eseguire scenari comuni usando il servizio archiviazione code di Azure. Gli esempi vengono scritti in C++ e usano la libreria client di Archiviazione di Azure per C++. Gli scenari illustrati includono inserimento, visualizzazione, recupero ed eliminazione dei messaggi in coda, oltre alla creazione ed eliminazione di code.
Nota
Questa guida è destinata alla libreria client di Archiviazione di Azure per C++ v1.0.0 e versioni successive. La versione consigliata è la libreria client di Archiviazione di Azure v2.2.0, disponibile tramite NuGet o GitHub.
Che cos'è l'archiviazione code?
Il servizio di archiviazione di accodamento di Azure consente di archiviare grandi quantità di messaggi ai quali è possibile accedere da qualsiasi parte del mondo mediante chiamate autenticate tramite HTTP o HTTPS. La dimensione massima di un singolo messaggio della coda è di 64 KB e una coda può contenere milioni di messaggi, nei limiti della capacità complessiva di un account di archiviazione. L'archiviazione code viene spesso usata per creare un backlog di lavoro per elaborare in modo asincrono.
Concetti del servizio di accodamento
Il servizio Code di Azure contiene i componenti seguenti:
Account di archiviazione: Tutto l'accesso ad Archiviazione di Azure viene eseguito tramite un account di archiviazione. Per altre informazioni sugli account di archiviazione, vedere Panoramica dell'account di archiviazione.
Coda: una coda contiene un set di messaggi. Tutti i messaggi devono essere inclusi in una coda. Si noti che il nome della coda deve essere in lettere minuscole. Per altre informazioni, vedere Denominazione di code e metadati.
Messaggio: un messaggio, in qualsiasi formato, con dimensioni massime di 64 KB. Il tempo massimo che un messaggio può rimanere nella coda è di 7 giorni. Per la versione 2017-07-29 o successive, la durata massima consentita può essere un numero positivo qualsiasi o -1, a indicare che il messaggio non scade. Se questo parametro viene omesso, la durata predefinita è di sette giorni.
Formato URL: Le code sono indirizzabili usando il formato URL seguente: http://.queue.core.windows.net/
<storage account><queue>L'URL seguente fa riferimento a una delle code nel diagramma:
http://myaccount.queue.core.windows.net/incoming-orders
Creare un account di archiviazione di Azure
Il modo più semplice per creare il primo account di archiviazione di Azure consiste nell'usare il portale di Azure. Per altre informazioni, vedere Creare un account di archiviazione.
È anche possibile creare un account di archiviazione di Azure usando Azure PowerShell, l'interfaccia della riga di comando di Azure o il provider di risorse di archiviazione di Azure per .NET.
Se si preferisce non creare un account di archiviazione in Azure in questo momento, è anche possibile usare l'emulatore di archiviazione Azurite per eseguire e testare il codice in un ambiente locale. Per altre informazioni, vedere Usare l'emulatore Azurite per lo sviluppo locale di Archiviazione di Azure.
Creazione di un’applicazione C++
In questa guida verranno utilizzate le funzionalità di archiviazione che è possibile eseguire all’interno di un’applicazione C++.
A tale scopo, sarà necessario installare la libreria client di Archiviazione di Azure per C++ e creare un account di Archiviazione di Azure nella sottoscrizione di Azure.
Per installare la libreria client di Archiviazione di Azure per C++, è possibile usare i metodi seguenti:
- Linux: Seguire le istruzioni fornite nella libreria client di Archiviazione di Azure per C++ README: Introduzione nella pagina Linux.
- Windows: in Windows usare vcpkg come utilità di gestione dipendenze. Seguire la guida introduttiva per inizializzare
vcpkg. Quindi usare il comando seguente per installare la libreria:
.\vcpkg.exe install azure-storage-cpp
È possibile trovare una guida per come compilare il codice sorgente ed esportare in NuGet nel file README .
Configurazione dell'applicazione per l’accesso ad Archiviazione di accodamento
Aggiungere le istruzioni di inclusione seguenti all'inizio del file C++ in cui si desidera usare le API di Archiviazione di Azure per accedere alle code:
#include <was/storage_account.h>
#include <was/queue.h>
Configurare una stringa di connessione di archiviazione di Azure
I client di archiviazione di Azure usano le stringhe di connessione di archiviazione per archiviare endpoint e credenziali per l'accesso ai servizi di gestione dati. Quando si esegue in un'applicazione client, è necessario specificare la stringa di connessione di archiviazione nel formato seguente, usando il nome dell'account di archiviazione e la chiave di accesso di archiviazione per l'account di archiviazione elencato nel portale di Azure per i AccountName valori eAccountKey. Per informazioni sugli account di archiviazione e sulle chiavi di accesso, vedere Informazioni sugli account di archiviazione di Azure. In questo esempio viene illustrato come dichiarare un campo statico per memorizzare la stringa di connessione:
// Define the connection-string with your values.
const utility::string_t storage_connection_string(U("DefaultEndpointsProtocol=https;AccountName=your_storage_account;AccountKey=your_storage_account_key"));
Per testare l'applicazione nel computer Windows locale, è possibile usare l'emulatore di archiviazione Azurite. Azurite è un'utilità che simula Archiviazione BLOB di Azure e Archiviazione code nel computer di sviluppo locale. Nell’esempio seguente viene illustrato come dichiarare un campo statico per memorizzare la stringa di connessione all’emulatore di archiviazione locale:
// Define the connection-string with Azurite.
const utility::string_t storage_connection_string(U("UseDevelopmentStorage=true;"));
Per avviare Azurite, vedere Usare l'emulatore Azurite per lo sviluppo locale di Archiviazione di Azure.
Gli esempi seguenti presumono che sia stato usato uno di questi due metodi per ottenere la stringa di connessione di archiviazione.
Recuperare la stringa di connessione
Per visualizzare le informazioni dell'account di archiviazione, è possibile usare la classe cloud_storage_account. Per recuperare le informazioni sull'account di archiviazione dalla stringa di connessione di archiviazione, è possibile usare il parse metodo .
// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
Procedura: creare una coda
Un cloud_queue_client oggetto consente di ottenere oggetti di riferimento per le code. Il codice seguente crea un cloud_queue_client oggetto.
// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create a queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
Usare l'oggetto cloud_queue_client per ottenere un riferimento alla coda da usare. È possibile creare la coda se non esiste già.
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Create the queue if it doesn't already exist.
queue.create_if_not_exists();
Procedura: inserire un messaggio in una coda
Per inserire un messaggio in una coda esistente, creare prima di tutto un nuovo cloud_queue_message. Chiamare quindi il add_message metodo. È possibile creare un oggetto cloud_queue_message da una stringa (in formato UTF-8) o da una matrice di byte. Ecco il codice che crea una coda (se non esiste) e inserisce il messaggio Hello, World:
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Create the queue if it doesn't already exist.
queue.create_if_not_exists();
// Create a message and add it to the queue.
azure::storage::cloud_queue_message message1(U("Hello, World"));
queue.add_message(message1);
Procedura: visualizzare il messaggio successivo
È possibile visualizzare il messaggio davanti a una coda senza rimuoverlo dalla coda chiamando il peek_message metodo .
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Peek at the next message.
azure::storage::cloud_queue_message peeked_message = queue.peek_message();
// Output the message content.
std::wcout << U("Peeked message content: ") << peeked_message.content_as_string() << std::endl;
Procedura: cambiare il contenuto di un messaggio accodato
È possibile cambiare il contenuto di un messaggio inserito nella coda. Se il messaggio rappresenta un'attività di lavoro, è possibile utilizzare questa funzionalità per aggiornarne lo stato. Il codice seguente consente di aggiornare il messaggio in coda con nuovo contenuto e di impostarne il timeout di visibilità per prolungarlo di altri 60 secondi. In questo modo lo stato del lavoro associato al messaggio viene salvato e il client ha a disposizione un altro minuto per continuare l'elaborazione del messaggio. È possibile usare questa tecnica per tenere traccia dei flussi di lavoro multistep nei messaggi della coda, senza dover iniziare dall'inizio se un passaggio di elaborazione non riesce a causa di un errore hardware o software. In genere, è consigliabile mantenere anche un conteggio dei tentativi, in modo da eliminare i messaggi per cui vengono effettuati più di n tentativi. In questo modo è possibile evitare che un messaggio attivi un errore dell'applicazione ogni volta che viene elaborato.
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Get the message from the queue and update the message contents.
// The visibility timeout "0" means make it visible immediately.
// The visibility timeout "60" means the client can get another minute to continue
// working on the message.
azure::storage::cloud_queue_message changed_message = queue.get_message();
changed_message.set_content(U("Changed message"));
queue.update_message(changed_message, std::chrono::seconds(60), true);
// Output the message content.
std::wcout << U("Changed message content: ") << changed_message.content_as_string() << std::endl;
Procedura: rimuovere il messaggio successivo dalla coda
Il codice consente di rimuovere un messaggio da una coda in due passaggi. Quando si chiama get_message, viene visualizzato il messaggio successivo in una coda. Un messaggio restituito da get_message diventa invisibile a qualsiasi altro elemento di codice che legge i messaggi di questa coda. Per completare la rimozione del messaggio dalla coda, è necessario chiamare anche delete_message. Questo processo in due passaggi di rimozione di un messaggio assicura che, qualora l'elaborazione di un messaggio non riesca a causa di errori hardware o software, un'altra istanza del codice sia in grado di ottenere lo stesso messaggio e di riprovare. Il codice chiama delete_message subito dopo l'elaborazione del messaggio.
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Get the next message.
azure::storage::cloud_queue_message dequeued_message = queue.get_message();
std::wcout << U("Dequeued message: ") << dequeued_message.content_as_string() << std::endl;
// Delete the message.
queue.delete_message(dequeued_message);
Procedura: Usare opzioni aggiuntive per la dequeuing dei messaggi
È possibile personalizzare il recupero di messaggi da una coda in due modi. Innanzitutto, è possibile recuperare un batch di messaggi (massimo 32). In secondo luogo, è possibile impostare un timeout di invisibilità più lungo o più breve assegnando al codice più o meno tempo per l'elaborazione completa di ogni messaggio. Nell'esempio di codice seguente viene usato il metodo get_messages per recuperare 20 messaggi con una sola chiamata. Ogni messaggio viene poi elaborato con un ciclo for. Per ogni messaggio, inoltre, il timeout di invisibilità viene impostato su cinque minuti. Si noti che i cinque minuti iniziano contemporaneamente per tutti i messaggi, quindi dopo cinque minuti dalla chiamata a get_messages, tutti i messaggi che non sono stati eliminati diventeranno nuovamente visibili.
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Dequeue some queue messages (maximum 32 at a time) and set their visibility timeout to
// 5 minutes (300 seconds).
azure::storage::queue_request_options options;
azure::storage::operation_context context;
// Retrieve 20 messages from the queue with a visibility timeout of 300 seconds.
std::vector<azure::storage::cloud_queue_message> messages = queue.get_messages(20, std::chrono::seconds(300), options, context);
for (auto it = messages.cbegin(); it != messages.cend(); ++it)
{
// Display the contents of the message.
std::wcout << U("Get: ") << it->content_as_string() << std::endl;
}
Procedura: recuperare la lunghezza delle code
È possibile ottenere una stima sul numero di messaggi presenti in una coda. Il metodo download_attributes restituisce le proprietà della coda, incluso il numero dei messaggi. Il approximate_message_count metodo ottiene il numero approssimativo di messaggi nella coda.
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Fetch the queue attributes.
queue.download_attributes();
// Retrieve the cached approximate message count.
int cachedMessageCount = queue.approximate_message_count();
// Display number of messages.
std::wcout << U("Number of messages in queue: ") << cachedMessageCount << std::endl;
Procedura: eliminare una coda
Per eliminare una coda e tutti i messaggi che contiene, chiamare il metodo delete_queue_if_exists sull'oggetto coda.
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// If the queue exists and delete it.
queue.delete_queue_if_exists();
Passaggi successivi
Dopo aver appreso le nozioni di base di Archiviazione code, seguire questi collegamenti per altre informazioni su Archiviazione di Azure.