使用 Java 建立容器或 Blob 的使用者委派 SAS

• .NET
• Java
• Python

共用存取簽章 (SAS) 可讓您對儲存體帳戶中的容器和 Blob 授與有限的存取權。 當您建立 SAS 時，需要指定其條件約束，包括允許用戶端存取的 Azure 儲存體資源、對這些資源的使用權限，以及 SAS 的有效期限。

每個 SAS 都會以金鑰簽署。 您可以使用下列兩種方式之一簽署 SAS：

• 透過使用 Microsoft Entra 認證建立的金鑰。 使用 Microsoft Entra 認證簽署的 SAS 是一種使用者委派 SAS。 凡建立使用者委派 SAS 的用戶端，都必須被指派包含下列動作的 Azure RBAC 角色：Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey。 若要深入了解，請參閱建立使用者委派 SAS。
• 使用儲存體帳戶金鑰。 服務 SAS 和帳戶 SAS 都使用儲存體帳戶金鑰加以簽署。 凡建立服務 SAS 的用戶端，都必須具備帳戶金鑰的直接存取權，或者被指派 Microsoft.Storage/storageAccounts/listkeys/action 使用權限。 若要深入了解，請參閱建立服務 SAS 或建立帳戶 SAS。

注意

使用者委派 SAS 可以為使用儲存體帳戶金鑰簽署的 SAS 提供絕佳的安全性。 Microsoft 建議盡可能採用使用者委派 SAS。 如需詳細資訊，請參閱使用共用存取簽章 (SAS) 授與資料的有限存取權。

本文說明如何使用 Microsoft Entra 認證，透過適用於 Java 的 Azure 儲存體用戶端程式庫為容器或 Blob 建立使用者委派 SAS。

關於使用者委派 SAS

您可以使用 Microsoft Entra 認證或帳戶金鑰保護存取容器或 Blob 的 SAS 權杖。 使用 Microsoft Entra 認證保護的 SAS 稱為使用者委派 SAS，因為用來簽署 SAS 的 OAuth 2.0 權杖是代表該使用者而要求的。

Microsoft 建議您的安全性最佳做法是盡可能使用 Microsoft Entra 認證，而不是使用帳戶金鑰，因為後者可能更容易遭到盜用。 當您的應用程式設計需要共用存取簽章時，請使用 Microsoft Entra 認證來建立使用者委派 SAS 以獲得較佳的安全性。 如需使用者委派 SAS 的詳細資訊，請參閱建立使用者委派 SAS。

警告

擁有有效 SAS 的任何用戶端在該 SAS 允許的範圍內，可存取儲存體帳戶中的資料。 保護 SAS 防止遭到惡意使用或誤用至關重要。 在散發 SAS 時請謹慎使用，並備妥方案以撤銷遭盜用的 SAS。

如需共用存取簽章的詳細資訊，請參閱使用共用存取簽章 (SAS) 授與 Azure 儲存體資源的有限存取權。

指派存取資料的 Azure 角色

當 Microsoft Entra 安全性主體嘗試存取資料時，該安全性主體必須具有該資源的權限。 無論安全性主體是 Azure 中的受控識別，或是在開發環境中執行程式碼的 Microsoft Entra 使用者帳戶，都必須為安全性主體指派授與資料存取權的 Azure 角色。 如需透過 Azure RBAC 指派權限的相關資訊，請參閱指派 Azure 角色以存取 Blob 資料。

設定您的專案

若要使用本文中的程式碼範例，請新增下列 import 指示詞：

import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.sas.*;

取得已驗證的權杖認證

若要取得程式碼可用來授權 Blob 儲存體要求的權杖認證，請建立 DefaultAzureCredential 類別的執行個體。 如需使用 Default AzureCredential 類別來授權受控識別以存取 Blob 儲存體的詳細資訊，請參閱適用於 JAVA 的 Azure 身分識別用戶端程式庫。

下列程式碼片段說明如何取得已驗證的權杖認證，並用其建立 Blob 儲存體的服務用戶端：

BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

若要深入了解如何使用 JAVA SDK 從您的應用程式授權存取 Blob 儲存體，請參閱使用 JAVA 和 Azure 身分識別進行 Azure 驗證。

取得使用者委派金鑰

每個 SAS 都會以金鑰簽署。 若要建立使用者委派 SAS，您必須先要求使用者委派金鑰，然後使用該金鑰來簽署 SAS。 使用者委派金鑰類似用來簽署服務 SAS 或帳戶 SAS 的帳戶金鑰，不同之處在於其依賴您的 Microsoft Entra 認證。 當用戶端使用 OAuth 2.0 權杖要求使用者委派金鑰時，Blob 儲存體會代表使用者傳回使用者委派金鑰。

擁有使用者委派金鑰之後，您就可以使用該金鑰，在金鑰存留期內建立任意數量的使用者委派共用存取簽章。 使用者委派金鑰與用來取得該金鑰的 OAuth 2.0 權杖無關，因此只要金鑰仍有效，就不需要更新權杖。 您可以指定金鑰維持有效的時間長度，最多七天。

您可以使用下列其中一種方法來要求使用者委派金鑰：

• getUserDelegationKey

下列程式碼範例說明如何要求使用者委派金鑰：

