Guida introduttiva: libreria client di Archiviazione BLOB di Azure per C++

Introduzione alla libreria client Archiviazione BLOB di Azure per C++. Archiviazione BLOB di Azure è la soluzione Microsoft per l'archiviazione di oggetti per il cloud. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.

| Documentazione | di riferimento sulle API Esempi di codice | sorgente della libreria |

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito
• Account di archiviazione di Azure: creare un account di archiviazione
• Compilatore C++
• CMake
• vcpkg - Gestione pacchetti C e C++

Configurazione

Questa sezione illustra come preparare un progetto per lavorare con la libreria client Archiviazione BLOB di Azure per C++. Il modo più semplice per acquisire Azure SDK per C++ consiste nell'usare la vcpkg gestione pacchetti.

Installare i pacchetti

Usare il vcpkg install comando per installare la libreria di Archiviazione BLOB di Azure per C++ e le dipendenze necessarie:

vcpkg.exe install azure-storage-blobs-cpp

La libreria di identità di Azure è necessaria per le connessioni senza password ai servizi di Azure:

vcpkg.exe install azure-identity-cpp

Per altre informazioni sulla configurazione del progetto e sull'uso di Azure SDK per C++, vedere il file leggimi azure SDK per C++.

Creare il progetto

In Visual Studio creare una nuova applicazione console C++ per Windows denominata BlobQuickstart.

Modello a oggetti

Il servizio Archiviazione BLOB di Azure è ottimizzato per archiviare enormi quantità di dati non strutturati. I dati non strutturati sono dati che non seguono una definizione o un modello di dati specifico, ad esempio dati di testo o binari. Archiviazione BLOB offre tre tipi di risorse:

• L'account di archiviazione
• Un contenitore nell'account di archiviazione
• Un oggetto BLOB in un contenitore

Il diagramma seguente mostra la relazione tra queste risorse.

Usare queste classi C++ per interagire con queste risorse:

• BlobServiceClient: la BlobServiceClient classe consente di modificare Archiviazione di Azure risorse e contenitori BLOB.
• BlobContainerClient: la BlobContainerClient classe consente di modificare Archiviazione di Azure contenitori e i relativi BLOB.
• BlobClient: la BlobClient classe consente di modificare Archiviazione di Azure BLOB. È la classe di base per tutte le classi BLOB specializzate.
• BlockBlobClient: la BlockBlobClient classe consente di modificare Archiviazione di Azure BLOB in blocchi.

Esempi di codice

Questi frammenti di codice di esempio illustrano come eseguire le attività seguenti con la libreria client di Archiviazione BLOB di Azure per C++:

• Aggiungere file di inclusione
• Eseguire l'autenticazione in Azure e autorizzare l'accesso ai dati BLOB
• Creare un contenitore
• Caricare BLOB in un contenitore
• Elencare i BLOB in un contenitore
• Scaricare BLOB
• Eliminare un contenitore

Aggiungere file di inclusione

Dalla directory del progetto:

1. Aprire il file di soluzione BlobQuickstart.sln in Visual Studio
2. In Visual Studio aprire il file di origine BlobQuickstart.cpp
3. Rimuovere eventuale codice all'interno di main che è stato generato automaticamente
4. Aggiungere #include istruzioni e using namespace

#include <iostream>
#include <azure/core.hpp>
#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs.hpp>

using namespace Azure::Identity;
using namespace Azure::Storage::Blobs;

Eseguire l'autenticazione in Azure e autorizzare l'accesso ai dati BLOB

Le richieste dell'applicazione a Archiviazione BLOB di Azure devono essere autorizzate. L'uso della DefaultAzureCredential classe fornita dalla libreria client di Identità di Azure è l'approccio consigliato per l'implementazione di connessioni senza password ai servizi di Azure nel codice, incluso l'Archiviazione BLOB.

È anche possibile autorizzare le richieste di Archiviazione BLOB di Azure usando la chiave di accesso dell'account. Tuttavia, questo approccio deve essere usato con cautela. Gli sviluppatori devono essere diligenti per non esporre mai la chiave di accesso in una posizione non sicura. Chiunque abbia la chiave di accesso è in grado di autorizzare le richieste all'account di archiviazione e può accedere in modo efficace a tutti i dati. DefaultAzureCredential offre vantaggi di gestione e sicurezza migliorati rispetto alla chiave dell'account per consentire l'autenticazione senza password. Entrambe le opzioni sono illustrate nell'esempio seguente.

Senza password (scelta consigliata)

La libreria di identità di Azure fornisce il supporto per l'autenticazione del token Microsoft Entra in Azure SDK. Fornisce un set di TokenCredential implementazioni che possono essere usate per costruire client Azure SDK che supportano l'autenticazione del token Microsoft Entra. DefaultAzureCredential supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione.

Assegnare ruoli all'account utente di Microsoft Entra

Quando si sviluppa in locale, assicurarsi che l'account utente che accede ai dati BLOB disponga delle autorizzazioni corrette. È necessario Archiviazione Collaboratore ai dati BLOB per leggere e scrivere dati BLOB. Per assegnare a se stessi questo ruolo, è necessario assegnare il ruolo Accesso utente Amministrazione istrator o un altro ruolo che include l'azione Microsoft.Authorization/roleAssignments/write. È possibile assegnare ruoli controllo degli accessi in base al ruolo di Azure a un utente usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell. Per altre informazioni sugli ambiti disponibili per le assegnazioni di ruolo, vedere la pagina di panoramica dell'ambito.

In questo scenario si assegneranno le autorizzazioni all'account utente, con ambito all'account di archiviazione, per seguire il principio dei privilegi minimi. Questa procedura offre agli utenti solo le autorizzazioni minime necessarie e crea ambienti di produzione più sicuri.

L'esempio seguente assegnerà il ruolo collaboratore ai dati BLOB Archiviazione all'account utente, che fornisce sia l'accesso in lettura che in scrittura ai dati BLOB nell'account di archiviazione.

Importante

Nella maggior parte dei casi, la propagazione dell'assegnazione di ruolo in Azure richiederà almeno due minuti, ma in rari casi può richiedere fino a otto minuti. Se si ricevono errori di autenticazione quando si esegue il codice per la prima volta, attendere alcuni istanti e riprovare.

Azure portal

1. Nella portale di Azure individuare l'account di archiviazione usando la barra di ricerca principale o lo spostamento a sinistra.

2. Nella pagina di panoramica dell'account di archiviazione selezionare Controllo di accesso (IAM) dal menu a sinistra.

3. Nella pagina Controllo di accesso (IAM) selezionare la scheda Assegnazioni di ruolo.

4. Selezionare + Aggiungi dal menu in alto e quindi Aggiungi assegnazione di ruolo dal menu a discesa risultante.

   

5. Usare la casella di ricerca per filtrare i risultati in base al ruolo desiderato. Per questo esempio, cercare Archiviazione Collaboratore dati BLOB e selezionare il risultato corrispondente e quindi scegliere Avanti.

6. In Assegna accesso a selezionare Utente, gruppo o entità servizio e quindi scegliere + Seleziona membri.

7. Nella finestra di dialogo cercare il nome utente di Microsoft Entra (in genere l'indirizzo di posta elettronica user@domain ) e quindi scegliere Seleziona nella parte inferiore della finestra di dialogo.

8. Selezionare Rivedi e assegna per passare alla pagina finale e quindi rivedi e assegna per completare il processo.

Interfaccia della riga di comando di Azure

Per assegnare un ruolo a livello di risorsa usando l'interfaccia della riga di comando di Azure, è prima necessario recuperare l'ID risorsa usando il az storage account show comando . È possibile filtrare le proprietà di output usando il --query parametro .

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Copiare l'output Id dal comando precedente. È quindi possibile assegnare ruoli usando il comando az role dell'interfaccia della riga di comando di Azure.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

Per assegnare un ruolo a livello di risorsa usando Azure PowerShell, è prima necessario recuperare l'ID risorsa usando il Get-AzResource comando .

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Copiare il Id valore dall'output del comando precedente. È quindi possibile assegnare ruoli usando il comando New-AzRoleAssignment in PowerShell.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

Accedere e connettere il codice dell'app ad Azure usando DefaultAzureCredential

È possibile autorizzare l'accesso ai dati nell'account di archiviazione seguendo questa procedura:

1. Assicurarsi di essere autenticati con lo stesso account Microsoft Entra a cui è stato assegnato il ruolo nell'account di archiviazione. È possibile eseguire l'autenticazione tramite l'interfaccia della riga di comando di Azure. Accedere ad Azure tramite l'interfaccia della riga di comando di Azure usando il comando seguente:

   az login
   

2. Per usare DefaultAzureCredential, assicurarsi che il pacchetto azure-identity-cpp sia installato e che venga aggiunto quanto segue #include :

   #include <azure/identity/default_azure_credential.hpp>
   

3. Aggiungere questo codice alla fine di main(). Quando il codice viene eseguito nella workstation locale, DefaultAzureCredential usa le credenziali per gli sviluppatori per l'interfaccia della riga di comando di Azure per l'autenticazione in Azure.

   // Initialize an instance of DefaultAzureCredential
    auto defaultAzureCredential = std::make_shared<DefaultAzureCredential>();
   
    auto accountURL = "https://<storage-account-name>.blob.core.windows.net";
    BlobServiceClient blobServiceClient(accountURL, defaultAzureCredential);
   

4. Assicurarsi di aggiornare il nome dell'account di archiviazione nell'URI dell'oggetto BlobServiceClient . Il nome dell'account di archiviazione è disponibile nella pagina di panoramica del portale di Azure.

   

   Nota

   Quando si usa L'SDK C++ in un ambiente di produzione, è consigliabile abilitare solo le credenziali che l'applicazione userà. Invece di usare DefaultAzureCredential, è consigliabile autorizzare l'uso di un tipo di credenziale specifico o usando ChainedTokenCredential con le credenziali supportate.

Stringa di connessione

Un stringa di connessione include la chiave di accesso dell'account di archiviazione e la usa per autorizzare le richieste. Prestare sempre attenzione a non esporre mai le chiavi in una posizione non sicura.

Nota

Per autorizzare l'accesso ai dati con la chiave di accesso dell'account di archiviazione, sono necessarie le autorizzazioni per l'azione di controllo degli accessi in base al ruolo di Azure seguente: Microsoft.Archiviazione/storageAccounts/listkeys/action. Il ruolo predefinito con privilegi minimi con autorizzazioni per questa azione è Lettore e Accesso ai dati, ma qualsiasi ruolo che include questa azione funzionerà.

Azure portal

1. Accedi al portale di Azure.

2. Individuare l'account di archiviazione.

3. Nel riquadro dei menu dell'account di archiviazione, in Sicurezza e rete selezionare Chiavi di accesso. Qui è possibile visualizzare le chiavi di accesso dell'account e il stringa di connessione completo per ogni chiave.

4. Nel riquadro Chiavi di accesso selezionare Mostra chiavi.

5. Nella sezione key1 individuare il valore della stringa di Connessione ion. Selezionare l'icona Copia negli Appunti per copiare il stringa di connessione. Il valore stringa di connessione verrà aggiunto a una variabile di ambiente nella sezione successiva.

   

Interfaccia della riga di comando di Azure

È possibile visualizzare il stringa di connessione per l'account di archiviazione usando il comando az storage account show-connection-string.

az storage account show-connection-string --name "<your-storage-account-name>"

PowerShell

È possibile assemblare un stringa di connessione con PowerShell usando i comandi Get-Az Archiviazione Account e Get-Az Archiviazione AccountKey.

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

Configurare la stringa di connessione di archiviazione

Dopo aver copiato il stringa di connessione, scriverlo in una nuova variabile di ambiente nel computer locale che esegue l'applicazione. Per impostare la variabile di ambiente, aprire una finestra della console e seguire le istruzioni per il sistema operativo specifico. Sostituire <yourconnectionstring> con la stringa di connessione effettiva.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Dopo aver aggiunto la variabile di ambiente in Windows, è necessario avviare una nuova istanza della finestra di comando.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

L'esempio di codice seguente recupera il stringa di connessione per l'account di archiviazione dalla variabile di ambiente creata in precedenza e usa il stringa di connessione per costruire un oggetto client del servizio.

Aggiungere questo codice alla fine di main():

    // Retrieve the connection string for use with the application. The storage
    // connection string is stored in an environment variable on the machine
    // running the application called AZURE_STORAGE_CONNECTION_STRING.
    // Note that _MSC_VER is set when using MSVC compiler.
    static const char* AZURE_STORAGE_CONNECTION_STRING = "AZURE_STORAGE_CONNECTION_STRING";

#if !defined(_MSC_VER)
    const char* connectionString = std::getenv(AZURE_STORAGE_CONNECTION_STRING);
#else
	// Use getenv_s for MSVC
	size_t requiredSize;
	getenv_s(&requiredSize, NULL, NULL, AZURE_STORAGE_CONNECTION_STRING);
	if (requiredSize == 0) {
		throw std::runtime_error("missing connection string from env.");
	}
	std::vector<char> value(requiredSize);
	getenv_s(&requiredSize, value.data(), value.size(), AZURE_STORAGE_CONNECTION_STRING);
	std::string connectionStringStr = std::string(value.begin(), value.end());
	const char* connectionString = connectionStringStr.c_str();
#endif

	auto blobServiceClient = BlobServiceClient::CreateFromConnectionString(connectionString);

Importante

La chiave di accesso dell'account deve essere usata con cautela. Se la chiave di accesso dell'account viene persa o accidentalmente inserita in una posizione non sicura, il servizio potrebbe diventare vulnerabile. Chiunque abbia la chiave di accesso è in grado di autorizzare le richieste all'account di archiviazione e può accedere in modo efficace a tutti i dati. DefaultAzureCredential offre funzionalità e vantaggi avanzati per la sicurezza ed è l'approccio consigliato per la gestione dell'autorizzazione per i servizi di Azure.

Creazione di un contenitore

Decidere un nome per il nuovo contenitore. Creare quindi un'istanza di BlobContainerClient e creare il contenitore.

Importante

I nomi dei contenitori devono essere in minuscolo. Per altre informazioni sulla denominazione di contenitori e BLOB, vedere Naming and Referencing Containers, Blobs, and Metadata (Assegnazione di nome e riferimento a contenitori, BLOB e metadati).

Aggiungere questo codice alla fine di main():

std::string containerName = "myblobcontainer";
auto containerClient = blobServiceClient.GetBlobContainerClient("myblobcontainer");

// Create the container if it does not exist
std::cout << "Creating container: " << containerName << std::endl;
containerClient.CreateIfNotExists();

Caricare BLOB in un contenitore

Il frammento di codice seguente consente di:

1. Dichiara una stringa contenente "Hello Azure!"
2. Ottenere un riferimento a un oggetto BlockBlobClient chiamando il metodo GetBlockBlobClient sul contenitore dalla sezione Creare un contenitore.
3. Carica la stringa nel BLOB chiamando la funzione UploadFrom . Questa funzione crea il BLOB se non esiste oppure lo aggiorna se esiste già.

Aggiungere questo codice alla fine di main():

std::string blobName = "blob.txt";
uint8_t blobContent[] = "Hello Azure!";
// Create the block blob client
BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName);

