快速入門: Azure Blob 儲存體適用于 .NET 的用戶端程式庫 v12Quickstart: Azure Blob Storage client library v12 for .NET

開始使用適用于 .NET 的 Azure Blob 儲存體用戶端程式庫 v12。Get started with the Azure Blob Storage client library v12 for .NET. Azure Blob 儲存體是 Microsoft 針對雲端推出的物件儲存體解決方案。Azure Blob Storage is Microsoft's object storage solution for the cloud. 請依照下列步驟來安裝套件,並試用基本工作的範例程式碼。Follow steps to install the package and try out example code for basic tasks. Blob 儲存體經過最佳化,已能妥善儲存大量的非結構化資料。Blob storage is optimized for storing massive amounts of unstructured data.

使用 Azure Blob 儲存體適用于 .NET 的用戶端程式庫 v12:Use the Azure Blob Storage client library v12 for .NET to:

  • 建立容器Create a container
  • 將 Blob 上傳至 Azure 儲存體Upload a blob to Azure Storage
  • 列出容器中的所有 BlobList all of the blobs in a container
  • 將 Blob 下載到本機電腦Download the blob to your local computer
  • 刪除容器Delete a container

其他資源:Additional resources:

注意

本文所述的各項功能現在可供具有階層命名空間的帳戶使用。The features described in this article are now available to accounts that have a hierarchical namespace. 若要檢閱限制,請參閱 Azure Data Lake Storage Gen2 中可用的 Blob 儲存體功能一文。To review limitations, see the Blob storage features available in Azure Data Lake Storage Gen2 article.

必要條件Prerequisites

設定Setting up

本節會引導您準備專案以搭配適用于 .NET 的 Azure Blob 儲存體用戶端程式庫 v12 使用。This section walks you through preparing a project to work with the Azure Blob Storage client library v12 for .NET.

建立專案Create the project

建立一個名為 BlobQuickstartV12 的 .NET Core 應用程式。Create a .NET Core application named BlobQuickstartV12.

  1. 在主控台視窗中 (例如 cmd、PowerShell 或 Bash),使用 dotnet new 命令建立名為 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. 此命令會建立簡單的 "Hello World" C# 專案,內含單一原始程式檔:Program.csThis command creates a simple "Hello World" C# project with a single source file: Program.cs.

    dotnet new console -n BlobQuickstartV12
    
  2. 切換至新建立的 BlobQuickstartV12 目錄。Switch to the newly created BlobQuickstartV12 directory.

    cd BlobQuickstartV12
    
  3. BlobQuickstartV12 目錄內,建立另一個名為 data 的目錄。In side the BlobQuickstartV12 directory, create another directory called data. 這是將建立和儲存 Blob 資料檔案的位置。This is where the blob data files will be created and stored.

    mkdir data
    

安裝套件Install the package

若您仍在應用程式目錄中,請使用 dotnet add package 命令安裝適用於 .NET 套件的 Azure Blob 儲存體用戶端程式庫。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

設定應用程式架構Set up the app framework

從專案目錄:From the project directory:

  1. 在編輯器中開啟 Program.cs 檔案Open the Program.cs file in your editor
  2. 移除 Console.WriteLine("Hello World!"); 陳述式Remove the Console.WriteLine("Hello World!"); statement
  3. 新增 using 指示詞Add using directives
  4. 更新 Main 方法宣告以支援非同步程式碼Update the Main method declaration to support async code

此程式碼如下: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()
        {
        }
    }
}

從 Azure 入口網站複製您的認證Copy your credentials from the Azure portal

