共用方式為

ContainerClient 類別

  • 參考

要與特定容器互動的用戶端，雖然該容器可能還不存在。

對於與此容器內特定 Blob 相關的作業，可以使用 函式擷取 get_blob_client Blob 用戶端。

繼承
azure.storage.blob._shared.base_client_async.AsyncStorageAccountHostsMixin
ContainerClient
azure.storage.blob._container_client.ContainerClient
ContainerClient
azure.storage.blob._encryption.StorageEncryptionMixin
ContainerClient

建構函式

ContainerClient(account_url: str, container_name: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | AsyncTokenCredential | None = None, **kwargs: Any)

參數

account_url
str
必要

儲存體帳戶的 URI。 若要在容器的完整 URI 下建立用戶端，請使用 from_container_url classmethod。

container_name
str
必要

Blob 的容器名稱。

credential
預設值: None

要用來驗證的認證。 如果帳戶 URL 已經有 SAS 權杖，則這是選擇性的。 此值可以是 SAS 權杖字串、來自 azure.core.credentials 的 AzureSasCredential 或 AzureNamedKeyCredential 實例、帳戶共用存取金鑰，或來自 azure.identity 的 TokenCredentials 類別實例。 如果資源 URI 已經包含 SAS 權杖，則會忽略此權杖，以使用明確的認證

  • 除了 AzureSasCredential 的情況之外，衝突的 SAS 權杖將會引發 ValueError。 如果使用 AzureNamedKeyCredential 的實例，「name」 應該是儲存體帳戶名稱，而 「key」 應該是儲存體帳戶金鑰。
api_version
str

要用於要求的儲存體 API 版本。 預設值是與目前 SDK 相容的最新服務版本。 將 設定為較舊版本可能會導致功能相容性降低。

12.2.0 版的新功能。

secondary_hostname
str

次要端點的主機名稱。

max_block_size
int

以區塊方式上傳區塊 Blob 的最大區塊大小。 預設為 41024 1024或 4MB。

max_single_put_size
int

如果 Blob 大小小於或等於 max_single_put_size，則 Blob 只會上傳一個 HTTP PUT 要求。 如果 Blob 大小大於 max_single_put_size，Blob 將會以區塊方式上傳。 預設為 641024 1024或 64MB。

min_large_block_upload_threshold
int

上傳區塊 Blob 時，使用記憶體有效率演算法所需的最社區塊大小。 預設為 4*1024*1024+1。

use_byte_buffer
bool

針對區塊 Blob 上傳使用位元組緩衝區。 預設為 False。

max_page_size
int

上傳分頁 Blob 的最大區塊大小。 預設為 41024 1024或 4MB。

max_single_get_size
int

在單一呼叫中下載 Blob 的大小上限，超過的部分會以區塊方式下載， (可能會平行) 。 預設為 321024 1024或 32MB。

max_chunk_get_size
int

用於下載 Blob 的最大區塊大小。 預設為 41024 1024或 4MB。

方法

acquire_lease

要求新的租用。 如果容器沒有作用中的租用，Blob 服務會在容器上建立租用，並傳回新的租用識別碼。
close

這個方法是關閉用戶端所開啟的通訊端。 與內容管理員搭配使用時，不需要使用它。
create_container

在指定的帳號下建立新的容器。 如果相同名稱的容器已經存在，作業會失敗。
delete_blob

標記要刪除的指定 Blob 或快照集。

Blob 稍後會在記憶體回收時刪除。 請注意，若要刪除 Blob，您必須刪除其所有快照集。 您可以使用delete_blob作業同時刪除這兩者。

如果服務已啟用刪除保留原則，此作業會虛刪除 Blob 或快照集，並保留 Blob 或快照集的指定天數。 在指定的天數之後，Blob 的資料會在垃圾收集期間從服務中移除。 虛刪除的 Blob 或快照集可透過 list_blobs 指定 include=[「deleted」] 虛刪除的 Blob 或快照集進行還原 <xref:azure.storage.blob.aio.BlobClient.undelete>
delete_blobs

標記要刪除的指定 Blob 或快照集。

Blob 稍後會在垃圾收集期間刪除。 請注意，若要刪除 Blob，您必須刪除其所有快照集。 您可以使用delete_blobs作業同時刪除這兩者。

如果服務已啟用刪除保留原則，此作業會虛刪除 Blob 或快照集，並保留 Blob 或快照集的指定天數。 在指定的天數之後，Blob 的資料會在垃圾收集期間從服務中移除。 虛刪除的 Blob 或快照集可透過 list_blobs 指定 include=[「deleted」] 虛刪除的 Blob 或快照集來還原使用 <xref:azure.storage.blob.aio.BlobClient.undelete>

單一要求中可刪除的 Blob 數目上限為 256。
delete_container

標示要刪除的指定容器。 其中包含的容器和任何 Blob 稍後會在記憶體回收時刪除。
download_blob

