開始使用 Azure Blob 儲存體和 Java

發行項
10/22/2024

本文說明如何使用適用於 Java 的 Azure Blob 儲存體用戶端程式庫來連線至 Azure Blob 儲存體。線上之後，請使用開發人員指南來瞭解如何在 Blob 記憶體服務的容器、Blob 和功能上運作程式碼。

如果您想要從完整的範例開始，請參閱快速入門：Azure Blob 儲存體 Java 用戶端連結庫。

API 參考 | 套件 (Maven) | 程式庫原始程式碼 | 範例 | 提供意見反應

必要條件

Azure 訂用帳戶 - 建立免費帳戶
Azure 儲存體帳戶 - 建立儲存體帳戶
Java 開發套件 (JDK) 8 版或更新版本
在此範例中，Apache Maven 用於專案管理

設定您的專案

注意

本文使用 Maven 建置工具來建置和執行範例程式碼。 Gradle 等其他建置工具也能與適用於 Java 的 Azure SDK 搭配運作。

使用 Maven 建立新的控制台應用程式，或開啟現有的專案。請遵循下列步驟來安裝套件並新增必要的 import 指示詞。

安裝套件

在文字編輯器中開啟 pom.xml 檔案。包含 BOM 檔案或包含直接相依性以安裝套件。

包含 BOM 檔案

新增 azure-sdk-bom，以相依於最新版本的程式庫。在下列程式碼片段中，將 {bom_version_to_target} 預留位置取代為版本號碼。使用 azure-sdk-bom 可讓您不必指定每個個別相依性的版本。若要深入了解 BOM，請參閱 Azure SDK BOM 讀我檔案 (英文)。

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

將下列相依性元素新增至相依性群組。需要 azure-identity 相依性才能對 Azure 服務進行無密碼連線。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
</dependency>
<dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-storage-common</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

包含直接相依性

若要相依於特定版本的程式庫，請將直接相依性新增至您的專案：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>{package_version_to_target}</version>
</dependency>
<dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-storage-common</artifactId>
      <version>{package_version_to_target}</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>{package_version_to_target}</version>
</dependency>

包含匯入指示詞

然後開啟您的程式碼檔案並新增必要的 import 指示詞。在此範例中，我們會在 App.java 檔案中新增下列指示詞：

import com.azure.core.credential.*;
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.specialized.*;
import com.azure.storage.common.*;

Blob 用戶端程式庫資訊:

com.azure.storage.blob：包含可用來在服務、容器和 Blob 上操作的主要類別 (用戶端物件)。
com.azure.storage.blob.models：包含公用程式類別、結構和列舉型別。
com.azure.storage.blob.specialized：包含可用於執行 Blob 類型特有作業的類別 (例如：附加 Blob)。

授權存取權並連線到 Blob 儲存體

若要將應用程式連線至 Blob 儲存體，請建立 BlobServiceClient 類別的執行個體。您也可以使用 BlobServiceAsyncClient 類別進行非同步程式設計。此物件是您與儲存體帳戶層級的資料資源互動的起點。您可以使用它來操作儲存體帳戶及其容器。您也可以使用服務用戶端來建立容器用戶端或 Blob 用戶端，視您需要使用的資源而定。

若要深入了解如何建立及管理用戶端物件，請參閱建立和管理與資料資源互動的用戶端端物件 (部分機器翻譯)。

您可以使用 Microsoft Entra 授權權杖、帳戶存取密鑰或共用存取簽章 (SAS) 來授權 BlobServiceClient 物件。為了實現最佳安全性，Microsoft 建議使用具有受控識別的 Microsoft Entra ID 來授權針對 Blob 資料的要求。如需更多資訊，請參閱使用 Microsoft Entra ID 授與 Blob 的存取權。

若要使用 Microsoft Entra ID 進行授權，您必須使用安全性主體。需要何種安全性主體取決於應用程式的執行位置。參考下表：

應用程式的執行位置	安全性主體	指引
本機電腦 (開發和測試)	服務主體	若要了解如何註冊應用程式、設定 Microsoft Entra 群組、指派角色及設定環境變數，請參閱使用開發人員服務主體授權存取。
本機電腦 (開發和測試)	使用者身分識別	若要了解如何設定 Microsoft Entra 群組、指派角色並登入 Azure，請參閱使用開發人員認證授權存取。
裝載於 Azure 中	受控識別	若要了解如何啟用受控識別並指派角色，請參閱使用受控識別從 Azure 裝載的應用程式授權存取。
裝載在 Azure 外部 (例如內部部署應用程式)	服務主體	若要了解如何註冊應用程式、指派角色及設定環境變數，請參閱使用應用程式服務主體從内部部署應用程式授權存取

使用 DefaultAzureCredential 授權存取

授權存取權並連線到 Blob 儲存體簡單又安全的方式，是藉由建立 DefaultAzureCredential 執行個體來取得 OAuth 權杖。然後，您可以使用該認證來建立 BlobServiceClient 物件。

請確定您在 pom.xml 中有正確的相依性以及必要的匯入指示詞，如設定專案中所述。

下列範例會使用 BlobServiceClientBuilder，使用 DefaultAzureCredential 建置 BlobServiceClient 物件，並視需要示範如何建立容器和 Blob 用戶端：

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

使用 BlobServiceClientBuilder，建置使用 SAS 權杖的 BlobServiceClient 物件：

public static BlobServiceClient GetBlobServiceClientSAS(String sasToken) {
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .sasToken(sasToken)
            .buildClient();

    return blobServiceClient;
}

若要深入了解如何產生和管理 SAS 權杖，請參閱下列文章:

注意

針對使用共用存取簽章 (SAS) 的案例，Microsoft 建議使用使用者委派 SAS。使用者委派 SAS 會使用 Microsoft Entra 認證來保護，而不是使用帳戶金鑰。

使用儲存體帳戶名稱和帳戶金鑰來建立 StorageSharedKeyCredential。然後，使用該物件來初始化 BlobServiceClient 物件。

public static BlobServiceClient GetBlobServiceClientAccountKey(String accountName, String accountKey) {
    StorageSharedKeyCredential credential = new StorageSharedKeyCredential(accountName, accountKey);

    // Azure SDK client builders accept the credential as a parameter
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint(String.format("https://%s.blob.core.windows.net/", accountName))
            .credential(credential)
            .buildClient();

    return blobServiceClient;        
}

您也可以使用連接字串來建立 BlobServiceClient 物件。

public static BlobServiceClient GetBlobServiceClientConnectionString(String connectionString) {
    // Azure SDK client builders accept the credential as a parameter
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .connectionString(connectionString)
            .buildClient();

    return blobServiceClient;        
}

關於如何取得帳戶金鑰及正確管理和保護金鑰的最佳做法指導方針，如需相關資訊，請參閱管理儲存體帳戶存取金鑰。

重要

應該謹慎使用帳戶存取金鑰。如果帳戶存取金鑰遺失或意外放在不安全的地方，您的服務可能變得易受攻擊。任何擁有存取金鑰的人都可以授權執行目標為儲存體帳戶的要求，而且可實質存取所有資料。 DefaultAzureCredential 會提供增強的安全性功能和權益，建議用來管理對 Azure 服務的授權。

設定 DNS 名稱查閱的 JVM TTL

Java 虛擬機（JVM）會快取來自成功 DNS 名稱查閱的回應，在指定的一段時間內，稱為存留時間（TTL）。許多 JVM -1的預設 TTL 值為，這表示 JVM 會無限期地快取回應，或直到 JVM 重新啟動為止。

因為 Azure 資源使用可以變更的 DNS 名稱項目，建議您將 JVM TTL 值設定為 10 秒。此組態可確保資源的更新IP位址會隨著下一個 DNS 查詢傳回。

若要使用 JVM 全域變更所有應用程式的 TTL 值，請在檔案中java.security設定 networkaddress.cache.ttl 屬性。

networkaddress.cache.ttl=10

針對 Java 8，檔案 java.security 位於 $JAVA_HOME/jre/lib/security 目錄中。針對 Java 11 和更新版本，檔案位於 $JAVA_HOME/conf/security 目錄中。

建置應用程式

當您建置應用程式以在 Azure Blob 儲存體中使用資料資源時，您的程式碼主要會與三種資源類型互動：儲存體帳戶、容器和 Blob。若要深入了解這些資源類型、彼此的關係，以及應用程式如何與資源互動，請參閱了解應用程式如何與 Blob 儲存體資料資源互動。

下列指南會示範如何存取資料，並使用適用於 JAVA 的 Azure 儲存體用戶端程式庫來執行特定動作：

指南	描述
設定重試原則 (部分機器翻譯)	實作用戶端作業的重試原則。
複製 Blob	將 Blob 從一個位置複製到另一個位置。
建立容器	建立 Blob 容器
建立使用者委派 SAS	建立容器或 Blob 的使用者委派 SAS。
建立和管理 blob 租用	建立和管理 Blob 上的鎖定。
建立和管理容器租用	在容器上建立和管理鎖定。
刪除和還原 Blob	刪除 Blob 和 (如果已啟用虛刪除) 還原已刪除的 Blob。
刪除和還原容器	刪除容器和 (如果已啟用虛刪除) 還原已刪除的容器。
下載 Blob	使用字串、串流和檔案路徑來下載 Blob。
使用標籤來尋找 Blob	設定和擷取標籤，以及使用標籤來尋找 Blob。
列出 Blob	以各種方式列出 Blob。
列出容器	列出帳戶中的容器，以及可用來自訂清單的各種選項。
管理屬性和中繼資料 (Blob)	取得和設定 Blob 的屬性和中繼資料。
管理屬性和中繼資料 (容器)	取得和設定容器的屬性和中繼資料。
資料傳輸的效能微調	最佳化資料傳輸作業的效能。
設定或變更 Blob 的存取層	設定及變更區塊 Blob 的存取層。
上傳 Blob	了解如何使用字串、串流、檔案路徑和其他方法來上傳 Blob。

共用方式為