練習 - 設定及初始化用戶端程式庫

10 分鐘

使用 Azure Blob 儲存體的應用程式，其一般工作流程如下所示：

擷取設定：啟動時，會載入儲存體帳戶設定，通常是儲存體帳戶連接字串。
將用戶端初始化：使用連接字串將 Azure 儲存體用戶端程式庫初始化。此初始化會建立應用程式用來搭配 Blob 儲存體 API 運作的物件。
使用：若要在容器與 Blob 上操作，請藉由使用用戶端程式庫進行 API 呼叫。

設定您的連接字串

在執行您的應用程式之前，取得要使用的儲存體帳戶連接字串。您可以使用任何 Azure 管理介面 (包括 Azure 入口網站、Azure CLI 和 Azure PowerShell) 取得。當您在本課程模組結尾設定 Web 應用程式以執行程式碼時，使用 Azure CLI 取得您稍早所建立儲存體帳戶的連接字串。

儲存體帳戶連接字串包含帳戶金鑰。請將帳戶金鑰視為祕密，並一律安全地儲存。在此，您會將連接字串儲存於 App Service 應用程式設定中。 App Service 應用程式設定是應用程式祕密的安全位置。此設計不支援本機開發，而且本身不是強固的端對端解決方案。

重要

此程式碼範例會使用連接字串來授權存取儲存體帳戶。此組態是作為範例用途。在應用程式程式碼中應謹慎使用連接字串和帳戶存取金鑰。如果帳戶存取金鑰遺失或意外放在不安全的地方，您的服務可能變得易受攻擊。任何擁有存取金鑰的人都可以授權執行目標為儲存體帳戶的要求，而且可實質存取所有資料。

為了實現最佳安全性，Microsoft 建議盡可能使用具有受控識別的 Microsoft Entra ID 來授權對於 Blob、佇列和資料表資料的請求。若要深入瞭解，請參閱使用 Microsoft Entra ID 授權存取 Blob。

初始化 Blob 儲存體物件模型

在 Azure Storage SDK for .NET 中，使用 Blob 儲存體的標準模式如下所示：

將新的 BlobServiceClient 物件具現化，並將連接字串提供給儲存體帳戶。
若要取得 BlobContainerClient，請使用您想要與其互動或加以建立的容器名稱來呼叫 BlobServiceClient 上的 GetBlobContainerClient。

在程式碼中，這些步驟如下所示。

BlobServiceClient blobServiceClient = new BlobServiceClient(storageConfig.ConnectionString);
BlobContainerClient containerClient = blobServiceClient.GetBlobContainerClient(storageConfig.FileContainerName);

此初始化程式碼不會透過網路進行呼叫。這個事實表示因為錯誤資訊而發生的一些例外狀況不會立即擲回。例如，若將格式不正確的連接字串提供給 BlobServiceClient 類別的建構函式，則會立即擲回例外狀況。然而，若連接字串指向不存在的儲存體帳戶，則在您嘗試對儲存體帳戶執行作業之前，將不會擲回任何例外狀況。

在 Azure Storage SDK for Java 中，使用 Blob 儲存體的標準模式包含下列步驟：

藉由使用您儲存體帳戶的連接字串將新 BlobServiceClientBuilder 物件具現化，以建置 BlobServiceClient。
藉由使用您想要與其互動或加以建立的容器名稱呼叫 BlobServiceClient 上的 getBlobContainerClient，以取得 BlobContainerClient。

在程式碼中，這些步驟如下所示。

BlobServiceClient blobServiceClient = BlobServiceClientBuilder()
    .connectionString(connectionString)
    .buildClient();
BlobContainerClient containerClient = blobServiceClient.getBlobContainerClient(containerName);

此初始化程式碼不會透過網路進行呼叫。這個事實表示因為錯誤資訊而發生的一些例外狀況不會立即擲回。例如，若將格式不正確的連接字串提供給 BlobServiceClientBuilder，則會立即擲回例外狀況。然而，若連接字串指向不存在的儲存體帳戶，則在您嘗試對儲存體帳戶執行作業之前，將不會擲回任何例外狀況。

在啟動時建立容器