將 Blob 下載至 StorageStreamDownloader。 readall () 方法必須用來讀取所有內容或 readinto () ，才能將 Blob 下載至資料流程。 使用 chunks () 會傳回非同步反覆運算器，讓使用者以區塊逐一查看內容。
exists

如果容器存在，則傳回 True，否則會傳回 False。
find_blobs_by_tags

傳回產生器，以列出指定容器底下的 Blob，其標記符合指定的搜尋運算式。 產生器會延遲遵循服務所傳回的接續權杖。
from_connection_string

從連接字串建立 ContainerClient。
from_container_url

從容器 URL 建立 ContainerClient。
get_account_information

取得儲存體帳戶的相關資訊。

如果使用者具有容器或 Blob 的 SAS，也可以擷取資訊。 傳回字典中的索引鍵包括 'sku_name' 和 'account_kind'。
get_blob_client

取得用戶端以與指定的 Blob 互動。

Blob 不需要已經存在。
get_container_access_policy

取得指定容器的許可權。 這些權限指出是否可以公開存取容器資料。
get_container_properties

傳回指定容器的所有使用者定義中繼資料和系統屬性。 傳回的資料不包含容器的 Blob 清單。
list_blob_names

傳回產生器，以列出指定容器底下的 Blob 名稱。 產生器會延遲遵循服務所傳回的接續權杖。

請注意，使用此 API 時不會傳回任何其他屬性或中繼資料。 此外，此 API 沒有選項可包含其他 Blob，例如快照集、版本、虛刪除的 Blob 等。若要取得此資料中的任何一項，請使用 list_blobs 。
list_blobs

傳回產生器，以列出指定容器底下的 Blob。 產生器會延遲遵循服務所傳回的接續權杖。
set_container_access_policy

設定可搭配共用存取簽章使用的指定容器或預存存取原則的許可權。 這些權限指出是否可以公開存取容器中的 Blob。
set_container_metadata

為指定的容器設定一或多個使用者定義的名稱/值組。 每次呼叫這項作業都會取代附加至容器之所有現有的中繼資料。 若要從容器中移除所有中繼資料，請呼叫沒有中繼資料聽寫的這項作業。
set_premium_page_blob_tier_blobs

設定 Blob 上的分頁 Blob 層。 只有進階帳戶上的分頁 Blob 才支援此 API。

單一要求中可更新的 Blob 數目上限為 256。
set_standard_blob_tier_blobs

此作業會在區塊 Blob 上設定層。

區塊 Blob 的層會決定經常性存取/非經常性存取/封存儲存體類型。 這項作業不會更新 Blob 的 ETag。

單一要求中可更新的 Blob 數目上限為 256。
upload_blob

使用自動區塊化從資料來源建立新的 Blob。
walk_blobs

傳回產生器，以列出指定容器底下的 Blob。 產生器會延遲遵循服務所傳回的接續權杖。 此作業會根據階層列出 Blob，以指定的分隔符號分隔。

acquire_lease

要求新的租用。 如果容器沒有作用中的租用，Blob 服務會在容器上建立租用，並傳回新的租用識別碼。

async acquire_lease(lease_duration: int = -1, lease_id: str | None = None, **kwargs) -> BlobLeaseClient

參數

lease_duration
int
必要

指定租用的持續時間 (秒數)，或指定負一 (-1)，代表租用永不到期。 非無限期的租用可以介於 15 到 60 秒之間。 無法使用續約或變更來變更租用持續時間。 預設值為 -1 (無限租用) 。

lease_id
str
必要

建議的租用識別碼，使用 GUID 字串格式。 如果建議的租用識別碼的格式不正確，Blob 服務會傳回 400 (不正確要求) 。

if_modified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源在指定的時間後修改，才能指定此標準執行作業。

if_unmodified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源沒有在指定的日期/時間後修改，才能指定此標頭執行作業。

etag
str

ETag 值，或萬用字元 (*)。 用來檢查資源是否已變更，並根據 match_condition 參數所指定的條件採取行動。

match_condition
MatchConditions

要用於 etag 的比對條件。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 此值不會在用戶端上追蹤或驗證。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

BlobLeaseClient 物件，可在內容管理員中執行。

傳回類型

BlobLeaseClient

close

這個方法是關閉用戶端所開啟的通訊端。 與內容管理員搭配使用時，不需要使用它。

async close()

create_container

在指定的帳號下建立新的容器。 如果相同名稱的容器已經存在，作業會失敗。

async create_container(metadata: Dict[str, str] | None = None, public_access: PublicAccess | str | None = None, **kwargs: Any) -> Dict[str, str | datetime]

參數

metadata
dict[str, str]
必要

具有name_value組的聽寫，要與容器產生關聯做為中繼資料。 範例：{'Category'：'test'}

public_access
PublicAccess
必要

可能的值包括：'container'、'blob'。

container_encryption_scope
dict 或 ContainerEncryptionScope

指定要在容器上設定的預設加密範圍，並用於所有未來的寫入。

