BlobServiceClient 類別

在帳戶層級與 Blob 服務互動的用戶端。

此用戶端提供作業來擷取和設定帳戶屬性，以及列出、建立和刪除帳戶內的容器。 對於與特定容器或 Blob 相關的作業，也可以使用 get_client 函式來擷取這些實體的用戶端。

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

繼承

azure.storage.blob._shared.base_client.StorageAccountHostsMixin

BlobServiceClient

azure.storage.blob._encryption.StorageEncryptionMixin

BlobServiceClient

建構函式

BlobServiceClient(account_url: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any)

參數

account_url

str

必要

Blob 儲存體帳戶的 URL。 URL 路徑中包含的任何其他實體 (例如，將會捨棄容器或 Blob) 。 此 URL 可以選擇性地使用 SAS 權杖進行驗證。

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。

方法

close	這個方法是關閉用戶端所開啟的通訊端。 與內容管理員搭配使用時，不需要使用它。
create_container	在指定的帳號下建立新的容器。 如果具有相同名稱的容器已經存在，將會引發 ResourceExistsError。 這個方法會傳回要與新建立容器互動的用戶端。
delete_container	標示要刪除的指定容器。 其中包含的容器和任何 Blob 稍後會在記憶體回收時刪除。 如果找不到容器，將會引發 ResourceNotFoundError。
find_blobs_by_tags	篩選 Blob 作業可讓呼叫端列出標籤符合指定搜尋運算式之所有容器的 Blob。 篩選 Blob 會在儲存體帳戶內的所有容器中搜尋，但可以在運算式中限定為單一容器。
from_connection_string	從連接字串建立 BlobServiceClient。
get_account_information	取得儲存體帳戶的相關資訊。 如果使用者具有容器或 Blob 的 SAS，也可以擷取資訊。 傳回字典中的索引鍵包括 'sku_name' 和 'account_kind'。
get_blob_client	取得用戶端以與指定的 Blob 互動。 Blob 不需要已經存在。
get_container_client	取得用戶端以與指定的容器互動。 容器不需要已經存在。
get_service_properties	取得儲存體帳戶 Blob 服務的屬性，包括 Azure 儲存體分析。
get_service_stats	擷取與 Blob 服務的複寫相關的統計資料。 只有在儲存體帳戶啟用讀取權限異地備援複寫時，才能使用。 有了地理備援複寫，Azure 儲存體會以持久的方式在兩個位置維護您的資料。 在這兩個位置中，Azure 儲存體會持續維護狀況良好的多個資料複本。 您讀取、建立、更新或刪除資料的位置是「主要」儲存體帳戶的位置。 主要位置存在於您透過 Azure 管理 Azure 傳統入口網站建立帳戶時所選擇的區域，例如美國中北部。 資料複寫的目標位置是「次要」位置。 次要位置是根據主要的位置自動判斷而來，它是與主要位置位於相同地區的第二個資料中心。 當儲存體帳戶啟用「讀取權限的地理備援複寫」時，可從次要位置使用唯讀權限。
get_user_delegation_key	為了簽署 SAS 權杖的目的，取得使用者委派金鑰。 權杖認證必須存在於服務物件上，此要求才能成功。
list_containers	傳回產生器，以列出指定帳戶下的容器。 產生器會延遲遵循服務傳回的接續權杖，並在傳回所有容器時停止。
set_service_properties	設定儲存體帳戶 Blob 服務的屬性，包括 Azure 儲存體分析。 如果專案 (例如，analytics_logging) 保留為 None，則會保留該服務上的現有設定。
undelete_container	還原虛刪除的容器。 只有在刪除保留原則中所設定的指定天數內使用時，作業才會成功。 12.4.0 版的新功能：此作業是在 API 版本 '2019-12-12' 中引進。

close

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

close()

create_container

在指定的帳號下建立新的容器。

如果具有相同名稱的容器已經存在，將會引發 ResourceExistsError。 這個方法會傳回要與新建立容器互動的用戶端。

create_container(name: str, metadata: Dict[str, str] | None = None, public_access: PublicAccess | str | None = None, **kwargs) -> ContainerClient

參數

name

str

必要

要建立的容器名稱。

metadata

dict(str, str)

必要

具有名稱/值組的聽寫，與容器建立關聯做為中繼資料。 範例： {'Category'：'test'}

public_access

str 或 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 。 此值不會在用戶端上追蹤或驗證。 若要設定用戶端網路逾時，請參閱 這裡。

傳回類型

ContainerClient

delete_container

標示要刪除的指定容器。

其中包含的容器和任何 Blob 稍後會在記憶體回收時刪除。 如果找不到容器，將會引發 ResourceNotFoundError。

delete_container(container: ContainerProperties | str, lease: BlobLeaseClient | str | None = None, **kwargs) -> None

參數

container

str 或 ContainerProperties

必要

要刪除的容器。 這可以是容器的名稱或 ContainerProperties 的實例。

lease

必要

如果指定，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

find_blobs_by_tags

篩選 Blob 作業可讓呼叫端列出標籤符合指定搜尋運算式之所有容器的 Blob。 篩選 Blob 會在儲存體帳戶內的所有容器中搜尋，但可以在運算式中限定為單一容器。

find_blobs_by_tags(filter_expression: str, **kwargs: Any) -> ItemPaged[FilteredBlob]

參數

filter_expression

str

必要

要尋找標記符合指定條件之 Blob 的運算式。 例如 「」yourtagname「='firsttag' 和 」yourtagname2「='secondtag'」 若要指定容器，例如 「@container='containerName' 和 」Name「='C'」

results_per_page

int

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

timeout

int

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

傳回

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

傳回類型

ItemPaged[FilteredBlob]

from_connection_string

從連接字串建立 BlobServiceClient。

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

參數

conn_str

str

必要

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

credential

預設值: None

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

傳回

Blob 服務用戶端。

傳回類型

BlobServiceClient

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(container: ContainerProperties | str, blob: BlobProperties | str, snapshot: Dict[str, Any] | str | None = None, *, version_id: str | None = None) -> BlobClient

參數

container

str 或 ContainerProperties

必要

Blob 所在的容器。 這可以是容器的名稱或 ContainerProperties 的實例。

blob

str 或 BlobProperties

必要

要與其互動的 Blob。 這可以是 Blob 的名稱或 BlobProperties 的實例。

snapshot

str 或 dict(str, Any)

預設值: None

要在其上運作的選擇性 Blob 快照集。 這可以是快照集的識別碼，或 所 create_snapshot 傳回的字典輸出。

version_id

str

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

傳回

BlobClient。

傳回類型

BlobClient

get_container_client

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

容器不需要已經存在。

get_container_client(container: ContainerProperties | str) -> ContainerClient

參數

container

str 或 ContainerProperties

必要

容器。 這可以是容器的名稱或 ContainerProperties 的實例。

傳回

ContainerClient。

傳回類型

ContainerClient

get_service_properties

取得儲存體帳戶 Blob 服務的屬性，包括 Azure 儲存體分析。

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

參數

timeout

int

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

傳回

物件，包含 Blob 服務屬性，例如分析記錄、小時/分鐘計量、cors 規則等。

傳回類型

Dict[str, Any]

get_service_stats

擷取與 Blob 服務的複寫相關的統計資料。

只有在儲存體帳戶啟用讀取權限異地備援複寫時，才能使用。

有了地理備援複寫，Azure 儲存體會以持久的方式在兩個位置維護您的資料。 在這兩個位置中，Azure 儲存體會持續維護狀況良好的多個資料複本。 您讀取、建立、更新或刪除資料的位置是「主要」儲存體帳戶的位置。 主要位置存在於您透過 Azure 管理 Azure 傳統入口網站建立帳戶時所選擇的區域，例如美國中北部。 資料複寫的目標位置是「次要」位置。 次要位置是根據主要的位置自動判斷而來，它是與主要位置位於相同地區的第二個資料中心。 當儲存體帳戶啟用「讀取權限的地理備援複寫」時，可從次要位置使用唯讀權限。

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