public UserDelegationKey requestUserDelegationKey(BlobServiceClient blobServiceClient) {
    // Request a user delegation key that's valid for 1 day, as an example
    UserDelegationKey userDelegationKey = blobServiceClient.getUserDelegationKey(
        OffsetDateTime.now().minusMinutes(5),
        OffsetDateTime.now().plusDays(1));

    return userDelegationKey;
}

建立使用者委派 SAS

您可以根據應用程式的需求，為容器或 Blob 建立使用者委派 SAS。

容器

取得使用者委派金鑰之後，即可建立使用者委派 SAS。 您可以使用 BlobContainerClient 執行個體中的下列方法來建立使用者委派 SAS，以委派對容器資源的有限存取權：

• generateUserDelegationSas

用來簽署 SAS 的使用者委派金鑰會連同 BlobServiceSasSignatureValues 的指定值一起傳遞至此方法。 權限會指定為 BlobContainerSasPermission 執行個體。

下列程式碼範例示範如何建立用於存取容器的使用者委派 SAS：

public String createUserDelegationSASContainer(BlobContainerClient containerClient, UserDelegationKey userDelegationKey) {
    // Create a SAS token that's valid for 1 day, as an example
    OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);

    // Assign read permissions to the SAS token
    BlobContainerSasPermission sasPermission = new BlobContainerSasPermission()
            .setReadPermission(true);

    BlobServiceSasSignatureValues sasSignatureValues = new BlobServiceSasSignatureValues(expiryTime, sasPermission)
            .setStartTime(OffsetDateTime.now().minusMinutes(5));

    String sasToken = containerClient.generateUserDelegationSas(sasSignatureValues, userDelegationKey);
    return sasToken;
}

Blob

取得使用者委派金鑰之後，即可建立使用者委派 SAS。 您可以使用 BlobClient 執行個體中的下列方法來建立使用者委派 SAS，以委派對 Blob 的有限存取權：

• generateUserDelegationSas

用來簽署 SAS 的使用者委派金鑰會連同 BlobServiceSasSignatureValues 的指定值一起傳遞至此方法。 權限會指定為 BlobSasPermission 執行個體。

下列程式碼範例示範如何建立 Blob 的使用者委派 SAS：

public String createUserDelegationSASBlob(BlobClient blobClient, UserDelegationKey userDelegationKey) {
    // Create a SAS token that's valid for 1 day, as an example
    OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);

    // Assign read permissions to the SAS token
    BlobSasPermission sasPermission = new BlobSasPermission()
            .setReadPermission(true);

    BlobServiceSasSignatureValues sasSignatureValues = new BlobServiceSasSignatureValues(expiryTime, sasPermission)
            .setStartTime(OffsetDateTime.now().minusMinutes(5));

    String sasToken = blobClient.generateUserDelegationSas(sasSignatureValues, userDelegationKey);
    return sasToken;
}

使用使用者委派 SAS 來授權用戶端物件

您可以使用使用者委派 SAS 來授權用戶端物件根據 SAS 授與的權限，在容器或 Blob 上執行作業。

容器

下列程式碼範例示範如何使用先前範例中所建立的使用者委派 SAS 來授權 BlobContainerClient 物件。 此用戶端物件可用來根據 SAS 授與的權限以在容器資源上執行作業。

// Create a SAS token for a container
BlobContainerClient containerClient = blobServiceClient.getBlobContainerClient("sample-container");
String sasToken = createUserDelegationSASContainer(containerClient, userDelegationKey);

// Create a new BlobContainerClient using the SAS token
BlobContainerClient sasContainerClient = new BlobContainerClientBuilder()
        .endpoint(containerClient.getBlobContainerUrl())
        .sasToken(sasToken)
        .buildClient();

Blob

下列程式碼範例示範如何使用先前範例中所建立的使用者委派 SAS 來授權 BlobClient 物件。 此用戶端物件可用來根據 SAS 授與的權限，在 Blob 資源上執行作業。

// Create a SAS token for a blob
BlobClient blobClient = blobServiceClient
        .getBlobContainerClient("sample-container")
        .getBlobClient("sample-blob.txt");
String sasToken = createUserDelegationSASBlob(blobClient, userDelegationKey);

// Create a new BlobClient using the SAS token
BlobClient sasBlobClient = new BlobClientBuilder()
        .endpoint(blobClient.getBlobUrl())
        .sasToken(sasToken)
        .buildClient();

資源

若要深入了解使用適用於 JAVA 的 Azure Blob 儲存體用戶端程式庫建立使用者委派 SAS，請參閱下列資源。

程式碼範例

• 檢視本文中的程式碼範例 (GitHub) (英文)

REST API 操作

適用於 JAVA 的 Azure SDK 包含建置在 Azure REST API 上的程式庫，可讓您透過熟悉的 JAVA 範例與 REST API 作業進行互動。 取得使用者委派金鑰的用戶端程式庫方法會使用下列 REST API 作業：

• 取得使用者委派金鑰 (REST API)

用戶端程式庫資源

• 用戶端程式庫參考文件
• 用戶端程式庫原始程式碼
• 套件 (Maven) \(英文\)

另請參閱

• 使用共用存取簽章 (SAS) 對 Azure 儲存體資源授與有限存取權
• 建立使用者委派 SAS

相關內容

• 本文是適用於 JAVA 的 Blob 儲存體開發人員指南的一部分。 若要深入了解，請參閱位於建置 JAVA 應用程式 (部分機器翻譯) 的開發人員指南文章完整清單。