當應用程式範例向 Azure 儲存體發出要求時,該要求必須獲得授權。When the sample application makes a request to Azure Storage, it must be authorized. 若要對要求授權,請以連接字串的形式將儲存體帳戶認證新增至應用程式。To authorize a request, add your storage account credentials to the application as a connection string. 請依照下列步驟檢視您的儲存體帳戶認證:View your storage account credentials by following these steps:

  1. 登入 Azure 入口網站Sign in to the Azure portal.

  2. 找出您的儲存體帳戶。Locate your storage account.

  3. 在儲存體帳戶概觀的 [設定] 區段中,選取 [存取金鑰] 。In the Settings section of the storage account overview, select Access keys. 在此處,您可以檢視帳戶存取金鑰,和每個金鑰的完整連接字串。Here, you can view your account access keys and the complete connection string for each key.

  4. 尋找 [金鑰 1] 下方的 [連接字串] 值,然後選取 [複製] 按鈕以複製連接字串。Find the Connection string value under key1, and select the Copy button to copy the connection string. 在下一個步驟中,您會將連接字串值新增至環境變數。You will add the connection string value to an environment variable in the next step.

    顯示如何從 Azure 入口網站複製連接字串的螢幕擷取畫面

設定儲存體連接字串Configure your storage connection string

在複製您的連接字串後,請在執行應用程式的本機電腦上,將該字串寫入至新的環境變數中。After you have copied your connection string, write it to a new environment variable on the local machine running the application. 若要設定環境變數,請開啟主控台視窗,並遵循您的作業系統所適用的指示。To set the environment variable, open a console window, and follow the instructions for your operating system. <yourconnectionstring> 用實際的連接字串取代。Replace <yourconnectionstring> with your actual connection string.

WindowsWindows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

在 Windows 中新增環境變數之後,您必須啟動新的命令視窗執行個體。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>"

重新啟動程式Restart programs

新增環境變數之後,請重新啟動任何需要讀取環境變數的執行中程式。After you add the environment variable, restart any running programs that will need to read the environment variable. 例如,在繼續之前,先重新啟動您的開發環境或編輯器。For example, restart your development environment or editor before continuing.

物件模型Object model

Azure Blob 儲存體經過最佳化,已能妥善儲存大量的非結構化資料。Azure Blob Storage is optimized for storing massive amounts of unstructured data. 非結構化資料是指不遵守特定資料模型或定義的資料,例如文字或二進位資料。Unstructured data is data that does not adhere to a particular data model or definition, such as text or binary data. Blob 儲存體提供三種類型資源:Blob storage offers three types of resources:

  • 儲存體帳戶The storage account
  • 儲存體帳戶中的容器A container in the storage account
  • 容器中的 BlobA blob in the container

下圖顯示資源之間的關係。The following diagram shows the relationship between these resources.

Blob 儲存體架構圖

使用下列 .NET 類別與這些資源互動:Use the following .NET classes to interact with these resources:

  • BlobServiceClientBlobServiceClient 類別可讓您操作 Azure 儲存體資源和 Blob 容器。BlobServiceClient: The BlobServiceClient class allows you to manipulate Azure Storage resources and blob containers.
  • BlobContainerClientBlobContainerClient 類別可讓您操作 Azure 儲存體容器及其 Blob。BlobContainerClient: The BlobContainerClient class allows you to manipulate Azure Storage containers and their blobs.
  • BlobClientBlobClient 類別可讓您操作 Azure 儲存體 Blob。BlobClient: The BlobClient class allows you to manipulate Azure Storage blobs.
  • BlobDownloadInfoBlobDownloadInfo 類別表示從下載 Blob 傳回的屬性和內容。BlobDownloadInfo: The BlobDownloadInfo class represents the properties and content returned from downloading a blob.

程式碼範例Code examples

這些範例程式碼片段會示範如何使用適用于 .NET 的 Azure Blob 儲存體用戶端程式庫執行下列動作:These example code snippets show you how to perform the following with the Azure Blob Storage client library for .NET:

取得連接字串Get the connection string

下列程式碼會從設定儲存體連接字串一節中建立的環境變數,擷取儲存體帳戶的連接字串。The code below retrieves the connection string for the storage account from the environment variable created in the Configure your storage connection string section.

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

建立容器Create a container

決定新容器的名稱。Decide on a name for the new container. 下列程式碼會將 GUID 值附加到容器名稱,以確保它是唯一的。The code below appends a GUID value to the container name to ensure that it is unique.

重要

容器名稱必須是小寫字母。Container names must be lowercase. 如需為容器和 Blob 命名的詳細資訊,請參閱命名和參考容器、Blob 及中繼資料For more information about naming containers and blobs, see Naming and Referencing Containers, Blobs, and Metadata.

建立 BlobServiceClient 類別的執行個體。Create an instance of the BlobServiceClient class. 接著,呼叫 CreateBlobContainerAsync 方法,以便在您的儲存體帳戶中建立容器。Then, call the CreateBlobContainerAsync method to create the container in your storage account.

將此程式碼加入到 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);

將 Blob 上傳至容器Upload blobs to a container

下列程式碼片段:The following code snippet:

  1. 在本機 data 目錄中建立一個文字檔。Creates a text file in the local data directory.
  2. 建立容器一節的容器上呼叫 GetBlobClient 方法,以取得 BlobClient 物件的參考。Gets a reference to a BlobClient object by calling the GetBlobClient method on the container from the Create a container section.
  3. 呼叫 UploadAsync 方法,將本機文字檔上傳至 Blob。Uploads the local text file to the blob by calling the UploadAsync method. 如果 Blob 不存在,此方法會建立 Blob,若已存在,則會加以覆寫。This method creates the blob if it doesn't already exist, and overwrites it if it does.

將此程式碼加入到 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();

列出容器中的 BlobList the blobs in a container

呼叫 GetBlobsAsync 方法,以列出容器中的 Blob。List the blobs in the container by calling the GetBlobsAsync method. 在此案例中,只有一個 Blob 新增至容器,所以清單作業只會傳回一個 Blob。In this case, only one blob has been added to the container, so the listing operation returns just that one blob.

將此程式碼加入到 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);
}

下載 BlobDownload blobs

呼叫 DownloadAsync 方法,以下載先前建立的 Blob。Download the previously created blob by calling the DownloadAsync method. 此範例程式碼會將 "DOWNLOADED" 的尾碼加入至檔案名稱,讓您可以在本機檔案系統中看到這兩個檔案。The example code adds a suffix of "DOWNLOADED" to the file name so that you can see both files in local file system.

將此程式碼加入到 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();
}

刪除容器Delete a container

下列程式碼會使用 DeleteAsync 刪除整個容器,以清除應用程式所建立的資源。The following code cleans up the resources the app created by deleting the entire container by using DeleteAsync. 它也會刪除應用程式所建立的本機檔案。It also deletes the local files created by the app.

應用程式會在刪除 Blob、容器和本機檔案之前呼叫 Console.ReadLine,藉以暫停使用者輸入。The app pauses for user input by calling Console.ReadLine before it deletes the blob, container, and local files. 這是很好的機會,可以在刪除資源之前,先確認實際上已正確地建立這些資源。This is a good chance to verify that the resources were actually created correctly, before they are deleted.

將此程式碼加入到 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");

執行程式碼Run the code

此應用程式會在本機 data 資料夾中建立一個測試檔案,並將其上傳到 Blob 儲存體。This app creates a test file in your local data folder and uploads it to Blob storage. 範例會接著列出容器中的 Blob,並下載具有新名稱的檔案,您便可比較舊檔案和新檔案。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.

瀏覽至您的應用程式目錄,並建置和執行應用程式。Navigate to your application directory, then build and run the application.

dotnet build
dotnet run

應用程式的輸出類似下列範例: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

在開始清除程序之前,請檢查 data 資料夾,找出這兩個檔案。Before you begin the clean up process, check your data folder for the two files. 您可以開啟它們,並觀察它們是否相同。You can open them and observe that they are identical.

確認檔案之後,按 Enter 鍵以刪除測試檔案並完成示範。After you've verified the files, press the Enter key to delete the test files and finish the demo.

後續步驟Next steps

在本快速入門中,您已了解如何使用 .NET 上傳、下載及列出 Blob。In this quickstart, you learned how to upload, download, and list blobs using .NET.

若要查看 Blob 儲存體範例應用程式,請繼續查看:To see Blob storage sample apps, continue to: