Avvio rapido: libreria client di Archiviazione BLOB di Azure per .NET

  • Articolo

Nota

L'opzione Compila da zero illustra in modo dettagliato il processo di creazione di un nuovo progetto, l'installazione di pacchetti, la scrittura del codice e l'esecuzione di un'app console di base. Questo approccio è consigliato se vuoi comprendere tutti i dettagli relativi alla creazione di un'app che si connette a Archiviazione BLOB di Azure. Se si preferisce automatizzare le attività di distribuzione e iniziare con un progetto completato, scegliere Inizia con un modello.

Nota

L'opzione Inizia con un modello usa l'interfaccia della riga di comando per sviluppatori di Azure per automatizzare le attività di distribuzione e inizia con un progetto completato. Questo approccio è consigliato se si vuole esplorare il codice il più rapidamente possibile senza eseguire le attività di configurazione. Se si preferisce istruzioni dettagliate per compilare l'app, scegliere Compila da zero.

Introduzione alla libreria client di Archiviazione BLOB di Azure per .NET Archiviazione BLOB di Azure è la soluzione di archiviazione di oggetti di Microsoft per il cloud ottimizzata per l'archiviazione di enormi quantità di dati non strutturati.

In questo articolo si seguono i passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.

In questo articolo si usa l'interfaccia della riga di comando per sviluppatori di Azure per distribuire le risorse di Azure ed eseguire un'app console completata con pochi comandi.

Documentazione di riferimento dell'API | Codice sorgente della libreria | Pacchetto (NuGet) | Esempi

Questo video illustra come iniziare a usare la libreria client Archiviazione BLOB di Azure per .NET.

I passaggi del video sono descritti anche nelle sezioni seguenti.

Prerequisiti

Configurazione

Questa sezione illustra come preparare un progetto da usare con la libreria client di Archiviazione BLOB di Azure per .NET.

Creare il progetto

Creare un'app console .NET usando l'interfaccia della riga di comando di .NET o Visual Studio 2022.

  1. Nella parte superiore di Visual Studio passare a File>Nuovo>progetto...

  2. Nella finestra di dialogo immettere l'app console nella casella di ricerca del modello di progetto e selezionare il primo risultato. Scegliere Avanti nella parte inferiore della finestra di dialogo.

    A screenshot showing how to create a new project using Visual Studio.

  3. Per Nome progetto immettere BlobQuickstart. Lasciare i valori predefiniti per il resto dei campi e selezionare Avanti.

  4. Per Framework verificare che sia selezionata la versione più recente installata di .NET. Scegli quindi Crea. Il nuovo progetto viene aperto all'interno dell'ambiente di Visual Studio.

Installare il pacchetto

Per interagire con Archiviazione BLOB di Azure, installare la libreria client Archiviazione BLOB di Azure per .NET.

  1. In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo Dipendenze del progetto. Scegliere Gestisci pacchetti NuGet.

  2. Nella finestra risultante cercare Azure.Archiviazione. BLOB. Selezionare il risultato appropriato e selezionare Installa.

    A screenshot showing how to add a new package using Visual Studio.

Configurare il codice dell'app

Sostituire il codice iniziale nel Program.cs file in modo che corrisponda all'esempio seguente, che include le istruzioni necessarie using per questo esercizio.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Con l'interfaccia della riga di comando per sviluppatori di Azure installata, è possibile creare un account di archiviazione ed eseguire il codice di esempio con pochi comandi. È possibile eseguire il progetto nell'ambiente di sviluppo locale o in devContainer.

Inizializzare il modello dell'interfaccia della riga di comando per sviluppatori di Azure e distribuire le risorse

Da una directory vuota seguire questa procedura per inizializzare il modello, effettuare il provisioning delle azd risorse di Azure e iniziare a usare il codice:

  • Clonare gli asset del repository di avvio rapido da GitHub e inizializzare il modello in locale:

    azd init --template blob-storage-quickstart-dotnet

    Verranno richieste le informazioni seguenti:

    • Nome ambiente: questo valore viene usato come prefisso per tutte le risorse di Azure create dall'interfaccia della riga di comando per sviluppatori di Azure. Il nome deve essere univoco in tutte le sottoscrizioni di Azure e deve avere una lunghezza compresa tra 3 e 24 caratteri. Il nome può contenere solo lettere minuscole e numeri.

  • Accedere ad Azure:

    azd auth login

  • Effettuare il provisioning e distribuire le risorse in Azure:

    azd up

    Verranno richieste le informazioni seguenti:

    • Sottoscrizione: sottoscrizione di Azure in cui vengono distribuite le risorse.
    • Località: area di Azure in cui vengono distribuite le risorse.

    Il completamento della distribuzione può richiedere alcuni minuti. L'output del azd up comando include il nome dell'account di archiviazione appena creato, che sarà necessario in un secondo momento per eseguire il codice.

Eseguire il codice di esempio

A questo punto, le risorse vengono distribuite in Azure e il progetto è pronto per l'esecuzione. Seguire questa procedura per aggiornare il nome dell'account di archiviazione nel codice ed eseguire l'app console di esempio:

  • Aggiornare il nome dell'account di archiviazione: passare alla src directory e modificare Program.cs. Trovare il <storage-account-name> segnaposto e sostituirlo con il nome effettivo dell'account di archiviazione creato dal azd up comando . Salvare le modifiche.
  • Eseguire il progetto: se si usa Visual Studio, premere F5 per compilare ed eseguire il codice e interagire con l'app console. Se si usa l'interfaccia della riga di comando di .NET, passare alla directory dell'applicazione, compilare il progetto usando dotnet builded eseguire l'applicazione usando .dotnet run
  • Osservare l'output: questa app crea un file di test nella cartella dati locale e lo carica in un contenitore nell'account di archiviazione. L'esempio elenca quindi i BLOB presenti nel contenitore e scarica il file con un nuovo nome per consentire il confronto tra i nuovi file e quelli precedenti.

Per altre informazioni sul funzionamento del codice di esempio, vedere Esempi di codice.

Al termine del test del codice, vedere la sezione Pulire le risorse per eliminare le risorse create dal azd up comando .

Modello a oggetti

Il servizio Archiviazione BLOB di Azure è ottimizzato per archiviare enormi quantità di dati non strutturati. I dati non strutturati non rispettano un particolare modello di dati o una definizione, ad esempio dati di testo o binari. L'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.

Diagram of Blob storage architecture.

Per interagire con queste risorse, usare le classi .NET seguenti:

  • 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.

Esempi di codice

I frammenti di codice di esempio nelle sezioni seguenti illustrano come eseguire le attività seguenti con la libreria client Archiviazione BLOB di Azure per .NET:

Importante

Assicurarsi di aver installato i pacchetti NuGet corretti e aggiunto le istruzioni using necessarie per consentire il funzionamento degli esempi di codice, come descritto nella sezione relativa alla configurazione.

Nota

Il modello dell'interfaccia della riga di comando per sviluppatori di Azure include un progetto con codice di esempio già disponibile. Negli esempi seguenti vengono forniti dettagli per ogni parte del codice di esempio. Il modello implementa il metodo di autenticazione senza password consigliato, come descritto nella sezione Eseguire l'autenticazione in Azure . Il metodo stringa di connessione viene visualizzato come alternativa, ma non viene usato nel modello e non è consigliato per il codice di produzione.

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.

DefaultAzureCredential è una classe fornita dalla libreria client di Identità di Azure per .NET, che è possibile ottenere altre informazioni sulla panoramica di DefaultAzureCredential. DefaultAzureCredential supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione. Questo approccio consente all'app di usare metodi di autenticazione diversi in ambienti diversi (locale e di produzione) senza implementare codice specifico dell'ambiente.

L'ordine e le posizioni in cui DefaultAzureCredential cercare le credenziali sono disponibili nella panoramica della libreria di identità di Azure.

Ad esempio, l'app può eseguire l'autenticazione usando le credenziali di accesso di Visual Studio con durante lo sviluppo in locale. L'app può quindi usare un'identità gestita dopo la distribuzione in Azure. Per questa transizione non sono necessarie modifiche al codice.

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.

  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.

    A screenshot showing how to assign a role.

  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.

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. Per lo sviluppo locale, assicurarsi di essere autenticati con lo stesso account Microsoft Entra a cui è stato assegnato il ruolo. È possibile eseguire l'autenticazione tramite strumenti di sviluppo diffusi, ad esempio l'interfaccia della riga di comando di Azure o Azure PowerShell. Gli strumenti di sviluppo con cui è possibile eseguire l'autenticazione variano a seconda dei linguaggi.

    Accedere ad Azure tramite l'interfaccia della riga di comando di Azure usando il comando seguente:

    az login

  2. Per usare DefaultAzureCredential, aggiungere il pacchetto Azure.Identity all'applicazione.

    1. In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo Dipendenze del progetto. Scegliere Gestisci pacchetti NuGet.

    2. Nella finestra risultante cercare Azure.Identity. Selezionare il risultato appropriato e selezionare Installa.

      A screenshot showing how to add the identity package.

  3. Aggiornare il codice Program.cs in modo che corrisponda all'esempio seguente. Quando il codice viene eseguito nella workstation locale durante lo sviluppo, userà le credenziali per sviluppatori dello strumento con priorità a cui si è connessi per l'autenticazione in Azure, ad esempio l'interfaccia della riga di comando di Azure o Visual Studio.

    using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new 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.

    A screenshot showing how to find the storage account name.

    Nota

    Quando viene distribuito in Azure, questo stesso codice può essere usato per autorizzare le richieste a Archiviazione di Azure da un'applicazione in esecuzione in Azure. È tuttavia necessario abilitare l'identità gestita nell'app in Azure. Configurare quindi l'account di archiviazione per consentire la connessione a tale identità gestita. Per istruzioni dettagliate sulla configurazione di questa connessione tra i servizi di Azure, vedere l'esercitazione Sull'autenticazione dalle app ospitate in Azure.

