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

Introduzione alla libreria client di Archiviazione BLOB di Azure per .NET Archiviazione BLOB di Azure è la soluzione di archiviazione di oggetti Microsoft per il cloud. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base. L'archiviazione BLOB è ottimizzata per l'archiviazione di grandi quantità di dati non strutturati.

Documentazione di | riferimento sulle API Codice | sorgente della libreriaPacchetto (NuGet) | Campioni

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

Per i passaggi successivi, è necessario creare un'app console .NET usando l'interfaccia della riga di comando .NET o Visual Studio 2022.

  1. Nella parte superiore di Visual Studio passare a File>New>Project....

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

    Screenshot che mostra come creare un nuovo progetto usando 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 .NET 6.0. Scegli quindi Crea. Il nuovo progetto verrà 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.Storage.BLOBs. Selezionare il risultato appropriato e selezionare Installa.

    Screenshot che mostra come aggiungere un nuovo pacchetto usando 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!");

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

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

È anche possibile autorizzare le richieste a 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 sull'account di archiviazione e può accedere in modo efficace a tutti i dati. DefaultAzureCredential offre vantaggi di gestione e sicurezza migliorati sulla 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 quale metodo deve essere usato in fase di esecuzione. Questo approccio consente all'app di usare metodi di autenticazione diversi in ambienti diversi (locale e produzione) senza implementare codice specifico dell'ambiente.

L'ordine e i percorsi 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 quando si sviluppa 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 Azure AD

Quando si sviluppa in locale, assicurarsi che l'account utente che accede ai dati BLOB disponga delle autorizzazioni corrette. È necessario collaboratore ai dati BLOB di archiviazione per leggere e scrivere dati BLOB. Per assegnare questo ruolo, è necessario assegnare il ruolo Amministratore accesso utente o un altro ruolo che include l'Microsoft. Azione authorization/roleAssignments/write. È possibile assegnare ruoli di controllo degli accessi in base al ruolo di Azure a un utente usando l'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 panoramica dell'ambito .

In questo scenario si assegnano 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.

Nell'esempio seguente verrà assegnato il ruolo Collaboratore dati BLOB di 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 l'assegnazione di ruolo richiederà un minuto o due per propagare in Azure, ma in rari casi potrebbe richiedere fino a otto minuti. Se si ricevono errori di autenticazione quando si esegue prima il codice, attendere alcuni momenti e riprovare.

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

  2. Nella pagina 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 Aggiungere l'assegnazione di ruolo dal menu a discesa risultante.

    Screenshot che mostra come assegnare un ruolo.

  5. Utilizzare la casella di ricerca per filtrare i risultati nel ruolo desiderato. Per questo esempio, cercare Collaboratore dati BLOB di archiviazione e selezionare il risultato corrispondente e quindi scegliere Avanti.

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

  7. Nella finestra di dialogo cercare il nome utente di Azure AD (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 di nuovo 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. Assicurarsi di essere autenticati con lo stesso account Azure AD assegnato al ruolo. È possibile eseguire l'autenticazione tramite l'interfaccia della riga di comando di Azure, Visual Studio o Azure PowerShell.

    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.

      Screenshot che mostra come aggiungere il pacchetto identity.

  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 di BlobServiceClient. Il nome dell'account di archiviazione è disponibile nella pagina di panoramica del portale di Azure.

    Screenshot che mostra come trovare il nome dell'account di archiviazione.

    Nota

    Quando viene distribuito in Azure, questo stesso codice può essere usato per autorizzare le richieste ad Archiviazione di Azure da un'applicazione in esecuzione in Azure. Sarà 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 .

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 modello di dati o una definizione specifici, 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.

Diagramma dell'architettura di archiviazione BLOB.

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

  • BlobServiceClient: la classe BlobServiceClient consente di modificare le risorse di Archiviazione di Azure e i contenitori BLOB.
  • BlobContainerClient: la classe BlobContainerClient consente di modificare i contenitori di Archiviazione di Azure e i relativi oggetti BLOB.
  • BlobClient: la classe BlobClient consente di modificare gli oggetti BLOB di Archiviazione di Azure.

Esempi di codice

I frammenti di codice di esempio nelle sezioni seguenti illustrano come eseguire operazioni di base sui dati 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 .

  • Azure.Identity (se si usa l'approccio senza password)
  • Azure.Storage.Blobs

Creare un contenitore

Decidere un nome per il nuovo contenitore. Il codice seguente aggiunge un valore GUID al nome del contenitore per garantirne l'univocità.

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

È possibile chiamare il metodo CreateBlobContainerAsync su blobServiceClient per creare un contenitore nell'account di archiviazione.

Aggiungere questo codice alla fine della Program.cs classe :

// 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);

Caricare un BLOB in un contenitore

Aggiungere il codice seguente alla fine della Program.cs classe :

// 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);

Il frammento di codice completa i passaggi seguenti:

  1. Creare un file di testo nella directory data locale.
  2. Ottenere un riferimento a un oggetto BlobClient chiamando il metodo GetBlobClient sul contenitore dalla sezione Creare un contenitore.
  3. Caricare il file di testo locale nel BLOB chiamando il metodo UploadAsync. Questo metodo crea il BLOB se non esiste o lo sovrascrive se esiste già.

Elencare i BLOB in un contenitore

Elencare i BLOB nel contenitore chiamando il metodo GetBlobsAsync. In questo caso, al contenitore è stato aggiunto un unico BLOB, quindi l'operazione di recupero dell'elenco restituisce solo tale BLOB.

Aggiungere il codice seguente alla fine della Program.cs classe:

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

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

Scaricare un BLOB

Scaricare il BLOB creato in precedenza chiamando il metodo DownloadToAsync . Il codice di esempio aggiunge il suffisso "DOWNLOADED" al nome del file in modo da consentire la visualizzazione di entrambi i file nel file system locale.

Aggiungere il codice seguente alla fine della Program.cs classe:

// 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);

Eliminare un contenitore

Il codice seguente elimina le risorse create dall'app eliminando l'intero contenitore usando DeleteAsync. 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. Si tratta di una valida opportunità per verificare che le risorse siano state effettivamente create correttamente, prima che vengano eliminate.

Aggiungere il codice seguente alla fine della Program.cs classe:

// 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");

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 .NET, passare alla directory dell'applicazione, quindi compilare ed eseguire l'applicazione.

dotnet build
dotnet run

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

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobs60c70d78-8d93-43ae-954d-8322058cfd64/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Listing blobs...
        quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Downloading blob to
        ./data/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31DOWNLOADED.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 che nella cartella data siano presenti due file. È possibile aprirli e verificare che sono identici.

Dopo aver verificato i file, premere INVIO per eliminare i file di test e completare la demo.

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: