使用 .NET 建立容器或 Blob 的服務 SAS

發行項
10/16/2024

共用存取簽章 (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) 授與資料的有限存取權。

本文說明如何使用儲存體帳戶金鑰，搭配適用於 .NET 的 Azure Blob 儲存體用戶端程式庫，建立容器或 blob 的服務 SAS。

關於服務 SAS

服務 SAS 會使用帳戶存取金鑰加以簽署。您可以使用 StorageSharedKeyCredential 類別，建立用來簽署服務 SAS 的認證。

您也可以使用預存的存取原則來定義 SAS 的權限和持續時間。如果提供現有預存存取原則的名稱，該原則將與 SAS 相關聯。若要深入了解預存存取原則，請參閱定義預存存取原則。如果未提供任何預存存取原則，本文中的程式碼範例會示範如何定義 SAS 的權限和持續時間。

建立服務 SAS

您可以根據應用程式的需求，為容器或 Blob 建立服務 SAS。

容器
Blob

下列程式碼範例會示範如何建立容器資源的服務 SAS。首先，程式碼會藉由檢查 CanGenerateSasUri 屬性來驗證 BlobContainerClient 物件是否已獲得共用金鑰認證授權。然後，會透過 BlobSasBuilder 類別產生服務 SAS，並呼叫 GenerateSasUri，以根據用戶端和建立器物件來建立服務 SAS URI。

public static async Task<Uri> CreateServiceSASContainer(
    BlobContainerClient containerClient,
    string storedPolicyName = null)
{
    // Check if BlobContainerClient object has been authorized with Shared Key
    if (containerClient.CanGenerateSasUri)
    {
        // Create a SAS token that's valid for one day
        BlobSasBuilder sasBuilder = new BlobSasBuilder()
        {
            BlobContainerName = containerClient.Name,
            Resource = "c"
        };

        if (storedPolicyName == null)
        {
            sasBuilder.ExpiresOn = DateTimeOffset.UtcNow.AddDays(1);
            sasBuilder.SetPermissions(BlobContainerSasPermissions.Read);
        }
        else
        {
            sasBuilder.Identifier = storedPolicyName;
        }

        Uri sasURI = containerClient.GenerateSasUri(sasBuilder);

        return sasURI;
    }
    else
    {
        // Client object is not authorized via Shared Key
        return null;
    }
}

下列程式碼範例顯示如何建立 blob 資源的服務 SAS。首先，程式碼會藉由檢查 CanGenerateSasUri 屬性來驗證 BlobClient 物件是否已獲得共用金鑰認證授權。然後，會透過 BlobSasBuilder 類別產生服務 SAS，並呼叫 GenerateSasUri，以根據用戶端和產生器物件建立服務 SAS URI。

public static async Task<Uri> CreateServiceSASBlob(
    BlobClient blobClient,
    string storedPolicyName = null)
{
    // Check if BlobContainerClient object has been authorized with Shared Key
    if (blobClient.CanGenerateSasUri)
    {
        // Create a SAS token that's valid for one day
        BlobSasBuilder sasBuilder = new BlobSasBuilder()
        {
            BlobContainerName = blobClient.GetParentBlobContainerClient().Name,
            BlobName = blobClient.Name,
            Resource = "b"
        };

        if (storedPolicyName == null)
        {
            sasBuilder.ExpiresOn = DateTimeOffset.UtcNow.AddDays(1);
            sasBuilder.SetPermissions(BlobContainerSasPermissions.Read);
        }
        else
        {
            sasBuilder.Identifier = storedPolicyName;
        }

        Uri sasURI = blobClient.GenerateSasUri(sasBuilder);

        return sasURI;
    }
    else
    {
        // Client object is not authorized via Shared Key
        return null;
    }
}

使用服務 SAS 來授權用戶端物件

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

容器
Blob

下列程式碼範例示範如何使用服務 SAS 來授權 BlobContainerClient 物件。此用戶端物件可依據 SAS 授與的權限，用於在容器資源上執行作業。

首先，建立以帳戶存取金鑰簽署的 BlobServiceClient 物件：

string accountName = "<storage-account-name>";
string accountKey = "<storage-account-key";
StorageSharedKeyCredential storageSharedKeyCredential =
    new(accountName, accountKey);
BlobServiceClient blobServiceClient = new BlobServiceClient(
    new Uri($"https://{accountName}.blob.core.windows.net"),
    storageSharedKeyCredential);

然後，如同先前範例所示產生服務 SAS，並使用 SAS 來授權 BlobContainerClient 物件：

// Create a Uri object with a service SAS appended
BlobContainerClient containerClient = blobServiceClient
    .GetBlobContainerClient("sample-container");
Uri containerSASURI = await CreateServiceSASContainer(containerClient);

// Create a container client object representing 'sample-container' with SAS authorization
BlobContainerClient containerClientSAS = new BlobContainerClient(containerSASURI);

下列程式碼範例示範如何使用服務 SAS 來授權 BlobClient 物件。此用戶端物件可用來根據 SAS 授與的權限，在 Blob 資源上執行作業。

首先，建立以帳戶存取金鑰簽署的 BlobServiceClient 物件：

string accountName = "<storage-account-name>";
string accountKey = "<storage-account-key";
StorageSharedKeyCredential storageSharedKeyCredential =
    new(accountName, accountKey);
BlobServiceClient blobServiceClient = new BlobServiceClient(
    new Uri($"https://{accountName}.blob.core.windows.net"),
    storageSharedKeyCredential);