若要在啟動應用程式或應用程式第一次嘗試使用容器時建立容器，請在 BlobContainerClient 上呼叫 CreateIfNotExistsAsync。

若容器已存在，但不會對 Azure Blob 儲存體執行網路呼叫，則 CreateIfNotExistsAsync 不會擲回例外狀況。在初始化期間呼叫它一次，不是每次嘗試使用容器時呼叫。

若要在啟動應用程式或應用程式第一次嘗試使用容器時建立容器，請在 BlobContainerClient 上呼叫 exists 來檢查容器是否存在。如果不存在，則呼叫 create。在初始化期間呼叫它一次，不是每次嘗試使用容器時呼叫。

練習

複製並探索未完成的應用程式

首先，從 GitHub 複製啟始應用程式。若要取得原始程式碼的複本並在編輯器中加以開啟，請在 Azure Shell CLI 中執行下列命令：
```
git clone https://github.com/MicrosoftDocs/mslearn-store-data-in-azure.git
cd mslearn-store-data-in-azure/store-app-data-with-azure-blob-storage/src/start
code .
```
在編輯器中開啟 Controllers/FilesController.cs 檔案。雖然這裡沒有要做的工作，但我們會迅速瀏覽一下應用程式在做什麼。

此控制器會透過三個動作來實作 API：
- 索引：(GET /api/Files) 會傳回 URL 清單，每個 URL 各代表一個已上傳的檔案。應用程式前端會呼叫此方法，來建置已上傳檔案的超連結清單。
- 上傳：(POST /api/Files) 會接收並儲存已上傳的檔案。
- 下載：(GET /api/Files/{filename}) 依其名稱下載個別檔案。
為了執行其工作，每個方法都會使用稱為 storage 的 IStorage 執行個體。您要填入的 Models/BlobStorage.cs 中，有未完成的 IStorage 實作。

新增 NuGet 套件

新增 Azure 儲存體 SDK 的參考。在 Azure Shell CLI 中執行下列命令：
```
dotnet add package Azure.Storage.Blobs
dotnet restore
```
此命令可確保您正在使用最新版的 Blob 儲存體用戶端程式庫。

設定

您需要的設定值，是應用程式儲存檔案時使用的儲存體帳戶連接字串和容器名稱。在本課程模組中，您只會在 Azure App Service 中執行應用程式。請遵循 App Service 最佳做法，並將值儲存在 App Service 應用程式設定中。當您建立 App Service 執行個體時，即會執行此動作。您目前不需要執行任何動作。

使用設定時，啟始應用程式會包含所需的設定連接。 BlobStorage 中的 IOptions<AzureStorageConfig> 建構函式參數具有兩個屬性：儲存體帳戶連接字串，以及您的應用程式儲存 Blob 時使用的容器名稱。 Startup.cs 的 ConfigureServices 方法中有程式碼，可在應用程式啟動時從設定載入值。

Initialize

在編輯器中開啟 Models/BlobStorage.cs。將下列 using 陳述式新增至檔案頂端，為您要新增的程式碼備妥。
```
using Azure;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
```
尋找 Initialize 方法。您的應用程式第一次使用 BlobStorage 時會呼叫此方法。如果您想知道，您可以在 Startup.cs 中檢視 ConfigureServices 以了解呼叫如何完成。

Initialize 是您想要建立容器的位置 (如果容器尚未存在)。以下列程式碼取代目前的 Initialize 實作，並使用 CTRL+S 儲存您的工作。
```
public Task Initialize()
{
    BlobServiceClient blobServiceClient = new BlobServiceClient(storageConfig.ConnectionString);
    BlobContainerClient containerClient = blobServiceClient.GetBlobContainerClient(storageConfig.FileContainerName);
    return containerClient.CreateIfNotExistsAsync();
}
```

複製並探索未完成的應用程式

首先，從 GitHub 複製啟始應用程式。若要取得原始程式碼的複本並在編輯器中加以開啟，請在 Azure Shell CLI 中執行下列命令：

git clone https://github.com/MicrosoftDocs/mslearn-store-data-in-azure.git
cd mslearn-store-data-in-azure/store-java-ee-application-data-with-azure-blob-storage/start
code .

在編輯器中開啟 src/main/java/com/microsoft/azure/samples/jsf/IndexBean.java 檔案。雖然這裡沒有要做的工作，但我們會迅速瀏覽一下應用程式在做什麼。

此要求會限定 Bean 實作下列三個動作的範圍，這些動作由 src/main/webapp/index.xhtml Java Server Faces (JSF) 頁面所使用：
- listFileNames：傳回檔案名稱的清單，每個檔案名稱各代表一個已上傳的檔案。 index.xhtml 頁面會呼叫此方法，以建置已上傳檔案的超連結清單。
- upload：會接收並儲存已上傳的檔案。檔案內容與中繼資料會由 JSF 架構插入 uploadedFile 屬性中。
- download：依其名稱下載個別檔案。
為了執行其工作，每個方法都會使用稱為 storage 的 Storage 執行個體。要填入的 src/main/java/com/microsoft/azure/samples/service/BlobStorage.java 中的 Storage 實作不完整。

新增 Azure Storage SDK for Java 參考

我們建議使用 Azure BOM 將 Azure 用戶端程式庫新增至專案。其使用多個 Azure 用戶端程式庫來提供簡單且簡潔的協調方式，同時確保將相依性衝突降至最低。

在編輯器中開啟 pom.xml 檔案。

若要將 Azure BOM 新增至專案，請在 project XML 標籤下新增下列 dependencyManagement 區段。

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-sdk-bom</artifactId>
      <version>1.0.6</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

若要新增 Azure Storage SDK for Java，請將下列 dependency 新增至 project/dependencies XML 區段。
```
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-blob</artifactId>
</dependency>
```

設定

您需要的設定值，是應用程式儲存檔案時使用的儲存體帳戶連接字串和容器名稱。在本課程模組中，您只會在 Azure App Service 中執行應用程式。請遵循 App Service 最佳做法，並將值儲存在 App Service 應用程式設定中。當我們建立 App Service 執行個體時，即會執行此動作。您目前不需要執行任何動作。

說到「使用」設定時，會將 App Service 應用程式設定傳遞為應用程式程式碼的環境變數。您會在初始化程式碼中加以讀取。

Initialize

在編輯器中開啟 src/main/java/com/microsoft/azure/samples/service/BlobStorage.java。將下列 import 陳述式新增至檔案頂端，為您要新增的程式碼備妥。

import java.util.stream.Collectors;

import com.azure.storage.blob.BlobClient;
import com.azure.storage.blob.BlobContainerClient;
import com.azure.storage.blob.BlobServiceClient;
import com.azure.storage.blob.BlobServiceClientBuilder;
import com.azure.storage.blob.models.BlobItem;

在 BlobStorage 類別中新增類別屬性，以保留 BlobContainerClient 參考。
```
private BlobContainerClient blobContainerClient;
```
提示

Azure 用戶端為無狀態且為安全執行緒。建議在適用的情況下快取其執行個體。例如，您正在使用的應用程式會使用具有常數名稱的單一容器，因此最好在應用程式存留期範圍內加以快取。 BlobStorage 以 @Singleton 加以註解，因此建議將 BlobContainerClient 參考儲存於其欄位中。

找出具有以 @PostConstruct 註解的 init 方法。您的應用程式會在建立 BlobStorage 執行個體之後，以及第一次使用該執行個體之前，呼叫此方法。

init 是建立容器的位置 (如果容器尚未存在)。使用下列程式碼取代目前的 init 實作，並儲存您的工作。

@PostConstruct
private void init() {
    String connectionString = System.getenv("STORAGE_CONNECTION_STRING");
    String containerName = System.getenv("STORAGE_CONTAINER_NAME");
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .connectionString(connectionString)
        .buildClient();
    blobContainerClient = blobServiceClient.getBlobContainerClient(containerName);
    if (!blobContainerClient.exists()) {
        blobContainerClient.create();
    }
}

練習 - 設定及初始化用戶端程式庫

設定您的連接字串

初始化 Blob 儲存體物件模型

在啟動時建立容器

練習

複製並探索未完成的應用程式

新增 NuGet 套件

設定

Initialize

複製並探索未完成的應用程式

新增 Azure Storage SDK for Java 參考

設定

Initialize

意見反應