Creazione di un contenitore

Creare un nuovo contenitore nell'account di archiviazione chiamando il metodo CreateBlobContainerAsync sull'oggetto blobServiceClient . In questo esempio il codice aggiunge un valore GUID al nome del contenitore per assicurarsi che sia univoco.

Aggiungere il codice seguente alla fine del file Program.cs:

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

Per altre informazioni sulla creazione di un contenitore e per esplorare altri esempi di codice, vedere Creare un contenitore BLOB con .NET.

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).

Caricare un BLOB in un contenitore

Caricare un BLOB in un contenitore usando UploadAsync. Il codice di esempio crea un file di testo nella directory dati locale da caricare nel contenitore.

Aggiungere il codice seguente alla fine del file Program.cs:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file, overwrite the blob if it already exists
await blobClient.UploadAsync(localFilePath, true);

Per altre informazioni sul caricamento di BLOB e per esplorare altri esempi di codice, vedere Caricare un BLOB con .NET.

Elencare i BLOB in un contenitore

Elencare i BLOB nel contenitore chiamando il metodo GetBlobsAsync.

Aggiungere il codice seguente alla fine del file Program.cs:

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

Per altre informazioni sull'elenco dei BLOB e per esplorare altri esempi di codice, vedere Elencare i BLOB con .NET.

Scaricare un BLOB

Scaricare il BLOB creato in precedenza chiamando il metodo DownloadToAsync . Il codice di esempio aggiunge la stringa "DOWNLOADED" al nome del file in modo che sia possibile visualizzare entrambi i file nel file system locale.

Aggiungere il codice seguente alla fine del file Program.cs:

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

Per altre informazioni sul download di BLOB e per esplorare altri esempi di codice, vedere Scaricare un BLOB con .NET.

Eliminare un contenitore

Il codice seguente pulisce le risorse create dall'app eliminando il contenitore usando DeleteAsync. L'esempio di codice elimina anche i file locali creati dall'app.

L'app viene sospesa per l'input dell'utente chiamando Console.ReadLine prima dell'eliminazione di BLOB, contenitore e file locali. Questa è una buona probabilità di verificare che le risorse siano state create correttamente, prima che vengano eliminate.

Aggiungere il codice seguente alla fine del file Program.cs:

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Per altre informazioni sull'eliminazione di un contenitore e per esplorare altri esempi di codice, vedere Eliminare e ripristinare un contenitore BLOB con .NET.

Codice completato

Dopo aver completato questi passaggi, il codice nel Program.cs file dovrebbe ora essere simile al seguente:

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Eseguire il codice

Questa app crea un file di test nella cartella data locale e lo carica nell'archiviazione BLOB. L'esempio elenca quindi i BLOB presenti nel contenitore e scarica il file con un nuovo nome per consentire il confronto tra i nuovi file e quelli precedenti.

Se si usa Visual Studio, premere F5 per compilare ed eseguire il codice e interagire con l'app console. Se si usa l'interfaccia della riga di comando di .NET, passare alla directory dell'applicazione, quindi compilare ed eseguire l'applicazione.

dotnet build

dotnet run

L'output dell'app è simile all'esempio seguente (i valori GUID omessi per la leggibilità):

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobsGUID/quickstartGUID.txt

Listing blobs...
        quickstartGUID.txt

Downloading blob to
        ./data/quickstartGUIDDOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

Prima di iniziare il processo di pulizia, controllare la cartella dei dati per i due file. È possibile aprirli e osservare che sono identici.

Pulire le risorse

Dopo aver verificato i file e aver completato il test, premere INVIO per eliminare i file di test insieme al contenitore creato nell'account di archiviazione. È anche possibile usare l'interfaccia della riga di comando di Azure per eliminare le risorse.

Al termine dell'avvio rapido, è possibile pulire le risorse create eseguendo il comando seguente:

azd down

Verrà richiesto di confermare l'eliminazione delle risorse. Immettere y per confermare.

Passaggi successivi

In questa guida introduttiva si è appreso come caricare, scaricare ed elencare i BLOB con .NET.

Per visualizzare le app di esempio di Archiviazione BLOB, procedere con:

libreria Archiviazione BLOB di Azure per esempi .NET