然後，如同先前範例所示產生服務 SAS，並使用 SAS 來授權 BlobClient 物件：

// Create a Uri object with a service SAS appended
BlobClient blobClient = blobServiceClient
    .GetBlobContainerClient("sample-container")
    .GetBlobClient("sample-blob.txt");
Uri blobSASURI = await CreateServiceSASBlob(blobClient);

// Create a blob client object representing 'sample-blob.txt' with SAS authorization
BlobClient blobClientSAS = new BlobClient(blobSASURI);

定義預存的存取原則

預存存取原則可針對伺服器端的服務等級共用存取簽章 (SAS) 提供額外一層控制權。建立預存存取原則可用來將共用存取簽章分組，以及針對受限於原則的簽章提供額外限制。

您可以使用預存存取原則來變更簽章的開始時間、到期時間或權限。您也可以使用預存存取原則在發出簽章之後撤銷簽章。本節著重於 Blob 容器，但預存存取原則也支援檔案共用、佇列和資料表。

若要管理容器資源上的預存存取原則，請從 BlobContainerClient 物件呼叫下列其中一種方法：

建立或修改預存存取原則

您一次可以在資源上設定最多五個存取原則。每個 SignedIdentifier 欄位，連同其唯一 Id 欄位，均會個別對應到一個存取原則。若嘗試一次設定五個以上的存取原則，會導致服務傳回 400 (Bad Request) 狀態碼。

下列程式碼範例會示範如何在容器資源上建立兩個預存存取原則：

public static async Task CreateStoredAccessPolicyAsync(BlobContainerClient containerClient)
{
    // Create a stored access policy with read and write permissions, valid for one day
    List<BlobSignedIdentifier> signedIdentifiers = new List<BlobSignedIdentifier>
    {
        new BlobSignedIdentifier
        {
            Id = "sample-read-write-policy",
            AccessPolicy = new BlobAccessPolicy
            {
                StartsOn = DateTimeOffset.UtcNow,
                ExpiresOn = DateTimeOffset.UtcNow.AddDays(1),
                Permissions = "rw"
            }
        },
        new BlobSignedIdentifier
        {
            Id = "sample-read-policy",
            AccessPolicy = new BlobAccessPolicy
            {
                StartsOn = DateTimeOffset.UtcNow,
                ExpiresOn = DateTimeOffset.UtcNow.AddDays(1),
                Permissions = "r"
            }
        }
    };

    // Set the container's access policy
    await containerClient.SetAccessPolicyAsync(permissions: signedIdentifiers);
}

您也可以修改現有的原則。下列程式碼範例會示範如何藉由修改單一預存存取原則來更新原則的到期日：

public static async Task ModifyStoredAccessPolicyAsync(BlobContainerClient containerClient)
{
    BlobContainerAccessPolicy accessPolicy = await containerClient.GetAccessPolicyAsync();
    List<BlobSignedIdentifier> signedIdentifiers = accessPolicy.SignedIdentifiers.ToList();

    // Modify the expiration date a single policy
    var samplePolicy = signedIdentifiers.FirstOrDefault(item => item.Id == "sample-read-policy");
    samplePolicy.AccessPolicy.PolicyExpiresOn = DateTimeOffset.UtcNow.AddDays(7);

    // Update the container's access policy
    await containerClient.SetAccessPolicyAsync(permissions: signedIdentifiers);
}

撤銷或刪除預存存取原則

若要撤銷儲存的存取原則，Microsoft 建議刪除已簽署的識別碼並建立一個新的識別碼。變更簽署識別碼會中斷任何現有的簽章與該儲存的存取原則之間的關聯。預存存取原則一經刪除或修改，將隨即影響所有與其相關聯的共用存取簽章。

下列程式碼範例會示範如何藉由變更已簽署識別碼的 Id 屬性來撤銷原則。此方法有效地刪除已簽署的識別碼並建立一個新的識別碼：

public static async Task RevokeStoredAccessPolicyAsync(BlobContainerClient containerClient)
{
    BlobContainerAccessPolicy accessPolicy = await containerClient.GetAccessPolicyAsync();
    List<BlobSignedIdentifier> signedIdentifiers = accessPolicy.SignedIdentifiers.ToList();

    // Revoke a single policy by changing its name
    var samplePolicy = signedIdentifiers.FirstOrDefault(item => item.Id == "sample-read-policy");
    samplePolicy.Id = "sample-read-policy-revoke";

    // Update the container's access policy
    await containerClient.SetAccessPolicyAsync(permissions: signedIdentifiers);
}

您也可以藉由使用空白 permissions 參數來呼叫 SetAccessPolicyAsync，即可從容器資源移除所有存取原則。下列範例會示範如何從指定的容器中刪除所有預存存取原則：

public static async Task DeleteStoredAccessPolicyAsync(BlobContainerClient containerClient)
{
    // Remove all stored access policies for the container resource
    await containerClient.SetAccessPolicyAsync();
}

資源

若要深入了解如何使用 .NET 適用的 Azure Blob 儲存體用戶端程式庫來建立服務 SAS，請參閱下列資源。

程式碼範例

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

共用方式為

使用 .NET 建立容器或 Blob 的服務 SAS

關於服務 SAS

建立服務 SAS

使用服務 SAS 來授權用戶端物件

定義預存的存取原則

建立或修改預存存取原則

撤銷或刪除預存存取原則

資源

程式碼範例

用戶端程式庫資源

另請參閱

意見反應

其他資源