// Upload the blob
std::cout << "Uploading blob: " << blobName << std::endl;
blobClient.UploadFrom(blobContent, sizeof(blobContent));

Elencare i BLOB in un contenitore

Elencare i BLOB nel contenitore chiamando la funzione ListBlobs . Al contenitore è stato aggiunto un unico BLOB, quindi l'operazione restituisce solo tale BLOB.

Aggiungere questo codice alla fine di main():

std::cout << "Listing blobs..." << std::endl;
auto listBlobsResponse = containerClient.ListBlobs();
for (auto blobItem : listBlobsResponse.Blobs)
{
    std::cout << "Blob name: " << blobItem.Name << std::endl;
}

Scaricare BLOB

Ottenere le proprietà del BLOB caricato, quindi dichiarare e ridimensionare un nuovo oggetto std::vector<uint8_t> usando le proprietà del BLOB caricato. Scaricare il BLOB creato in precedenza nel nuovo std::vector<uint8_t> oggetto chiamando la funzione DownloadTo nella classe di base BlobClient . Infine, visualizzare i dati del BLOB scaricato.

Aggiungere questo codice alla fine di main():

auto properties = blobClient.GetProperties().Value;
std::vector<uint8_t> downloadedBlob(properties.BlobSize);

blobClient.DownloadTo(downloadedBlob.data(), downloadedBlob.size());
std::cout << "Downloaded blob contents: " << std::string(downloadedBlob.begin(), downloadedBlob.end()) << std::endl;

Eliminare un BLOB

Il codice seguente elimina il BLOB dal contenitore di Archiviazione BLOB di Azure chiamando la funzione BlobClient.Delete.

std::cout << "Deleting blob: " << blobName << std::endl;
blobClient.Delete();

Eliminare un contenitore

Il codice seguente pulisce le risorse create dall'app eliminando l'intero contenitore usando BlobContainerClient.Elimina.

Aggiungere questo codice alla fine di main():

std::cout << "Deleting container: " << containerName << std::endl;
containerClient.Delete();

Eseguire il codice

Questa app crea un contenitore e carica un file di testo in Archiviazione BLOB di Azure. L'esempio elenca quindi i BLOB nel contenitore, scarica il file e visualizza il contenuto del file. Infine, l'app elimina il BLOB e il contenitore.

L'output dell'app è simile all'esempio seguente:

Azure Blob Storage - C++ quickstart sample
Creating container: myblobcontainer
Uploading blob: blob.txt
Listing blobs...
Blob name: blob.txt
Downloaded blob contents: Hello Azure!
Deleting blob: blob.txt
Deleting container: myblobcontainer

Passaggi successivi

In questo argomento di avvio rapido si è appreso come caricare, scaricare ed elencare i BLOB con C++. È stato anche illustrato come creare ed eliminare un contenitore di Archiviazione BLOB di Azure.

Per visualizzare un esempio di Archiviazione BLOB per C++, procedere con:

esempi di libreria client Archiviazione BLOB di Azure per C++