12.2.0 版的新功能。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 此值不會在用戶端上追蹤或驗證。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

回應標頭的字典。

傳回類型

Dict[str, Union[str, datetime]]

delete_blob

標記要刪除的指定 Blob 或快照集。

Blob 稍後會在記憶體回收時刪除。 請注意，若要刪除 Blob，您必須刪除其所有快照集。 您可以使用delete_blob作業同時刪除這兩者。

如果服務已啟用刪除保留原則，此作業會虛刪除 Blob 或快照集，並保留 Blob 或快照集的指定天數。 在指定的天數之後，Blob 的資料會在垃圾收集期間從服務中移除。 虛刪除的 Blob 或快照集可透過 list_blobs 指定 include=[「deleted」] 虛刪除的 Blob 或快照集進行還原 <xref:azure.storage.blob.aio.BlobClient.undelete>

async delete_blob(blob: str | BlobProperties, delete_snapshots: str | None = None, **kwargs) -> None

參數

blob
str 或 BlobProperties
必要

要與其互動的 Blob。 如果指定，此值將會覆寫 Blob URL 中指定的 Blob 值。

delete_snapshots
str
必要

如果 Blob 有相關聯的快照集，則為必要項目。 數值包括：

  • 「only」：只刪除 Blob 快照集。

  • 「include」：刪除 Blob 以及所有快照集。

version_id
str

版本識別碼參數是不透明的 DateTime 值，當存在時，會指定要刪除的 Blob 版本。

12.4.0 版的新功能。

此關鍵字引數是在 API 版本 '2019-12-12' 中引進。

lease
BlobLeaseClient 或 str

如果 Blob 具有作用中租用，則為必要項目。 值可以是 Lease 物件或租用識別碼做為字串。

if_modified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源在指定的時間後修改，才能指定此標準執行作業。

if_unmodified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源沒有在指定的日期/時間後修改，才能指定此標頭執行作業。

etag
str

ETag 值，或萬用字元 (*)。 用來檢查資源是否已變更，並根據 match_condition 參數所指定的條件採取行動。

match_condition
MatchConditions

要用於 etag 的比對條件。

if_tags_match_condition
str

指定 Blob 標記上的 SQL where 子句，以只在具有相符值的 Blob 上運作。 例如 "\"tagname\"='my tag'"

12.4.0 版的新功能。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回類型

None

delete_blobs

標記要刪除的指定 Blob 或快照集。

Blob 稍後會在垃圾收集期間刪除。 請注意，若要刪除 Blob，您必須刪除其所有快照集。 您可以使用delete_blobs作業同時刪除這兩者。

如果服務已啟用刪除保留原則，此作業會虛刪除 Blob 或快照集，並保留 Blob 或快照集的指定天數。 在指定的天數之後，Blob 的資料會在垃圾收集期間從服務中移除。 虛刪除的 Blob 或快照集可透過 list_blobs 指定 include=[「deleted」] 虛刪除的 Blob 或快照集來還原使用 <xref:azure.storage.blob.aio.BlobClient.undelete>

單一要求中可刪除的 Blob 數目上限為 256。