參數

timeout

int

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

傳回

blob 服務的統計資料。

傳回類型

Dict[str, Any]

get_user_delegation_key

為了簽署 SAS 權杖的目的，取得使用者委派金鑰。 權杖認證必須存在於服務物件上，此要求才能成功。

get_user_delegation_key(key_start_time: datetime, key_expiry_time: datetime, **kwargs: Any) -> UserDelegationKey

參數

key_start_time

datetime

必要

日期時間值。 指出金鑰何時生效。

key_expiry_time

datetime

必要

日期時間值。 指出金鑰何時停止有效。

timeout

int

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

傳回

使用者委派金鑰。

傳回類型

UserDelegationKey

list_containers

傳回產生器，以列出指定帳戶下的容器。

產生器會延遲遵循服務傳回的接續權杖，並在傳回所有容器時停止。

list_containers(name_starts_with: str | None = None, include_metadata: bool | None = False, **kwargs) -> ItemPaged[ContainerProperties]

參數

name_starts_with

str

必要

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

include_metadata

bool

必要

指定要在回應中傳回的容器中繼資料。 預設值為 [False] 。

include_deleted

bool

指定要在回應中傳回的已刪除容器。 這是針對已啟用容器還原的帳戶。 預設值為 [False] 。 .. versionadded：： 12.4.0

include_system

bool

指定應該包含系統容器的旗標。 .. versionadded：：12.10.0

results_per_page

int

每個 API 呼叫要擷取的容器名稱數目上限。 如果要求未指定伺服器，最多會傳回 5,000 個專案。

timeout

int

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

傳回

ContainerProperties 的可反覆運算 (自動分頁) 。

傳回類型

ItemPaged[ContainerProperties]

set_service_properties

設定儲存體帳戶 Blob 服務的屬性，包括 Azure 儲存體分析。

如果專案 (例如，analytics_logging) 保留為 None，則會保留該服務上的現有設定。

set_service_properties(analytics_logging: BlobAnalyticsLogging | None = None, hour_metrics: Metrics | None = None, minute_metrics: Metrics | None = None, cors: List[CorsRule] | None = None, target_version: str | None = None, delete_retention_policy: RetentionPolicy | None = None, static_website: StaticWebsite | None = None, **kwargs) -> None

參數

analytics_logging

BlobAnalyticsLogging

必要

將 Azure Analytics 記錄設定分組。

hour_metrics

Metrics

必要

小時計量設定會提供依 API 分組的要求統計資料摘要，以 Blob 的每小時匯總方式分組。

minute_metrics

Metrics

必要

分鐘計量設定會針對 Blob 提供每分鐘的要求統計資料。

cors

list[CorsRule]

必要

您可以在清單中包含最多五個 CorsRule 元素。 如果指定了空白清單，則會刪除所有 CORS 規則，而且會停用服務的 CORS。

target_version

str

必要

指出未指定連入要求版本時，用於要求的預設版本。

delete_retention_policy

RetentionPolicy

必要

刪除保留原則會指定是否保留已刪除的 Blob。 它也會指定要保留的 Blob 天數和版本。

static_website

StaticWebsite

必要

指定是否啟用靜態網站功能，如果是，則表示要使用的索引檔和 404 錯誤檔。

timeout

int

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

傳回類型

None

undelete_container

還原虛刪除的容器。

只有在刪除保留原則中所設定的指定天數內使用時，作業才會成功。

12.4.0 版的新功能：此作業是在 API 版本 '2019-12-12' 中引進。

undelete_container(deleted_container_name: str, deleted_container_version: str, **kwargs: Any) -> ContainerClient

參數

deleted_container_name

str

必要

指定要還原的已刪除容器名稱。

deleted_container_version

str

必要

指定要還原的已刪除容器版本。

timeout

int

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

傳回

未刪除的 ContainerClient。

傳回類型

ContainerClient

屬性

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