ContainerClient 類別

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

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

如需更多選擇性設定，請按一下 這裡。

繼承

azure.storage.blob._shared.base_client.StorageAccountHostsMixin

ContainerClient

azure.storage.blob._encryption.StorageEncryptionMixin

ContainerClient

建構函式

ContainerClient(account_url: str, container_name: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | 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 時，使用記憶體有效率演算法所需的最社區塊大小。 預設為 41024 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.BlobClient.undelete>
delete_blobs	標記要刪除的指定 Blob 或快照集。 Blob 稍後會在垃圾收集期間刪除。 請注意，若要刪除 Blob，您必須刪除其所有快照集。 您可以使用delete_blobs作業同時刪除這兩者。 如果服務已啟用刪除保留原則，此作業會虛刪除 Blob 或快照集，並保留 Blob 或快照集的指定天數。 在指定的天數之後，Blob 的資料會在垃圾收集期間從服務中移除。 虛刪除的 Blob 或快照集可透過 list_blobs 指定 include=[「deleted」] 虛刪除的 Blob 或快照集來還原 <xref:azure.storage.blob.BlobClient.undelete> 單一要求中可刪除的 Blob 數目上限為 256。
delete_container	標記要刪除的指定容器。 其中包含的容器和任何 Blob 稍後會在記憶體回收時刪除。
download_blob	將 Blob 下載至 StorageStreamDownloader。 readall () 方法必須用來讀取所有內容或 readinto () ，才能將 Blob 下載至資料流程。 使用區塊 () 會傳回反覆運算器，讓使用者逐一查看區塊中的內容。
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 層。 此 API 僅支援進階帳戶上的分頁 Blob。 單一要求中可更新的 Blob 數目上限為 256。
set_standard_blob_tier_blobs	此作業會設定區塊 Blob 上的層。 區塊 Blob 的層會決定經常性存取/非經常性存取/封存儲存體類型。 這項作業不會更新 Blob 的 ETag。 單一要求中可更新的 Blob 數目上限為 256。
upload_blob	使用自動區塊化從資料來源建立新的 Blob。
walk_blobs	傳回產生器，以列出指定容器底下的 Blob。 產生器會延遲遵循服務所傳回的接續權杖。 此作業會根據階層列出 Blob，以指定的分隔符號分隔。

acquire_lease

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

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

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

close()

create_container

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

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.BlobClient.undelete>

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 具有作用中租用，則為必要項目。 值可以是 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 。 此值不會在用戶端上追蹤或驗證。 若要設定用戶端網路逾時，請參閱 這裡。

傳回類型

None

delete_blobs

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

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

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

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

delete_blobs(*blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> Iterator[HttpResponse]

參數

blobs

str 或 dict(str, Any) 或 BlobProperties

必要

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

注意

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

Blob 名稱：

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

您想要刪除的快照集：

索引鍵：'snapshot'，實數值型別：str

版本識別碼：

索引鍵：'version_id'，實數值型別：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]

子佇列的逾時：

機碼：'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 的布林參數。 設定此設定時，即使發生單一作業失敗，也會引發例外狀況。

timeout

int

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

傳回

回應的反覆運算器，每個 Blob 依序各一個

傳回類型

Iterator[HttpResponse]

delete_container

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

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 下載至資料流程。 使用區塊 () 會傳回反覆運算器，讓使用者逐一查看區塊中的內容。

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 時偵測線路上的 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], 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。

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) -> ItemPaged[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'。

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

傳回

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

傳回類型

dict(str, str)

get_blob_client

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

Blob 不需要已經存在。

get_blob_client(blob: str | BlobProperties, 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

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

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 清單。

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) -> ItemPaged[str]

參數

name_starts_with

str

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

timeout

int

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

傳回

可反覆運算 (自動分頁) Blob 名稱作為字串的回應。

傳回類型

ItemPaged[str]

list_blobs

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

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

參數

name_starts_with

str

必要

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

include

list[str] 或 str

必要

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

timeout

int

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

傳回

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

傳回類型

ItemPaged[BlobProperties]

set_container_access_policy

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

set_container_access_policy(signed_identifiers: Dict[str, AccessPolicy], public_access: str | PublicAccess | None = None, **kwargs) -> 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

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

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。 只有資源在指定的時間後修改，才能指定此標準執行作業。

if_unmodified_since

datetime

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

etag

str

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

timeout

int

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

傳回

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

傳回類型

dict[str, str,

datetime]

set_premium_page_blob_tier_blobs

在所有 Blob 上設定分頁 Blob 層。 此 API 僅支援進階帳戶上的分頁 Blob。

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

set_premium_page_blob_tier_blobs(premium_page_blob_tier: str | PremiumPageBlobTier | None, *blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> Iterator[HttpResponse]

參數

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]

子佇列的逾時：

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

timeout

int

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

raise_on_any_failure

bool

這是預設值為 True 的布林參數。 設定此設定時，即使發生單一作業失敗，也會引發例外狀況。

傳回

回應的反覆運算器，每個 Blob 依序各一個

傳回類型

<xref:iterator>[HttpResponse]

set_standard_blob_tier_blobs

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

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

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

set_standard_blob_tier_blobs(standard_blob_tier: str | StandardBlobTier | None, *blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> Iterator[HttpResponse]

參數

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]

快照：

key：「snapshot」， value type： str

版本識別碼：

機碼：「version_id」， 實數值型別： str

標記比對條件：

索引鍵：'if_tags_match_condition'，實數值型別：str

子佇列的逾時：

機碼：'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 的布林參數。 設定此設定時，即使發生單一作業失敗，也會引發例外狀況。

傳回

回應的反覆運算器，每個 Blob 依序各一個

傳回類型

Iterator[HttpResponse]

upload_blob

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

upload_blob(name: str | BlobProperties, data: bytes | str | Iterable | 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。 如果設定 overwrite=True，則會刪除現有的附加 Blob，並建立新的附加 Blob。 預設為 False。

content_settings

ContentSettings

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

validate_content

bool

如果為 true，則計算 Blob 每個區塊的 MD5 雜湊。 儲存體服務會檢查與已傳送雜湊一起抵達之內容的雜湊。 如果使用 HTTP 而非 HTTPs，這主要是在使用 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 。 此值不會在用戶端上追蹤或驗證。 若要設定用戶端網路逾時，請參閱 這裡。 這個方法可能會對服務進行多個呼叫，而逾時會個別套用至每個呼叫。

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]], 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) -> ItemPaged[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 的可反覆運算 (自動分頁) 回應。

傳回類型

ItemPaged[BlobProperties]

屬性

api_version

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

location_mode

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

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

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