async delete_blobs(*blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> AsyncIterator[AsyncHttpResponse]

參數

blobs
str 或 dict(str, Any) 或 BlobProperties
必要

要刪除的 Blob。 這可以是單一 Blob，也可以提供多個值，其中每個值都是 blob 的名稱 (str) 或 BlobProperties。

注意

當 Blob 類型是聽寫時，以下是索引鍵、值規則的清單。

Blob 名稱：

機碼：'name'，實數值型別：str

您想要刪除的快照集：

機碼：'snapshot'，實數值型別：str

是否要在刪除 Blob 時刪除快照集：

索引鍵：'delete_snapshots'，值： 'include' 或 'only'

如果 Blob 已修改或未修改：

機碼：'if_modified_since'、'if_unmodified_since'、實數值型別：datetime

Etag：

機碼：'etag'，實數值型別：str

比對 etag 或不是：

機碼：'match_condition'，實數值型別：MatchConditions

標記比對條件：

機碼：'if_tags_match_condition'，實數值型別： str

租賃：

機碼： 'lease_id'， 實數值型別： Union[str， LeaseClient]

subrequest 的逾時：

機碼：'timeout'，實數值型別：int

delete_snapshots
str

如果 Blob 有相關聯的快照集，則為必要專案。 數值包括：

  • 「only」：只刪除 Blob 快照集。

  • 「include」：刪除 Blob 以及所有快照集。

if_modified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源在指定的時間後修改，才能指定此標準執行作業。

if_unmodified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源沒有在指定的日期/時間後修改，才能指定此標頭執行作業。

if_tags_match_condition
str

指定 Blob 標記上的 SQL where 子句，以只在具有相符值的 Blob 上運作。 例如 "\"tagname\"='my tag'"

12.4.0 版的新功能。

raise_on_any_failure
bool

這是布林參數，預設為 True。 設定時，即使發生單一作業失敗，也會引發例外狀況。 為了獲得最佳效能，這應該設定為 False

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

回應的非同步反覆運算器，每個 Blob 的順序各一個

傳回類型

<xref:asynciterator>[AsyncHttpResponse]

delete_container

標示要刪除的指定容器。 其中包含的容器和任何 Blob 稍後會在記憶體回收時刪除。

async delete_container(**kwargs: Any) -> None

參數

lease
BlobLeaseClient 或 str

如果指定，delete_container只有在容器的租用作用中且符合此識別碼時才會成功。 如果容器具有作用中的租用，則為必要專案。

if_modified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源在指定的時間後修改，才能指定此標準執行作業。

if_unmodified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源沒有在指定的日期/時間後修改，才能指定此標頭執行作業。

etag
str

ETag 值，或萬用字元 (*)。 用來檢查資源是否已變更，並根據 match_condition 參數所指定的條件採取行動。

match_condition
MatchConditions

要用於 etag 的比對條件。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回類型

None

download_blob

將 Blob 下載至 StorageStreamDownloader。 readall () 方法必須用來讀取所有內容或 readinto () ，才能將 Blob 下載至資料流程。 使用 chunks () 會傳回非同步反覆運算器，讓使用者以區塊逐一查看內容。

async download_blob(blob: str | BlobProperties, offset: int = None, length: int = None, *, encoding: str, **kwargs) -> StorageStreamDownloader[str]

參數

blob
str 或 BlobProperties
必要

要與其互動的 Blob。 如果指定，此值將會覆寫 Blob URL 中指定的 Blob 值。

offset
int
必要

要用來下載 Blob 區段的位元組範圍開始。 如果提供長度，則必須設定 。

length
int
必要

要從資料流程讀取的位元組數目。 這是選擇性的，但應該提供以獲得最佳效能。

version_id
str

版本識別碼參數是不透明的 DateTime 值，當存在時，會指定要下載的 Blob 版本。

12.4.0 版的新功能。

此關鍵字引數是在 API 版本 '2019-12-12' 中引進。

validate_content
bool

如果為 true，則計算 Blob 每個區塊的 MD5 雜湊。 儲存體服務會檢查與已傳送雜湊一起抵達之內容的雜湊。 如果使用 HTTP 而非 HTTPs，這主要是在使用 HTTP 而非 HTTPs 時偵測連線上的 bitflip，因為 HTTPs (預設) ，將會經過驗證。 請注意，此 MD5 雜湊不會隨 Blob 儲存。 另請注意，如果啟用，將不會使用記憶體有效率上傳演算法，因為計算 MD5 雜湊需要緩衝處理整個區塊，因此會破壞記憶體有效率演算法的用途。

lease
BlobLeaseClient 或 str

如果 Blob 具有作用中租用，則為必要項目。 如果指定，download_blob只有在 Blob 的租用作用中且符合此識別碼時才會成功。 值可以是 BlobLeaseClient 物件或租用識別碼做為字串。

if_modified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源在指定的時間後修改，才能指定此標準執行作業。

if_unmodified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源沒有在指定的日期/時間後修改，才能指定此標頭執行作業。

etag
str

ETag 值，或萬用字元 (*)。 用來檢查資源是否已變更，並根據 match_condition 參數所指定的條件採取行動。

match_condition
MatchConditions

要用於 etag 的比對條件。

if_tags_match_condition
str

指定 Blob 標籤上的 SQL where 子句，以只在具有相符值的 Blob 上運作。 例如 "\"tagname\"='my tag'"

12.4.0 版的新功能。

cpk
CustomerProvidedEncryptionKey

使用指定的金鑰加密服務端的資料。 您必須透過 HTTPS 使用客戶提供的金鑰。 在要求中提供加密金鑰本身時，必須建立安全連線才能傳輸金鑰。

max_concurrency
int

要下載的平行連線數目。

encoding
str

要解碼所下載位元組的編碼方式。 預設值為 None，也就是沒有解碼。

progress_hook
Callable[[int, int], Awaitable[None]]

非同步回呼，用來追蹤長時間執行下載的進度。 簽章是目前 (函式：int、total： int) 其中 current 是目前傳輸的位元組數目，而 total 是下載的總大小。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 此值不會在用戶端上追蹤或驗證。 若要設定用戶端網路逾時，請參閱 這裡。 這個方法可能會對服務進行多個呼叫，而逾時會個別套用至每個呼叫。 對 Azure 服務的多個呼叫，而逾時會個別套用至每個呼叫。

傳回

串流物件。 (StorageStreamDownloader)

傳回類型

StorageStreamDownloader

exists

如果容器存在，則傳回 True，否則會傳回 False。

async exists(**kwargs: Any) -> bool

參數

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 此值不會在用戶端上追蹤或驗證。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

boolean

傳回類型

bool

find_blobs_by_tags

傳回產生器，以列出指定容器底下的 Blob，其標記符合指定的搜尋運算式。 產生器會延遲遵循服務所傳回的接續權杖。

find_blobs_by_tags(filter_expression: str, **kwargs: Any | None) -> AsyncItemPaged[FilteredBlob]

參數

filter_expression
str
必要

要尋找標記符合指定條件之 Blob 的運算式。 例如 「」yourtagname「='firsttag' 和 」yourtagname2「='secondtag'」

results_per_page
int

分頁時，每頁的結果上限。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 此值不會在用戶端上追蹤或驗證。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

FilteredBlob 的可反覆運算 (自動分頁) 回應。

傳回類型

ItemPaged[BlobProperties]

from_connection_string

從連接字串建立 ContainerClient。

from_connection_string(conn_str: str, container_name: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

參數

conn_str
str
必要

Azure 儲存體帳戶的連接字串。

container_name
str
必要

Blob 的容器名稱。

credential
預設值: None

要用來驗證的認證。 如果帳戶 URL 已經有 SAS 權杖，或連接字串已經有共用存取金鑰值，則這是選擇性的。 此值可以是 SAS 權杖字串、來自 azure.core.credentials 的 AzureSasCredential 或 AzureNamedKeyCredential 實例、帳戶共用存取金鑰，或來自 azure.identity 的 TokenCredentials 類別實例。 此處提供的認證優先于連接字串中的認證。 如果使用 AzureNamedKeyCredential 的實例，「name」 應該是儲存體帳戶名稱，而 「key」 應該是儲存體帳戶金鑰。

傳回

容器用戶端。

傳回類型

ContainerClient

from_container_url

從容器 URL 建立 ContainerClient。

from_container_url(container_url: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

參數

container_url
str
必要

容器的完整端點 URL，包括使用時使用的 SAS 權杖。 這可能是主要端點，或視目前 location_mode而定的次要端點。

credential
預設值: None

要用來驗證的認證。 如果帳戶 URL 已經有 SAS 權杖，或連接字串已經有共用存取金鑰值，則這是選擇性的。 此值可以是 SAS 權杖字串、來自 azure.core.credentials 的 AzureSasCredential 或 AzureNamedKeyCredential 實例、帳戶共用存取金鑰，或來自 azure.identity 的 TokenCredentials 類別實例。 如果資源 URI 已經包含 SAS 權杖，則會忽略此權杖，以使用明確的認證

  • 除了 AzureSasCredential 的情況之外，衝突的 SAS 權杖將會引發 ValueError。 如果使用 AzureNamedKeyCredential 的實例，「name」 應該是儲存體帳戶名稱，而 「key」 應該是儲存體帳戶金鑰。

傳回

容器用戶端。

傳回類型

ContainerClient

get_account_information

取得儲存體帳戶的相關資訊。

如果使用者具有容器或 Blob 的 SAS，也可以擷取資訊。 傳回字典中的索引鍵包括 'sku_name' 和 'account_kind'。

async get_account_information(**kwargs: Any) -> Dict[str, str]

傳回

帳戶資訊的聽寫 (SKU 和帳戶類型) 。

傳回類型

dict(str, str)

get_blob_client

取得用戶端以與指定的 Blob 互動。

Blob 不需要已經存在。

get_blob_client(blob: BlobProperties | str, snapshot: str = None, *, version_id: str | None = None) -> BlobClient

參數

blob
str 或 BlobProperties
必要

要與其互動的 Blob。

snapshot
str
預設值: None

要在其上運作的選擇性 Blob 快照集。 這可以是快照集識別碼字串或從 create_snapshot 傳回的回應。

version_id
str

版本識別碼參數是不透明的 DateTime 值，當存在時，會指定要運作的 Blob 版本。

傳回

BlobClient。

傳回類型

BlobClient

get_container_access_policy

取得指定容器的許可權。 這些權限指出是否可以公開存取容器資料。

async get_container_access_policy(**kwargs: Any) -> Dict[str, Any]

參數

lease
BlobLeaseClient 或 str

如果指定，get_container_access_policy只有在容器的租用為作用中且符合此識別碼時才會成功。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

存取聽寫中的原則資訊。

傳回類型

dict[str, Any]

get_container_properties

傳回指定容器的所有使用者定義中繼資料和系統屬性。 傳回的資料不包含容器的 Blob 清單。

async get_container_properties(**kwargs: Any) -> ContainerProperties

參數

lease
BlobLeaseClient 或 str

如果指定，則get_container_properties只有在容器的租用為作用中且符合此識別碼時才會成功。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

容器物件內指定容器的屬性。

傳回類型

ContainerProperties

list_blob_names

傳回產生器，以列出指定容器底下的 Blob 名稱。 產生器會延遲遵循服務所傳回的接續權杖。

請注意，使用此 API 時不會傳回任何其他屬性或中繼資料。 此外，此 API 沒有選項可包含其他 Blob，例如快照集、版本、虛刪除的 Blob 等。若要取得此資料中的任何一項，請使用 list_blobs 。

list_blob_names(**kwargs: Any) -> AsyncItemPaged[str]

參數

name_starts_with
str

篩選結果，只傳回名稱開頭為指定前置詞的 Blob。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

可逐一 (自動分頁) Blob 名稱作為字串的回應。

傳回類型

AsyncItemPaged[str]

list_blobs

傳回產生器，以列出指定容器底下的 Blob。 產生器會延遲遵循服務所傳回的接續權杖。

list_blobs(name_starts_with: str | None = None, include: str | List[str] | None = None, **kwargs: Any) -> AsyncItemPaged[BlobProperties]

參數

name_starts_with
str
必要

篩選結果，只傳回名稱開頭為指定前置詞的 Blob。

include
list[str] 或 str
必要

指定要包含在回應中的一或多個其他資料集。 選項包括：'snapshots'、'metadata'、'uncommittedblobs'、'copy'、'deleted'、'deletedwithversions'、'tags'、'versions'、'immutabilitypolicy'、'legalhold'。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

可逐一 (BlobProperties 的自動分頁) 回應。

傳回類型

AsyncItemPaged[BlobProperties]

set_container_access_policy

設定可搭配共用存取簽章使用的指定容器或預存存取原則的許可權。 這些權限指出是否可以公開存取容器中的 Blob。

async set_container_access_policy(signed_identifiers: Dict[str, AccessPolicy], public_access: str | PublicAccess | None = None, **kwargs: Any) -> Dict[str, str | datetime]

參數

signed_identifiers
dict[str, AccessPolicy]
必要

要與容器建立關聯的存取原則字典。 字典最多可以包含 5 個元素。 空的字典會清除服務上設定的存取原則。

public_access
PublicAccess
必要

可能的值包括：'container'、'blob'。

lease
BlobLeaseClient 或 str

如果容器具有作用中的租用，則為必要專案。 值可以是 BlobLeaseClient 物件或租用識別碼作為字串。

if_modified_since
datetime

datetime 值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 指定此標頭，只有在資源自指定的日期/時間以來已修改時，才執行作業。

if_unmodified_since
datetime

datetime 值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源沒有在指定的日期/時間後修改，才能指定此標頭執行作業。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

容器更新的屬性聽寫 (Etag 和上次修改) 。

傳回類型

dict[str, str,
datetime]

set_container_metadata

為指定的容器設定一或多個使用者定義的名稱/值組。 每次呼叫這項作業都會取代附加至容器之所有現有的中繼資料。 若要從容器中移除所有中繼資料，請呼叫沒有中繼資料聽寫的這項作業。

async set_container_metadata(metadata: Dict[str, str] | None = None, **kwargs) -> Dict[str, str | datetime]

參數

metadata
dict[str, str]
必要

包含要與容器建立關聯做為中繼資料之名稱/值組的聽寫。 範例： {'category'：'test'}

lease
BlobLeaseClient 或 str

如果指定，set_container_metadata只有在容器的租用作用中且符合此識別碼時才會成功。

if_modified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源在指定的時間後修改，才能指定此標準執行作業。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

容器更新的屬性聽寫 (Etag 和上次修改) 。

set_premium_page_blob_tier_blobs

設定 Blob 上的分頁 Blob 層。 只有進階帳戶上的分頁 Blob 才支援此 API。

單一要求中可更新的 Blob 數目上限為 256。

async set_premium_page_blob_tier_blobs(premium_page_blob_tier: str | PremiumPageBlobTier, *blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> AsyncIterator[AsyncHttpResponse]

參數

premium_page_blob_tier
PremiumPageBlobTier
必要

要設定于所有 Blob 上的分頁 Blob 層值。 層會與 Blob 的大小和允許的 IOPS 數目相互關聯。 這僅適用于進階儲存體帳戶上的分頁 Blob。

注意

如果您想要在不同的 Blob 上設定不同的層，請將此位置參數設定為 None。

然後，將會取得每個 BlobProperties 上的 Blob 層。

blobs
str 或 dict(str, Any) 或 BlobProperties
必要

要與其互動的 Blob。 這可以是單一 Blob，也可以提供多個值，其中每個值都是 blob 的名稱 (str) 或 BlobProperties。

注意

當 Blob 類型是聽寫時，以下是索引鍵、值規則的清單。

Blob 名稱：

機碼：'name'，實數值型別：str

進階 Blob 層：

機碼： 'blob_tier'， 實數值型別： PremiumPageBlobTier

租賃：

機碼： 'lease_id'， 實數值型別： Union[str， LeaseClient]

subrequest 的逾時：

機碼：'timeout'，實數值型別：int

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

raise_on_any_failure
bool

這是布林參數，預設為 True。 設定時，即使發生單一作業失敗，也會引發例外狀況。 為了獲得最佳效能，這應該設定為 False。

傳回

回應的非同步反覆運算器，每個 Blob 的順序各一個

傳回類型

<xref:asynciterator>[AsyncHttpResponse]

set_standard_blob_tier_blobs

此作業會在區塊 Blob 上設定層。

區塊 Blob 的層會決定經常性存取/非經常性存取/封存儲存體類型。 這項作業不會更新 Blob 的 ETag。

單一要求中可更新的 Blob 數目上限為 256。

async set_standard_blob_tier_blobs(standard_blob_tier: str | StandardBlobTier, *blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> AsyncIterator[AsyncHttpResponse]

參數

standard_blob_tier
str 或 StandardBlobTier
必要

指出要在所有 Blob 上設定的層。 選項包括 'Hot'、'Cool'、'Archive'。 經常性存取層已針對儲存經常存取的資料進行優化。 非經常性儲存層已針對儲存不常存取和儲存至少一個月的資料進行優化。 封存層已針對儲存很少存取且至少儲存六個月且有彈性延遲需求的資料進行優化。

注意

如果您想要在不同的 Blob 上設定不同的層，請將此位置參數設定為 None。

然後，將會取得每個 BlobProperties 上的 Blob 層。

blobs
str 或 dict(str, Any) 或 BlobProperties
必要

要與其互動的 Blob。 這可以是單一 Blob，也可以提供多個值，其中每個值都是 blob 的名稱 (str) 或 BlobProperties。

注意

當 Blob 類型是聽寫時，以下是索引鍵、值規則的清單。

Blob 名稱：

機碼：'name'，實數值型別：str

標準 Blob 層：

機碼：'blob_tier'，實數值型別：StandardBlobTier

解除凍結優先順序：

機碼： 'rehydrate_priority'， 實數值型別： RehydratePriority

租賃：

機碼： 'lease_id'， 實數值型別： Union[str， LeaseClient]

標記比對條件：

機碼：'if_tags_match_condition'，實數值型別： str

subrequest 的逾時：

機碼：'timeout'，實數值型別：int

rehydrate_priority
RehydratePriority

指出將封存 Blob 解除凍結的優先順序

if_tags_match_condition
str

指定 Blob 標記上的 SQL where 子句，以只在具有相符值的 Blob 上運作。 例如 "\"tagname\"='my tag'"

12.4.0 版的新功能。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

raise_on_any_failure
bool

這是布林參數，預設為 True。 設定時，即使發生單一作業失敗，也會引發例外狀況。 為了獲得最佳效能，這應該設定為 False。

傳回

回應的非同步反覆運算器，每個 Blob 的順序各一個

傳回類型

<xref:asynciterator>[AsyncHttpResponse]

upload_blob

使用自動區塊化從資料來源建立新的 Blob。

async upload_blob(name: str | BlobProperties, data: bytes | str | Iterable | AsyncIterable | IO, blob_type: str | BlobType = BlobType.BLOCKBLOB, length: int | None = None, metadata: Dict[str, str] | None = None, **kwargs) -> BlobClient

參數

name
str 或 BlobProperties
必要

要與其互動的 Blob。 如果指定，此值將會覆寫 Blob URL 中指定的 Blob 值。

data
必要

要上傳的 Blob 資料。

blob_type
BlobType
必要

Blob 的類型。 這可以是 BlockBlob、PageBlob 或 AppendBlob。 預設值為 BlockBlob。

length
int
必要

要從資料流程讀取的位元組數目。 這是選擇性的，但應該提供以獲得最佳效能。

metadata
dict(str, str)
必要

與 Blob 相關聯的名稱/值組，可做為中繼資料。

overwrite
bool

要上傳的 Blob 是否應該覆寫目前的資料。 如果為 True，upload_blob將會覆寫現有的資料。 如果設定為 False，作業將會因為 ResourceExistsError 而失敗。 上述的例外狀況是附加 Blob 類型：如果設定為 False 且資料已經存在，則不會引發錯誤，而且資料將會附加至現有的 Blob。 如果 set overwrite=True，則會刪除現有的附加 Blob，並建立新的 Blob。 預設為 False。

content_settings
ContentSettings

用來設定 Blob 屬性的 ContentSettings 物件。 用來設定內容類型、編碼、語言、處置、md5 和快取控制項。

validate_content
bool

如果為 true，則計算 Blob 每個區塊的 MD5 雜湊。 儲存體服務會檢查已使用已傳送之雜湊抵達的內容雜湊。 這主要是在使用 HTTP 而不是 HTTPs 時偵測線路上的 bitflip，因為 HTTPs (預設) ，將會進行驗證。 請注意，此 MD5 雜湊不會隨 Blob 儲存。 另請注意，如果啟用，將不會使用具有記憶體效率的上傳演算法，因為計算 MD5 雜湊需要緩衝整個區塊，因此會破壞記憶體效率演算法的目的。

lease
BlobLeaseClient 或 str

如果容器具有作用中的租用，則為必要專案。 值可以是 BlobLeaseClient 物件或租用識別碼作為字串。

if_modified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源在指定的時間後修改，才能指定此標準執行作業。

if_unmodified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區，則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。 只有資源沒有在指定的日期/時間後修改，才能指定此標頭執行作業。

etag
str

ETag 值，或萬用字元 (*)。 用來檢查資源是否已變更，並根據 match_condition 參數所指定的條件採取行動。

match_condition
MatchConditions

要用於 etag 的比對條件。

if_tags_match_condition
str

指定 Blob 標記上的 SQL where 子句，以只在具有相符值的 Blob 上運作。 例如 "\"tagname\"='my tag'"

12.4.0 版的新功能。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。 這個方法可能會對服務進行多個呼叫，而逾時會個別套用至每個呼叫。 對 Azure 服務的多個呼叫，且逾時會個別套用至每個呼叫。

premium_page_blob_tier
PremiumPageBlobTier

要設定 Blob 的分頁 Blob 層值。 層會與 Blob 的大小和允許的 IOPS 數目相互關聯。 這僅適用于進階儲存體帳戶上的分頁 Blob。

standard_blob_tier
StandardBlobTier

要設定 Blob 的標準 Blob 層值。 對於此版本的程式庫，這只適用于標準儲存體帳戶上的區塊 Blob。

maxsize_condition
int

選擇性的條件式標頭。 附加 Blob 允許的位元組長度上限。 如果附加區塊作業會導致 Blob 超過該限制，或 Blob 大小已經大於此標頭中指定的值，則要求將會失敗，且 MaxBlobSizeConditionNotMet 錯誤 (HTTP 狀態碼 412 - 前置條件失敗) 。

max_concurrency
int

Blob 大小超過 64 MB 時要使用的平行連線數目上限。

cpk
CustomerProvidedEncryptionKey

使用指定的金鑰加密服務端的資料。 您必須透過 HTTPS 使用客戶提供的金鑰。 在要求中提供加密金鑰本身時，必須建立安全連線才能傳輸金鑰。

encryption_scope
str

預先定義的加密範圍，用來加密服務上的資料。 您可以使用管理 API 來建立加密範圍，並依名稱參考此處。 如果已在容器上定義預設加密範圍，如果容器層級範圍設定為允許覆寫，這個值將會覆寫它。 否則會引發錯誤。

12.2.0 版的新功能。

encoding
str

預設為 UTF-8。

progress_hook
Callable[[int, Optional[int]], Awaitable[None]]

非同步回呼，用來追蹤長時間執行上傳的進度。 簽章是目前 (函式：int，total： Optional[int]) 其中 current 是目前傳輸的位元組數目，而 total 是 Blob 的大小，如果大小未知，則為 None。

傳回

與新上傳 Blob 互動的 BlobClient。

傳回類型

BlobClient

walk_blobs

傳回產生器，以列出指定容器底下的 Blob。 產生器會延遲遵循服務所傳回的接續權杖。 此作業會根據階層列出 Blob，以指定的分隔符號分隔。

walk_blobs(name_starts_with: str | None = None, include: str | List[str] | None = None, delimiter: str = '/', **kwargs: Any | None) -> AsyncItemPaged[BlobProperties]

參數

name_starts_with
str
必要

篩選結果，只傳回名稱開頭為指定前置詞的 Blob。

include
list[str] 或 str
必要

指定要包含在回應中的一或多個額外資料集。 選項包括：'snapshots'、'metadata'、'uncommittedblobs'、'copy'、'deletedwithversions'、'tags'、'versions'、'immutabilitypolicy'、'legalhold'。

delimiter
str
必要

當要求包含此參數時，作業會在回應本文中傳回 BlobPrefix 元素，做為名稱開頭為相同子字串的所有 Blob 的預留位置，最多到分隔符號的外觀。 此分隔符號可以是單一字元或字串。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 此值不會在用戶端上追蹤或驗證。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

BlobProperties 的可反覆運算 (自動分頁) 回應。

傳回類型

AsyncItemPaged[BlobProperties]

屬性

api_version

用於要求的儲存體 API 版本。

location_mode

用戶端目前使用的位置模式。

根據預設，這會是「主要」。 選項包括 「主要」和「次要」。

primary_endpoint

完整的主要端點 URL。

primary_hostname

主要端點的主機名稱。

secondary_endpoint

如果已設定，則為完整的次要端點 URL。

如果無法使用，將會引發 ValueError。 若要明確指定次要主機名稱，請在具現化上使用選擇性 secondary_hostname 關鍵字引數。

例外狀況

ValueError

secondary_hostname

次要端點的主機名稱。

如果無法使用，則為 None。 若要明確指定次要主機名稱，請在具現化上使用選擇性 secondary_hostname 關鍵字引數。

url

此實體的完整端點 URL，包括如果使用的 SAS 權杖。

這可能是主要端點或次要端點，視目前的 location_mode 而定。 ：returns：此實體的完整端點 URL，包括如果使用的 SAS 權杖。 ：rtype： str