Guida introduttiva: libreria client di archiviazione BLOB di Azure V12 per .NETQuickstart: Azure Blob Storage client library v12 for .NET

Introduzione alla libreria client di archiviazione BLOB di Azure V12 per .NET.Get started with the Azure Blob Storage client library v12 for .NET. Archiviazione BLOB di Azure è la soluzione di archiviazione di oggetti Microsoft per il cloud.Azure Blob Storage is Microsoft's object storage solution for the cloud. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.Follow steps to install the package and try out example code for basic tasks. L'archiviazione BLOB è ottimizzata per archiviare enormi quantità di dati non strutturati.Blob storage is optimized for storing massive amounts of unstructured data.

Usare la libreria client V12 di archiviazione BLOB di Azure per .NET per:Use the Azure Blob Storage client library v12 for .NET to:

  • Creare un contenitoreCreate a container
  • Caricare un oggetto BLOB in Archiviazione di AzureUpload a blob to Azure Storage
  • Elencare tutti i BLOB in un contenitoreList all of the blobs in a container
  • Scaricare il BLOB nel computer localeDownload the blob to your local computer
  • Eliminare un contenitoreDelete a container

Risorse aggiuntive:Additional resources:

Nota

Le funzionalità descritte in questo articolo sono ora disponibili per gli account con spazio dei nomi gerarchico.The features described in this article are now available to accounts that have a hierarchical namespace. Per un elenco completo, vedere l'articolo Funzionalità di archiviazione BLOB disponibili in Azure Data Lake Storage Gen2.To review limitations, see the Blob storage features available in Azure Data Lake Storage Gen2 article.

PrerequisitiPrerequisites

ConfigurazioneSetting up

Questa sezione illustra la preparazione di un progetto per l'uso con la libreria client di archiviazione BLOB di Azure V12 per .NET.This section walks you through preparing a project to work with the Azure Blob Storage client library v12 for .NET.

Creare il progettoCreate the project

Creare un'applicazione .NET Core denominata BlobQuickstartV12.Create a .NET Core application named BlobQuickstartV12.

  1. Nella finestra di una console (ad esempio cmd, PowerShell o Bash) usare il comando dotnet new per creare una nuova app console con il nome BlobQuickstartV12.In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name BlobQuickstartV12. Questo comando crea un semplice progetto C# "Hello World" con un singolo file di origine: Program.cs.This command creates a simple "Hello World" C# project with a single source file: Program.cs.

    dotnet new console -n BlobQuickstartV12
    
  2. Passare alla directory BlobQuickstartV12 creata.Switch to the newly created BlobQuickstartV12 directory.

    cd BlobQuickstartV12
    
  3. Nella directory BlobQuickstartV12 creare un'altra directory denominata data.In side the BlobQuickstartV12 directory, create another directory called data. Qui verranno creati e archiviati i file di dati BLOB.This is where the blob data files will be created and stored.

    mkdir data
    

Installare il pacchettoInstall the package

Sempre nella directory dell'applicazione, installare la libreria client di Archiviazione BLOB di Azure per il pacchetto .NET usando il comando dotnet add package.While still in the application directory, install the Azure Blob Storage client library for .NET package by using the dotnet add package command.

dotnet add package Azure.Storage.Blobs

Configurare il framework dell'appSet up the app framework

Dalla directory del progetto:From the project directory:

  1. Aprire il file Program. cs nell'editor.Open the Program.cs file in your editor.

  2. Rimuovere l'istruzione Console.WriteLine("Hello World!"); .Remove the Console.WriteLine("Hello World!"); statement.

  3. Aggiungere using direttive.Add using directives.

  4. Aggiornare la Main dichiarazione di metodo per supportare Async.Update the Main method declaration to support async.

    Ecco il codice:Here's the code:

    using Azure.Storage.Blobs;
    using Azure.Storage.Blobs.Models;
    using System;
    using System.IO;
    using System.Threading.Tasks;
    
    namespace BlobQuickstartV12
    {
        class Program
        {
            static async Task Main()
            {
            }
        }
    }
    

Copiare le credenziali dal portale di AzureCopy your credentials from the Azure portal

Le richieste effettuate dall'applicazione di esempio ad Archiviazione di Azure devono essere autorizzate.When the sample application makes a request to Azure Storage, it must be authorized. Per autorizzare una richiesta, aggiungere all'applicazione le credenziali dell'account di archiviazione sotto forma di stringa di connessione.To authorize a request, add your storage account credentials to the application as a connection string. Visualizzare le credenziali dell'account di archiviazione seguendo questa procedura:View your storage account credentials by following these steps:

  1. Accedere al portale di Azure.Sign in to the Azure portal.

  2. Individuare l'account di archiviazione.Locate your storage account.

  3. Nella sezione Impostazioni della panoramica dell'account di archiviazione selezionare Chiavi di accesso.In the Settings section of the storage account overview, select Access keys. A questo punto è possibile visualizzare le chiavi di accesso dell'account e la stringa di connessione completa per ogni chiave.Here, you can view your account access keys and the complete connection string for each key.

  4. Trovare il valore Stringa di connessione in key1 e selezionare il pulsante Copia per copiare la stringa di connessione.Find the Connection string value under key1, and select the Copy button to copy the connection string. Il valore della stringa di connessione verrà aggiunto a una variabile di ambiente nel passaggio successivo.You will add the connection string value to an environment variable in the next step.

    Screenshot che mostra come copiare una stringa di connessione dal portale di Azure

Configurare la stringa di connessione di archiviazioneConfigure your storage connection string

Dopo aver copiato la stringa di connessione, scriverla in una nuova variabile di ambiente nel computer locale che esegue l'applicazione.After you have copied your connection string, write it to a new environment variable on the local machine running the application. Per impostare la variabile di ambiente, aprire una finestra della console e seguire le istruzioni per il sistema operativo specifico.To set the environment variable, open a console window, and follow the instructions for your operating system. Sostituire <yourconnectionstring> con la stringa di connessione effettiva.Replace <yourconnectionstring> with your actual connection string.

WindowsWindows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Dopo aver aggiunto la variabile di ambiente in Windows, è necessario avviare una nuova istanza della finestra di comando.After you add the environment variable in Windows, you must start a new instance of the command window.

LinuxLinux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOSmacOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Riavviare i programmiRestart programs

Dopo aver aggiunto la variabile di ambiente, riavviare gli eventuali programmi in esecuzione che dovranno leggerla.After you add the environment variable, restart any running programs that will need to read the environment variable. Ad esempio, riavviare l'ambiente di sviluppo o l'editor prima di continuare.For example, restart your development environment or editor before continuing.

Modello a oggettiObject model

Il servizio Archiviazione BLOB di Azure è ottimizzato per archiviare enormi quantità di dati non strutturati.Azure Blob Storage is optimized for storing massive amounts of unstructured data. I dati non strutturati sono dati che non seguono una definizione o un modello di dati specifico, ad esempio dati di testo o binari.Unstructured data is data that does not adhere to a particular data model or definition, such as text or binary data. L’archiviazione BLOB offre tre tipi di risorse:Blob storage offers three types of resources:

  • L'account di archiviazioneThe storage account
  • Un contenitore nell'account di archiviazioneA container in the storage account
  • Un oggetto BLOB in un contenitoreA blob in the container

Il diagramma seguente mostra la relazione tra queste risorse.The following diagram shows the relationship between these resources.

Diagramma dell'architettura dell'archivio BLOB

Per interagire con queste risorse, usare le classi .NET seguenti:Use the following .NET classes to interact with these resources:

  • BlobServiceClient: la classe BlobServiceClient consente di modificare le risorse di Archiviazione di Azure e i contenitori BLOB.BlobServiceClient: The BlobServiceClient class allows you to manipulate Azure Storage resources and blob containers.
  • BlobContainerClient: la classe BlobContainerClient consente di modificare i contenitori di Archiviazione di Azure e i relativi oggetti BLOB.BlobContainerClient: The BlobContainerClient class allows you to manipulate Azure Storage containers and their blobs.
  • BlobClient: la classe BlobClient consente di modificare gli oggetti BLOB di Archiviazione di Azure.BlobClient: The BlobClient class allows you to manipulate Azure Storage blobs.
  • BlobDownloadInfo: la classe BlobDownloadInfo rappresenta le proprietà e il contenuto restituiti dal download di un BLOB.BlobDownloadInfo: The BlobDownloadInfo class represents the properties and content returned from downloading a blob.

Esempi di codiceCode examples

Questi frammenti di codice di esempio illustrano come eseguire le operazioni seguenti con la libreria client di archiviazione BLOB di Azure per .NET:These example code snippets show you how to perform the following with the Azure Blob Storage client library for .NET:

Ottenere la stringa di connessioneGet the connection string

Il codice seguente recupera la stringa di connessione per l'account di archiviazione dalla variabile di ambiente creata nella sezione Configurare la stringa di connessione di archiviazione.The code below retrieves the connection string for the storage account from the environment variable created in the Configure your storage connection string section.

Aggiungere questo codice all'interno del metodo Main:Add this code inside the Main method:

Console.WriteLine("Azure Blob Storage v12 - .NET quickstart sample\n");

// 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. If the
// environment variable is created after the application is launched in a
// console or with Visual Studio, the shell or application needs to be closed
// and reloaded to take the environment variable into account.
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

Creare un contenitoreCreate a container

Decidere un nome per il nuovo contenitore.Decide on a name for the new container. Il codice seguente aggiunge un valore GUID al nome del contenitore per garantirne l'univocità.The code below appends a GUID value to the container name to ensure that it is unique.

Importante

I nomi dei contenitori devono essere in minuscolo.Container names must be lowercase. 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).For more information about naming containers and blobs, see Naming and Referencing Containers, Blobs, and Metadata.

Creare un'istanza della classe BlobServiceClient.Create an instance of the BlobServiceClient class. Chiamare quindi il metodo CreateBlobContainerAsync per creare il contenitore nell'account di archiviazione.Then, call the CreateBlobContainerAsync method to create the container in your storage account.

Aggiungere questo codice alla fine del metodo Main:Add this code to the end of the Main method:

// Create a BlobServiceClient object which will be used to create a container client
BlobServiceClient blobServiceClient = new BlobServiceClient(connectionString);

//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 BLOB in un contenitoreUpload blobs to a container

Il frammento di codice seguente consente di:The following code snippet:

  1. Creare un file di testo nella directory data locale.Creates a text file in the local data directory.
  2. Ottenere un riferimento a un oggetto BlobClient chiamando il metodo GetBlobClient sul contenitore dalla sezione Creare un contenitore.Gets a reference to a BlobClient object by calling the GetBlobClient method on the container from the Create a container section.
  3. Caricare il file di testo locale nel BLOB chiamando il metodo UploadAsync.Uploads the local text file to the blob by calling the UploadAsync method. Questo metodo crea il BLOB se non esiste o lo sovrascrive se esiste già.This method creates the blob if it doesn't already exist, and overwrites it if it does.

Aggiungere questo codice alla fine del metodo Main:Add this code to the end of the Main method:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "./data/";
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);

// Open the file and upload its data
using FileStream uploadFileStream = File.OpenRead(localFilePath);
await blobClient.UploadAsync(uploadFileStream, true);
uploadFileStream.Close();

Elencare i BLOB in un contenitoreList the blobs in a container

Elencare i BLOB nel contenitore chiamando il metodo GetBlobsAsync.List the blobs in the container by calling the GetBlobsAsync method. In questo caso, al contenitore è stato aggiunto un unico BLOB, quindi l'operazione di recupero dell'elenco restituisce solo tale BLOB.In this case, only one blob has been added to the container, so the listing operation returns just that one blob.

Aggiungere questo codice alla fine del metodo Main:Add this code to the end of the Main method:

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

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

Scaricare BLOBDownload blobs

Scaricare il BLOB creato in precedenza chiamando il metodo DownloadAsync.Download the previously created blob by calling the DownloadAsync method. 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.The example code adds a suffix of "DOWNLOADED" to the file name so that you can see both files in local file system.

Aggiungere questo codice alla fine del metodo Main:Add this code to the end of the Main method:

// 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
BlobDownloadInfo download = await blobClient.DownloadAsync();

using (FileStream downloadFileStream = File.OpenWrite(downloadFilePath))
{
    await download.Content.CopyToAsync(downloadFileStream);
    downloadFileStream.Close();
}

Eliminare un contenitoreDelete a container

Il codice seguente elimina le risorse create dall'app eliminando l'intero contenitore usando DeleteAsync.The following code cleans up the resources the app created by deleting the entire container by using DeleteAsync. Elimina anche i file locali creati dall'app.It also deletes the local files created by the app.

L'app viene sospesa per l'input dell'utente chiamando Console.ReadLine prima dell'eliminazione di BLOB, contenitore e file locali.The app pauses for user input by calling Console.ReadLine before it deletes the blob, container, and local files. Si tratta di una valida opportunità per verificare che le risorse siano state effettivamente create correttamente, prima che vengano eliminate.This is a good chance to verify that the resources were actually created correctly, before they are deleted.

Aggiungere questo codice alla fine del metodo Main:Add this code to the end of the Main method:

// 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 codiceRun the code

Questa app crea un file di test nella cartella data locale e lo carica nell'archiviazione BLOB.This app creates a test file in your local data folder and uploads it to Blob storage. 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.The example then lists the blobs in the container and downloads the file with a new name so that you can compare the old and new files.

Passare alla directory dell'applicazione, quindi compilarla ed eseguirla.Navigate to your application directory, then build and run the application.

dotnet build
dotnet run

L'output dell'app è simile all'esempio seguente:The output of the app is similar to the following example:

Azure Blob Storage v12 - .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.Before you begin the clean up process, check your data folder for the two files. È possibile aprirli e verificare che sono identici.You can open them and observe that they are identical.

Dopo aver verificato i file, premere INVIO per eliminare i file di test e completare la demo.After you've verified the files, press the Enter key to delete the test files and finish the demo.

Passaggi successiviNext steps

In questa guida introduttiva si è appreso come caricare, scaricare ed elencare i BLOB con .NET.In this quickstart, you learned how to upload, download, and list blobs using .NET.

Per visualizzare le app di esempio di Archiviazione BLOB, procedere con:To see Blob storage sample apps, continue to: