共用方式為


BlobClient 類別

與特定 Blob 互動的用戶端,雖然該 Blob 可能還不存在。

繼承
azure.storage.blob._shared.base_client_async.AsyncStorageAccountHostsMixin
BlobClient
azure.storage.blob._blob_client.BlobClient
BlobClient
azure.storage.blob._encryption.StorageEncryptionMixin
BlobClient

建構函式

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

參數

account_url
str
必要

儲存體帳戶的 URI。 若要在 Blob 的完整 URI 下建立用戶端,請使用 from_blob_url classmethod。

container_name
str
必要

Blob 的容器名稱。

blob_name
str
必要

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

snapshot
str
預設值: None

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

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。

version_id
str

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

方法

abort_copy

中止進行中的複製作業。

這會保留長度為零和完整中繼資料的目的地 Blob。 如果複製作業已經結束,這會引發錯誤。

acquire_lease

要求新的租用。

如果 Blob 沒有作用中的租用,Blob 服務會在 Blob 上建立租用,並傳回新的租用。

append_block

將新的資料區塊認可至現有附加 Blob 的結尾。

append_block_from_url

建立要認可為 Blob 一部分的新區塊,其中內容是從來源 URL 讀取。

clear_page

清除頁面範圍。

close

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

commit_block_list

認可封鎖清單作業會指定組成 Blob 的區塊識別碼清單,以寫入 Blob。

create_append_blob

建立新的附加 Blob。 此作業會建立新的 0 長度附加 Blob。 任何現有 Blob 的內容會以新初始化的附加 Blob 覆寫。 若要將內容新增至附加 Blob,請呼叫 append_blockappend_block_from_url 方法。

create_page_blob

建立指定大小的新分頁 Blob。

create_snapshot

建立 Blob 的快照集。

快照集是在某個點時間取得的唯讀 Blob 版本。 它可以讀取、複製或刪除,但無法修改。 快照集提供在某個時間點備份 Blob 的方法。

Blob 的快照集的名稱與建立快照集的基底 Blob 名稱相同,並附加 DateTime 值來指出快照集的擷取時間。

delete_blob

將指定的 Blob 標記為刪除。

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

如果服務已啟用刪除保留原則,此作業會虛刪除 Blob,並將 Blob 保留指定的天數。 在指定的天數之後,Blob 的資料會在垃圾收集期間從服務中移除。 虛刪除的 Blob 可透過 list_blobs 指定 include=['deleted'] 選項來存取。 您可以使用作業還原 <xref:azure.storage.blob.aio.undelete> 虛刪除的 Blob。

delete_immutability_policy

刪除不變性原則作業會刪除 Blob 上的不變性原則。

12.10.0 版的新功能:此作業是在 API 版本 '2020-10-02' 中引進。

download_blob

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

exists

如果 Blob 存在具有已定義參數,則傳回 True,否則會傳回 False。

from_blob_url

從 Blob URL 建立 BlobClient。 這不支援 Blob 名稱中有 '/' 的自訂 Blob URL。

from_connection_string

從連接字串建立 BlobClient。

get_account_information

取得與 Blob 所在儲存體帳戶相關的資訊。

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

get_blob_properties

傳回 Blob 之所有使用者定義的中繼資料、標準 HTTP 屬性及系統屬性。 但不會傳回 Blob 的內容。

get_blob_tags

取得標籤作業可讓使用者取得 Blob 或特定 Blob 版本上的標記,但無法取得快照集。

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

get_block_list

取得區塊清單作業會擷取區塊清單,這些區塊已上傳為區塊 Blob 的一部分。

get_page_range_diff_for_managed_disk

傳回受控磁片或快照集的有效頁面範圍清單。

注意

這項作業僅適用于受控磁片帳戶。

12.2.0 版的新功能:此作業是在 API 版本 '2019-07-07' 中引進。

get_page_ranges

已淘汰:傳回分頁 Blob 或分頁 Blob 快照集的有效頁面範圍清單。

list_page_ranges

傳回分頁 Blob 或分頁 Blob 快照集的有效頁面範圍清單。 如果指定 了previous_snapshot ,結果將會是目標 Blob 與上一個快照集之間變更的差異。

query_blob

可讓使用者藉由提供簡單的查詢運算式,在 Blob/或 Blob 快照集資料上選取/專案。 此作業會傳回 BlobQueryReader,使用者必須使用 readall () 或 readinto () 來取得查詢資料。

resize_blob

將分頁 Blob 調整為指定的大小。

如果指定的值小於 Blob 目前的大小,則會清除大於指定值的所有分頁。

seal_append_blob

密封作業會密封附加 Blob,使其成為唯讀。

12.4.0 版的新功能。

set_blob_metadata

將 Blob 的使用者定義中繼資料設定為一或多個名稱/值組。

set_blob_tags

[設定標籤] 作業可讓使用者在 Blob 或特定 Blob 版本上設定標籤,但無法設定快照集。 每次呼叫此作業都會取代附加至 Blob 的所有現有標籤。 若要從 Blob 中移除所有標記,請呼叫此作業,但未設定任何標記。

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

set_http_headers

在 Blob 上設定系統屬性。

如果已為content_settings設定一個屬性,則會覆寫所有屬性。

set_immutability_policy

[設定不變性原則] 作業會在 Blob 上設定不變性原則。

12.10.0 版的新功能:此作業是在 API 版本 '2020-10-02' 中引進。

set_legal_hold

[設定合法保存] 作業會設定 Blob 上的合法保留。

12.10.0 版的新功能:此作業是在 API 版本 '2020-10-02' 中引進。

set_premium_page_blob_tier

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

set_sequence_number

設定 Blob 序號。

set_standard_blob_tier

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

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

stage_block

建立新區塊,並認可為 Blob 的一部分。

stage_block_from_url

建立要認可的新區塊,做為從 URL 讀取內容的 Blob 的一部分。

start_copy_from_url

從指定的 URL 複製 Blob。

此作業會傳回包含 copy_statuscopy_id的字典,可用來檢查複製作業的狀態或中止。 如果複本以同步方式完成,copy_status如果複本以非同步方式啟動,則為 「成功」。 針對非同步複製,可以輪詢 get_blob_properties 方法並檢查複製狀態來檢查狀態。 將 requires_sync 設為 True,以強制複製為同步。 Blob 服務將盡全力複製 Blob。

複製作業的來源 Blob 可能是區塊 Blob、附加 Blob 或分頁 Blob。 如果目的地 Blob 已經存在,則必須使用與來源 Blob 相同的 Blob 類型。 所有現有的目的地 Blob 都會被覆寫。 複製作業進行時,無法修改目的地 Blob。

從分頁 Blob 複製時,Blob 服務會建立來源 Blob 長度的目的地分頁 Blob,一開始包含所有零。 然後列舉來源頁面範圍,並複製非空白的範圍。

對於區塊 Blob 或附加 Blob,Blob 服務會在從此作業傳回之前,先建立長度為零的已認可 Blob。 從區塊 Blob 複製時,會複製所有認可的區塊及其區塊識別碼。 未認可的區塊不會複製。 在複製作業結束時,目的地 Blob 會擁有與來源相同的認可區塊計數。

從附加 Blob 複製時,會複製所有認可的區塊。 在複製作業結束時,目的地 Blob 會擁有與來源相同的認可區塊計數。

undelete_blob

還原虛刪除的 Blob 或快照集。

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

如果已啟用 Blob 版本設定,就無法使用此方法還原基底 Blob。 start_copy_from_url請改用您想要升級至目前版本的 Blob 版本的 URL。

upload_blob

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

upload_blob_from_url

建立新的區塊 Blob,其中 Blob 的內容是從指定的 URL 讀取。 現有 Blob 的內容會以新的 Blob 覆寫。

upload_page

[上傳頁面] 作業會將一系列的頁面寫入分頁 Blob。

upload_pages_from_url

[上傳頁面] 作業會將一系列頁面寫入至從 URL 讀取內容的分頁 Blob。

abort_copy

中止進行中的複製作業。

這會保留長度為零和完整中繼資料的目的地 Blob。 如果複製作業已經結束,這會引發錯誤。

async abort_copy(copy_id: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> None

參數

copy_id
strBlobProperties
必要

要中止的複製作業。 這可以是識別碼或 BlobProperties 的實例。

傳回類型

acquire_lease

要求新的租用。

如果 Blob 沒有作用中的租用,Blob 服務會在 Blob 上建立租用,並傳回新的租用。

async acquire_lease(lease_duration: int = -1, lease_id: str | None = None, **kwargs: Any) -> 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 的比對條件。

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

傳回

BlobLeaseClient 物件。

傳回類型

append_block

將新的資料區塊認可至現有附加 Blob 的結尾。

async append_block(data: bytes | str | Iterable[AnyStr] | IO[AnyStr], length: int | None = None, **kwargs) -> Dict[str, str | datetime | int]

參數

data
必要

區塊的內容。

length
int
必要

區塊的大小,以位元組為單位。

validate_content
bool

如果為 true,則計算區塊內容的 MD5 雜湊。 儲存體服務會檢查與已傳送雜湊一起抵達之內容的雜湊。 如果使用 HTTP 而非 HTTPs,這主要是在使用 HTTP 而非 HTTPs 時偵測連線上的 bitflip,因為 HTTPs (預設) ,將會經過驗證。 請注意,此 MD5 雜湊不會隨 Blob 儲存。

maxsize_condition
int

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

appendpos_condition
int

選擇性條件式標頭,僅用於附加區塊作業。 數位,表示要比較的位元組位移。 只有在附加位置等於這個數位時,附加區塊才會成功。 如果沒有,要求將會失敗,並出現 AppendPositionConditionNotMet 錯誤, (HTTP 狀態碼 412 - 前置條件失敗) 。

lease
BlobLeaseClientstr

如果 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 版的新功能。

encoding
str

預設為 UTF-8。

cpk
CustomerProvidedEncryptionKey

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

encryption_scope
str

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

12.2.0 版的新功能。

timeout
int

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

傳回

Blob 更新的屬性聽寫 (Etag、上次修改、附加位移、認可區塊計數) 。

傳回類型

append_block_from_url

建立要認可為 Blob 一部分的新區塊,其中內容是從來源 URL 讀取。

async append_block_from_url(copy_source_url: str, source_offset: int | None = None, source_length: int | None = None, **kwargs) -> Dict[str, str | datetime | int]

參數

copy_source_url
str
必要

來源資料的 URL。 它可以指向任何 Azure Blob 或檔案,也就是公用或已附加共用存取簽章。

source_offset
int
必要

這表示必須從複製來源擷取 (包含) 位元組範圍的開頭。

source_length
int
必要

這表示必須從複製來源擷取的位元組範圍結尾。

source_content_md5
bytearray

如果指定,服務會計算區塊內容的 MD5 雜湊,並與此值進行比較。

maxsize_condition
int

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

appendpos_condition
int

選擇性條件式標頭,僅適用于附加區塊作業。 數位,表示要比較的位元組位移。 只有在附加位置等於這個數位時,附加區塊才會成功。 如果沒有,要求將會失敗,並出現 AppendPositionConditionNotMet 錯誤, (HTTP 狀態碼 412 - 前置條件失敗) 。

lease
BlobLeaseClientstr

如果 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 版的新功能。

source_if_modified_since
datetime

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

source_if_unmodified_since
datetime

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

source_etag
str

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

source_match_condition
MatchConditions

要用於 etag 的來源比對條件。

cpk
CustomerProvidedEncryptionKey

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

encryption_scope
str

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

12.2.0 版的新功能。

timeout
int

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

source_authorization
str

使用用戶端密碼以服務主體身分驗證以存取來源 Blob。 請確定 「bearer」 是source_authorization字串的前置詞。

clear_page

清除頁面範圍。

async clear_page(offset: int, length: int, **kwargs: Any) -> Dict[str, str | datetime]

參數

offset
int
必要

要用於寫入 Blob 區段的位元組範圍開始。 頁面必須對齊 512 位元組界限,開始位移必須是 512 的模數,長度必須是 512 的模數。

length
int
必要

要用於寫入 Blob 區段的位元組數目。 頁面必須對齊 512 位元組界限,開始位移必須是 512 的模數,長度必須是 512 的模數。

lease
BlobLeaseClientstr

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

if_sequence_number_lte
int

如果 Blob 的序號小於或等於指定的值,則要求會繼續;否則會失敗。

if_sequence_number_lt
int

如果 Blob 的序號小於指定的值,則要求會繼續;否則會失敗。

if_sequence_number_eq
int

如果 Blob 的序號等於指定的值,要求就會繼續;否則會失敗。

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 使用客戶提供的金鑰。 在要求中提供加密金鑰本身時,必須建立安全連線以傳輸金鑰。

timeout
int

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

傳回

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

傳回類型

close

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

async close()

commit_block_list

認可封鎖清單作業會指定組成 Blob 的區塊識別碼清單,以寫入 Blob。

async commit_block_list(block_list: List[BlobBlock], content_settings: ContentSettings | None = None, metadata: Dict[str, str] | None = None, **kwargs) -> Dict[str, str | datetime]

參數

block_list
list
必要

Blockblobs 的清單。

content_settings
ContentSettings
必要

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

metadata
dict[str, str]
必要

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

tags
dict(str, str)

與 Blob 相關聯的名稱/值組作為標記。 標籤會區分大小寫。 標記集最多可以包含 10 個標籤。 標籤索引鍵必須介於 1 到 128 個字元之間,而標籤值必須介於 0 到 256 個字元之間。 有效的標記索引鍵和值字元包括:小寫和大寫字母、 digits (0-9) , space >><< () , plus (+) , 減 (-) , period (.) , solidus (/) , 冒號 (:) , equals (=) , 底線 (_)

12.4.0 版的新功能。

lease
BlobLeaseClientstr

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

immutability_policy
ImmutabilityPolicy

指定 Blob、Blob 快照集或 Blob 版本的不變性原則。

12.10.0 版的新功能:這是在 API 版本 '2020-10-02' 中引進的。

legal_hold
bool

指定是否應該在 Blob 上設定法律保留。

12.10.0 版的新功能:這是在 API 版本 '2020-10-02' 中引進的。

validate_content
bool

如果為 true,則計算頁面內容的 MD5 雜湊。 儲存體服務會檢查已使用已傳送之雜湊抵達的內容雜湊。 這主要是在使用 HTTP 而不是 HTTPs 時偵測線路上的 bitflip,因為 HTTPs (預設) ,將會進行驗證。 請注意,此 MD5 雜湊不會隨 Blob 儲存。

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 版的新功能。

standard_blob_tier
StandardBlobTier

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

cpk
CustomerProvidedEncryptionKey

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

encryption_scope
str

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

12.2.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

create_append_blob

建立新的附加 Blob。 此作業會建立新的 0 長度附加 Blob。 任何現有 Blob 的內容會以新初始化的附加 Blob 覆寫。 若要將內容新增至附加 Blob,請呼叫 append_blockappend_block_from_url 方法。

async create_append_blob(content_settings: ContentSettings | None = None, metadata: Dict[str, str] | None = None, **kwargs: Any) -> Dict[str, str | datetime]

參數

content_settings
ContentSettings
必要

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

metadata
dict(str, str)
必要

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

tags
dict(str, str)

與 Blob 相關聯的名稱/值組作為標記。 標籤會區分大小寫。 標記集最多可以包含 10 個標籤。 標籤索引鍵必須介於 1 到 128 個字元之間,而標籤值必須介於 0 到 256 個字元之間。 有效的標記索引鍵和值字元包括:小寫和大寫字母、 digits (0-9) , space >><< () , plus (+) , 減 (-) , period (.) , solidus (/) , 冒號 (:) , equals (=) , 底線 (_)

12.4.0 版的新功能。

immutability_policy
ImmutabilityPolicy

指定 Blob、Blob 快照集或 Blob 版本的不變性原則。

12.10.0 版的新功能:這是在 API 版本 '2020-10-02' 中引進的。

legal_hold
bool

指定是否應該在 Blob 上設定法律保留。

12.10.0 版的新功能:這是在 API 版本 '2020-10-02' 中引進的。

lease
BlobLeaseClientstr

如果 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 的比對條件。

cpk
CustomerProvidedEncryptionKey

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

encryption_scope
str

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

12.2.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

create_page_blob

建立指定大小的新分頁 Blob。

async create_page_blob(size: int, content_settings: ContentSettings | None = None, metadata: Dict[str, str] | None = None, premium_page_blob_tier: str | PremiumPageBlobTier | None = None, **kwargs) -> Dict[str, str | datetime]

參數

size
int
必要

這會指定分頁 Blob 的大小上限,最多 1 TB。 分頁 Blob 大小必須符合 512 個位元組的界限。

content_settings
ContentSettings
必要

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

metadata
dict(str, str)
必要

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

premium_page_blob_tier
PremiumPageBlobTier
必要

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

tags
dict(str, str)

與 Blob 相關聯的名稱/值組作為標記。 標籤會區分大小寫。 標記集最多可以包含 10 個標籤。 標籤索引鍵必須介於 1 到 128 個字元之間,而標籤值必須介於 0 到 256 個字元之間。 有效的標記索引鍵和值字元包括:小寫和大寫字母、 digits (0-9) , space >><< () , plus (+) , 減 (-) , period (.) , solidus (/) , 冒號 (:) , equals (=) , 底線 (_)

12.4.0 版的新功能。

sequence_number
int

僅適用于分頁 Blob。 序號是使用者控制的值,可用來追蹤要求。 序號的值必須介於 0 到 2^63 - 1 之間。預設值為 0。

lease
BlobLeaseClientstr

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

immutability_policy
ImmutabilityPolicy

指定 Blob、Blob 快照集或 Blob 版本的不變性原則。

12.10.0 版的新功能:這是在 API 版本 '2020-10-02' 中引進的。

legal_hold
bool

指定是否應該在 Blob 上設定法律保留。

12.10.0 版的新功能:這是在 API 版本 '2020-10-02' 中引進的。

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 的比對條件。

cpk
CustomerProvidedEncryptionKey

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

encryption_scope
str

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

12.2.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

create_snapshot

建立 Blob 的快照集。

快照集是在某個點時間取得的唯讀 Blob 版本。 它可以讀取、複製或刪除,但無法修改。 快照集提供在某個時間點備份 Blob 的方法。

Blob 的快照集的名稱與建立快照集的基底 Blob 名稱相同,並附加 DateTime 值來指出快照集的擷取時間。

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

參數

metadata
dict(str, str)
必要

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

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 版的新功能。

lease
BlobLeaseClientstr

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

cpk
CustomerProvidedEncryptionKey

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

encryption_scope
str

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

12.2.0 版的新功能。

timeout
int

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

傳回

Blob 更新的屬性聽寫 (快照集識別碼、Etag 和上次修改) 。

傳回類型

delete_blob

將指定的 Blob 標記為刪除。

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

如果服務已啟用刪除保留原則,此作業會虛刪除 Blob,並將 Blob 保留指定的天數。 在指定的天數之後,Blob 的資料會在垃圾收集期間從服務中移除。 虛刪除的 Blob 可透過 list_blobs 指定 include=['deleted'] 選項來存取。 您可以使用作業還原 <xref:azure.storage.blob.aio.undelete> 虛刪除的 Blob。

async delete_blob(delete_snapshots: str = None, **kwargs: Any) -> None

參數

delete_snapshots
str
必要

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

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

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

version_id
str

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

12.4.0 版的新功能。

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

lease
BlobLeaseClientstr

如果 Blob 具有作用中租用,則為必要項目。 如果指定,delete_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 版的新功能。

timeout
int

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

傳回類型

delete_immutability_policy

刪除不變性原則作業會刪除 Blob 上的不變性原則。

12.10.0 版的新功能:此作業是在 API 版本 '2020-10-02' 中引進。

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

參數

timeout
int

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

傳回

Blob 標記的索引鍵值組。

傳回類型

download_blob

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

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

參數

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
BlobLeaseClientstr

如果 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 (串流物件)

傳回類型

exists

如果 Blob 存在具有已定義參數,則傳回 True,否則會傳回 False。

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

參數

version_id
str

版本識別碼參數是不透明的 DateTime 值,當存在時,會指定 Blob 的版本,以檢查它是否存在。

timeout
int

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

傳回

boolean

傳回類型

from_blob_url

從 Blob URL 建立 BlobClient。 這不支援 Blob 名稱中有 '/' 的自訂 Blob URL。

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

參數

blob_url
str
必要

Blob 的完整端點 URL,包括使用 SAS 權杖和快照集。 這可能是主要端點或次要端點,視目前 location_mode而定。

credential
Optional[Union[str, Dict[str, str], <xref:"AzureNamedKeyCredential">, <xref:"AzureSasCredential">, <xref:"TokenCredential">]] <xref:./>
預設值: None

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

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

要在其上運作的選擇性 Blob 快照集。 這可以是快照集識別碼字串或從 create_snapshot 傳回的回應。 如果指定,這會覆寫 URL 中的快照集。

version_id
str

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

傳回

Blob 用戶端。

傳回類型

from_connection_string

從連接字串建立 BlobClient。

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

參數

conn_str
str
必要

Azure 儲存體帳戶連接字串。

container_name
str
必要

Blob 的容器名稱。

blob_name
str
必要

要與其互動的 Blob 名稱。

snapshot
str
預設值: None

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

credential
Optional[Union[str, Dict[str, str], <xref:"AzureNamedKeyCredential">, <xref:"AzureSasCredential">, <xref:"TokenCredential">]] <xref:./>
預設值: None

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

version_id
str

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

傳回

Blob 用戶端。

傳回類型

get_account_information

取得與 Blob 所在儲存體帳戶相關的資訊。

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

async get_account_information(**kwargs: int | None) -> Dict[str, str]

傳回

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

傳回類型

get_blob_properties

傳回 Blob 之所有使用者定義的中繼資料、標準 HTTP 屬性及系統屬性。 但不會傳回 Blob 的內容。

async get_blob_properties(**kwargs: Any) -> BlobProperties

參數

lease
BlobLeaseClientstr

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

version_id
str

版本識別碼參數是不透明的 DateTime 值,當存在時,會指定要取得屬性的 Blob 版本。

12.4.0 版的新功能。

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

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 使用客戶提供的金鑰。 在要求中提供加密金鑰本身時,必須建立安全連線以傳輸金鑰。

timeout
int

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

傳回

BlobProperties

傳回類型

get_blob_tags

取得標籤作業可讓使用者取得 Blob 或特定 Blob 版本上的標記,但無法取得快照集。

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

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

參數

version_id
str

版本識別碼參數是不透明的 DateTime 值,當存在時,會指定要加入標記的 Blob 版本。

if_tags_match_condition
str

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

lease
BlobLeaseClientstr

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

timeout
int

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

傳回

Blob 標記的索引鍵值組。

傳回類型

get_block_list

取得區塊清單作業會擷取區塊清單,這些區塊已上傳為區塊 Blob 的一部分。

async get_block_list(block_list_type: str | None = 'committed', **kwargs: Any) -> Tuple[List[BlobBlock], List[BlobBlock]]

參數

block_list_type
str
必要

指定傳回認可的區塊清單、未認可的區塊清單,或兩種清單一起傳回。 可能的值包括:'committed'、'uncommitted'、'all'

lease
BlobLeaseClientstr

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

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

傳回

兩個清單的元組 - 已認可和未認可的區塊

傳回類型

get_page_range_diff_for_managed_disk

傳回受控磁片或快照集的有效頁面範圍清單。

注意

這項作業僅適用于受控磁片帳戶。

12.2.0 版的新功能:此作業是在 API 版本 '2019-07-07' 中引進。

async get_page_range_diff_for_managed_disk(previous_snapshot_url: str, offset: int | None = None, length: int | None = None, **kwargs) -> Tuple[List[Dict[str, int]], List[Dict[str, int]]]

參數

previous_snapshot_url
必要

指定先前受控磁片快照集的 URL。 回應只會包含目標 Blob 與其先前快照集之間變更的頁面。

offset
int
必要

要用於取得有效頁面範圍的位元組範圍開始。 如果未指定任何長度,則會搜尋位移之後的所有位元組。 頁面必須對齊 512 位元組界限,開始位移必須是 512 的模數,長度必須是 512 的模數。

length
int
必要

用於取得有效頁面範圍的位元組數目。 如果指定長度,則必須提供位移。 此範圍會傳回從位移開始到指定長度的有效頁面範圍。 頁面必須對齊 512 位元組界限,開始位移必須是 512 的模數,長度必須是 512 的模數。

lease
BlobLeaseClientstr

如果 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 的比對條件。

timeout
int

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

傳回

具有 'start' 和 'end' 索引鍵之兩個頁面範圍的 Tuple。 第一個專案是填滿的頁面範圍,第 2 個元素會清除頁面範圍。

傳回類型

get_page_ranges

已淘汰:傳回分頁 Blob 或分頁 Blob 快照集的有效頁面範圍清單。

async get_page_ranges(offset: int | None = None, length: int | None = None, previous_snapshot_diff: str | Dict[str, Any] | None = None, **kwargs) -> Tuple[List[Dict[str, int]], List[Dict[str, int]]]

參數

offset
int
必要

要用於取得有效頁面範圍的位元組範圍開始。 如果未指定任何長度,則會搜尋位移之後的所有位元組。 頁面必須對齊 512 位元組界限,開始位移必須是 512 的模數,長度必須是 512 的模數。

length
int
必要

用於取得有效頁面範圍的位元組數目。 如果指定長度,則必須提供位移。 此範圍會傳回從位移開始到指定長度的有效頁面範圍。 頁面必須對齊 512 位元組界限,開始位移必須是 512 的模數,長度必須是 512 的模數。

previous_snapshot_diff
str
必要

快照集差異參數,其中包含不透明的 DateTime 值,指定要與較新的快照集或目前 Blob 比較先前的 Blob 快照集。

lease
BlobLeaseClientstr

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

傳回

具有 'start' 和 'end' 索引鍵之兩個頁面範圍的 Tuple。 第一個專案是填滿的頁面範圍,第 2 個元素會清除頁面範圍。

傳回類型

list_page_ranges

傳回分頁 Blob 或分頁 Blob 快照集的有效頁面範圍清單。 如果指定 了previous_snapshot ,結果將會是目標 Blob 與上一個快照集之間變更的差異。

list_page_ranges(*, offset: int | None = None, length: int | None = None, previous_snapshot: str | Dict[str, Any] | None = None, **kwargs: Any) -> AsyncItemPaged[PageRange]

參數

offset
int

要用於取得有效頁面範圍的位元組範圍開始。 如果未指定任何長度,則會搜尋位移之後的所有位元組。 頁面必須對齊 512 位元組界限,開始位移必須是 512 的模數,長度必須是 512 的模數。

length
int

用於取得有效頁面範圍的位元組數目。 如果指定長度,則必須提供位移。 此範圍會傳回從位移開始到指定長度的有效頁面範圍。 頁面必須對齊 512 位元組界限,開始位移必須是 512 的模數,長度必須是 512 的模數。

previous_snapshot
strDict[str, Any]

快照集值,指定回應只會包含目標 Blob 與先前快照集之間變更的頁面。 已變更的頁面包括已更新和清除的頁面。 只要 previous_snapshot 指定的快照集是兩者中的較舊,目標 Blob 就可能是快照集。

lease
BlobLeaseClientstr

如果 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 版的新功能。

results_per_page
int

每個 API 呼叫擷取的頁面範圍上限。

timeout
int

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

傳回

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

傳回類型

query_blob

可讓使用者藉由提供簡單的查詢運算式,在 Blob/或 Blob 快照集資料上選取/專案。 此作業會傳回 BlobQueryReader,使用者必須使用 readall () 或 readinto () 來取得查詢資料。

query_blob(query_expression: str, **kwargs: Any) -> BlobQueryReader

參數

query_expression
str
必要

必要。 查詢語句。 如需詳細資訊,請參閱 https://learn.microsoft.com/azure/storage/blobs/query-acceleration-sql-reference

on_error
Callable[BlobQueryError]

在服務傳回的任何處理錯誤上呼叫的函式。

blob_format
DelimitedTextDialectDelimitedJsonDialectQuickQueryDialectstr

選擇性。 定義目前儲存在 Blob 中的資料序列化。 預設值是將 Blob 資料視為以預設方言格式化的 CSV 資料。 這可以使用自訂 DelimitedTextDialect 或 DelimitedJsonDialect 或 「ParquetDialect」 (傳遞為字串或列舉) 來覆寫。 這些方言可以透過各自的類別、QuickQueryDialect 列舉或字串傳遞

output_format
DelimitedTextDialectDelimitedJsonDialectlist[ArrowDialect] 或 QuickQueryDialectstr

選擇性。 定義資料流程的輸出序列化。 根據預設,資料會以 Blob (Parquet 格式表示,預設為 DelimitedTextDialect) 。 藉由提供輸出格式,Blob 資料將會根據該設定檔重新格式化。 這個值可以是 DelimitedTextDialect 或 DelimitedJsonDialect 或 ArrowDialect。 這些方言可以透過各自的類別、QuickQueryDialect 列舉或字串傳遞

lease
BlobLeaseClientstr

如果 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 使用客戶提供的金鑰。 在要求中提供加密金鑰本身時,必須建立安全連線才能傳輸金鑰。

timeout
int

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

傳回

BlobQueryReader (串流物件)

傳回類型

resize_blob

將分頁 Blob 調整為指定的大小。

如果指定的值小於 Blob 目前的大小,則會清除大於指定值的所有分頁。

async resize_blob(size: int, **kwargs: Any) -> Dict[str, str | datetime]

參數

size
int
必要

用來調整 Blob 大小的大小。 分頁 Blob 的大小上限為 1 TB。 分頁 Blob 大小必須符合 512 個位元組的界限。

lease
BlobLeaseClientstr

如果 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 版的新功能。

premium_page_blob_tier
PremiumPageBlobTier

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

timeout
int

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

傳回

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

傳回類型

seal_append_blob

密封作業會密封附加 Blob,使其成為唯讀。

12.4.0 版的新功能。

async seal_append_blob(**kwargs) -> Dict[str, str | datetime | int]

參數

appendpos_condition
int

選擇性條件式標頭,僅用於附加區塊作業。 數位,表示要比較的位元組位移。 只有在附加位置等於這個數位時,附加區塊才會成功。 如果沒有,要求將會失敗,並出現 AppendPositionConditionNotMet 錯誤, (HTTP 狀態碼 412 - 前置條件失敗) 。

lease
BlobLeaseClientstr

如果 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 的比對條件。

timeout
int

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

傳回

Blob 更新的屬性聽寫 (Etag、上次修改、附加位移、認可區塊計數) 。

傳回類型

set_blob_metadata

將 Blob 的使用者定義中繼資料設定為一或多個名稱/值組。

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

參數

metadata
dict(str, str)
必要

包含名稱和值組的聽寫。 每次呼叫這項作業都會取代附加至 Blob 的所有現存中繼資料。 若要從 Blob 移除所有中繼資料,請呼叫這項作業並且不使用中繼資料標頭。

lease
BlobLeaseClientstr

如果 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 使用客戶提供的金鑰。 在要求中提供加密金鑰本身時,必須建立安全連線才能傳輸金鑰。

encryption_scope
str

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

12.2.0 版的新功能。

timeout
int

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

傳回

Blob 更新的屬性聽寫 (Etag 和上次修改)

set_blob_tags

[設定標籤] 作業可讓使用者在 Blob 或特定 Blob 版本上設定標籤,但無法設定快照集。 每次呼叫此作業都會取代附加至 Blob 的所有現有標籤。 若要從 Blob 中移除所有標記,請呼叫此作業,但未設定任何標記。

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

async set_blob_tags(tags: Dict[str, str] | None = None, **kwargs: Any) -> Dict[str, Any]

參數

tags
dict(str, str)
必要

與 Blob 相關聯的名稱/值組作為標記。 標記會區分大小寫。 標記集最多可以包含 10 個標記。 標籤索引鍵必須介於 1 到 128 個字元之間,而標籤值必須介於 0 到 256 個字元之間。 有效的標記索引鍵和值字元包括:小寫和大寫字母、 digits (0-9) , space >><< () , plus (+) , minus (-) , period (.) , solidus (/) , 冒號 (:) , equals (=) , 底線 (_)

version_id
str

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

validate_content
bool

如果為 true,則計算標籤內容的 MD5 雜湊。 儲存體服務會檢查與已傳送雜湊一起抵達之內容的雜湊。 如果使用 HTTP 而非 HTTPs,這主要是在使用 HTTP 而非 HTTPs 時偵測連線上的 bitflip,因為 HTTPs (預設) ,將會經過驗證。 請注意,此 MD5 雜湊不會隨 Blob 儲存。

if_tags_match_condition
str

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

lease
BlobLeaseClientstr

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

timeout
int

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

傳回

Blob 更新的屬性聽寫 (Etag 和上次修改)

傳回類型

set_http_headers

在 Blob 上設定系統屬性。

如果已為content_settings設定一個屬性,則會覆寫所有屬性。

async set_http_headers(content_settings: ContentSettings | None = None, **kwargs: Any) -> None

參數

content_settings
ContentSettings
必要

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

lease
BlobLeaseClientstr

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

傳回

Blob 更新的屬性聽寫 (Etag 和上次修改)

傳回類型

set_immutability_policy

[設定不變性原則] 作業會在 Blob 上設定不變性原則。

12.10.0 版的新功能:此作業是在 API 版本 '2020-10-02' 中引進。

async set_immutability_policy(immutability_policy: ImmutabilityPolicy, **kwargs: Any) -> Dict[str, str]

參數

immutability_policy
ImmutabilityPolicy
必要

指定 Blob、Blob 快照集或 Blob 版本的不變性原則。

12.10.0 版的新功能:這是在 API 版本 '2020-10-02' 中引進的。

timeout
int

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

傳回

Blob 標記的索引鍵值組。

傳回類型

[設定合法保存] 作業會設定 Blob 上的合法保留。

12.10.0 版的新功能:此作業是在 API 版本 '2020-10-02' 中引進。

async set_legal_hold(legal_hold: bool, **kwargs: Any) -> Dict[str, str | datetime | bool]

參數

legal_hold
bool
必要

如果應該在 Blob 上設定法務保存,則指定 。

timeout
int

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

傳回

Blob 標記的索引鍵值組。

傳回類型

set_premium_page_blob_tier

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

async set_premium_page_blob_tier(premium_page_blob_tier: str | PremiumPageBlobTier, **kwargs: Any) -> None

參數

premium_page_blob_tier
PremiumPageBlobTier
必要

要設定 Blob 的分頁 Blob 層值。 階層會與 Blob 的大小和允許的 IOPS 數目相互關聯。 這只適用于進階儲存體帳戶上的分頁 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 。 此值不會在用戶端上追蹤或驗證。 若要設定用戶端網路逾時,請參閱 這裡

lease
BlobLeaseClientstr

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

傳回類型

set_sequence_number

設定 Blob 序號。

async set_sequence_number(sequence_number_action: str | SequenceNumberAction, sequence_number: str | None = None, **kwargs) -> Dict[str, str | datetime]

參數

sequence_number_action
str
必要

此屬性會指出服務應如何修改 Blob 的序號。 如需相關資訊,請參閱 SequenceNumberAction

sequence_number
str
必要

此屬性會設定 Blob 的序號。 序號是使用者控制的屬性,可用來追蹤要求和管理並行問題。

lease
BlobLeaseClientstr

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

傳回

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

傳回類型

set_standard_blob_tier

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

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

async set_standard_blob_tier(standard_blob_tier: str | StandardBlobTier, **kwargs: Any) -> None

參數

standard_blob_tier
strStandardBlobTier
必要

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

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

lease
BlobLeaseClientstr

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

傳回類型

stage_block

建立新區塊,並認可為 Blob 的一部分。

async stage_block(block_id: str, data: Iterable | IO, length: int | None = None, **kwargs) -> None

參數

block_id
str
必要

識別區塊的字串值。 字串的大小應該小於或等於 64 個位元組。 針對指定的 Blob,每個區塊block_id的大小必須相同。

data
必要

Blob 資料。

length
int
必要

區塊的大小。

validate_content
bool

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

lease
BlobLeaseClientstr

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

encoding
str

預設為 UTF-8。

cpk
CustomerProvidedEncryptionKey

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

encryption_scope
str

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

12.2.0 版的新功能。

timeout
int

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

傳回類型

stage_block_from_url

建立要認可的新區塊,做為從 URL 讀取內容的 Blob 的一部分。

async stage_block_from_url(block_id: str | int, source_url: str, source_offset: int | None = None, source_length: int | None = None, source_content_md5: bytes | bytearray | None = None, **kwargs) -> None

參數

block_id
str
必要

識別區塊的字串值。 字串的大小應該小於或等於 64 個位元組。 針對指定的 Blob,每個區塊block_id的大小必須相同。

source_url
str
必要

URL。

source_offset
int
必要

要用於 區塊的位元組範圍開始。 如果提供來源長度,則必須設定 。

source_length
int
必要

區塊的大小,以位元組為單位。

source_content_md5
bytearray
必要

針對必須從複製來源讀取的位元組範圍指定 md5。

lease
BlobLeaseClientstr

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

cpk
CustomerProvidedEncryptionKey

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

encryption_scope
str

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

12.2.0 版的新功能。

timeout
int

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

source_authorization
str

使用用戶端密碼以服務主體身分驗證以存取來源 Blob。 請確定 「bearer」 是source_authorization字串的前置詞。

傳回類型

start_copy_from_url

從指定的 URL 複製 Blob。

此作業會傳回包含 copy_statuscopy_id的字典,可用來檢查複製作業的狀態或中止。 如果複本以同步方式完成,copy_status如果複本以非同步方式啟動,則為 「成功」。 針對非同步複製,可以輪詢 get_blob_properties 方法並檢查複製狀態來檢查狀態。 將 requires_sync 設為 True,以強制複製為同步。 Blob 服務將盡全力複製 Blob。

複製作業的來源 Blob 可能是區塊 Blob、附加 Blob 或分頁 Blob。 如果目的地 Blob 已經存在,則必須使用與來源 Blob 相同的 Blob 類型。 所有現有的目的地 Blob 都會被覆寫。 複製作業進行時,無法修改目的地 Blob。

從分頁 Blob 複製時,Blob 服務會建立來源 Blob 長度的目的地分頁 Blob,一開始包含所有零。 然後列舉來源頁面範圍,並複製非空白的範圍。

對於區塊 Blob 或附加 Blob,Blob 服務會在從此作業傳回之前,先建立長度為零的已認可 Blob。 從區塊 Blob 複製時,會複製所有認可的區塊及其區塊識別碼。 未認可的區塊不會複製。 在複製作業結束時,目的地 Blob 會擁有與來源相同的認可區塊計數。

從附加 Blob 複製時,會複製所有認可的區塊。 在複製作業結束時,目的地 Blob 會擁有與來源相同的認可區塊計數。

async start_copy_from_url(source_url: str, metadata: Dict[str, str] | None = None, incremental_copy: bool = False, **kwargs: Any) -> Dict[str, str | datetime]

參數

source_url
str
必要

長度上限為 2 KB 的 URL,指定檔案或 Blob。 此值應該像出現在要求 URI 中一樣以 URL 編碼。 如果來源位於另一個帳戶中,則來源必須是公用,或必須透過共用存取簽章進行驗證。 如果來源是公用的,則不需要驗證。 範例:https://myaccount.blob.core.windows.net/mycontainer/myblob

https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=

https://otheraccount.blob.core.windows.net/mycontainer/myblob?sastoken

metadata
dict(str, str)
必要

與 Blob 相關聯的名稱/值組,可做為中繼資料。 如果未指定名稱/值組,作業會將中繼資料從來源 Blob 或檔案複製到目的地 Blob。 如果指定了一或多個名稱/值組,則會使用指定的中繼資料建立目的地 Blob,而且中繼資料不會從來源 Blob 或檔案複製。

incremental_copy
bool
必要

將來源分頁 Blob 的快照集複製到目的地分頁 Blob。 系統會複製快照集,這樣只會將先前複製快照集之間的差異變更傳輸至目的地。 複製的快照集是原始快照集的完整複本,而且可以像往常一樣讀取或複製。 預設為 False。

tags
dict(str, str) 或 Literal["COPY"]

與 Blob 相關聯的名稱/值組作為標記。 標籤會區分大小寫。 標記集最多可以包含 10 個標籤。 標籤索引鍵必須介於 1 到 128 個字元之間,而標籤值必須介於 0 到 256 個字元之間。 有效的標記索引鍵和值字元包括:小寫和大寫字母、 digits (0-9) 、space () >><< 、plus (+) 、減 (-) 、period (.) 、solidus (/) 、冒號 (:) 、等於 (=) 、底線 (_) 。

(區分大小寫) 常值 「COPY」 可以改為傳遞,以從來源 Blob 複製標記。 只有在 incremental_copy=Falserequires_sync=True時,才能使用此選項。

12.4.0 版的新功能。

immutability_policy
ImmutabilityPolicy

指定 Blob、Blob 快照集或 Blob 版本的不變性原則。

12.10.0 版的新功能:這是在 API 版本 '2020-10-02' 中引進的。

legal_hold
bool

指定是否應該在 Blob 上設定法律保留。

12.10.0 版的新功能:這是在 API 版本 '2020-10-02' 中引進的。

source_if_modified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區,則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期,則會假設為 UTC。 只有在指定日期/時間修改來源 Blob 時,才能指定此條件式標頭以複製 Blob。

source_if_unmodified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區,則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期,則會假設為 UTC。 只有在非指定日期/時間修改來源 Blob 時,才能指定此條件式標頭以複製 Blob。

source_etag
str

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

source_match_condition
MatchConditions

要用於 etag 的來源比對條件。

if_modified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區,則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期,則會假設為 UTC。 只有在指定日期/時間修改目的地 Blob 時,才能指定此條件式標頭以複製 Blob。 如果未修改目的地 Blob,Blob 服務會傳回狀態碼 412 (先決條件失敗)。

if_unmodified_since
datetime

日期時間值。 Azure 預期傳入的日期值是 UTC。 如果包含時區,則任何非 UTC 日期時間都會轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期,則會假設為 UTC。 只有在非指定日期/時間修改目的地 Blob 時,才能指定此條件式標頭以複製 Blob。 如果已修改目的地 Blob,Blob 服務會傳回狀態碼 412 (先決條件失敗)。

etag
str

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

match_condition
MatchConditions

要用於 etag 的目的地比對條件。

if_tags_match_condition
str

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

12.4.0 版的新功能。

destination_lease
BlobLeaseClientstr

為此標頭指定的租用識別碼必須符合目的地 Blob 的租用識別碼。 如果要求不包含租用識別碼或無效,作業會失敗,並顯示狀態碼 412 (先決條件失敗)。

source_lease
BlobLeaseClientstr

指定此選項,只有在指定的租用識別碼符合來源 Blob 的作用中租用識別碼時,才執行複製 Blob 作業。

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。

rehydrate_priority
RehydratePriority

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

seal_destination_blob
bool

密封目的地附加 Blob。 此作業僅適用于附加 Blob。

12.4.0 版的新功能。

requires_sync
bool

強制在複製完成之前,服務不會傳迴響應。

source_authorization
str

使用用戶端密碼以服務主體身分驗證以存取來源 Blob。 請確定 「bearer」 是source_authorization字串的前置詞。 只有在 incremental_copy 設為 False 且 requires_sync 設定為 True 時,才能使用此選項。

12.9.0 版的新功能。

encryption_scope
str

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

12.10.0 版的新功能。

傳回

etag、last_modified、copy_id、copy_status) 複製 (屬性的字典。

傳回類型

undelete_blob

還原虛刪除的 Blob 或快照集。

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

如果已啟用 Blob 版本設定,就無法使用此方法還原基底 Blob。 start_copy_from_url請改用您想要升級至目前版本的 Blob 版本的 URL。

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

參數

timeout
int

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

傳回類型

upload_blob

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

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

參數

data
必要

要上傳的 Blob 資料。

blob_type
BlobType
必要

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

length
int
必要

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

metadata
dict(str, str)
必要

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

tags
dict(str, str)

與 Blob 相關聯的名稱/值組作為標記。 標記會區分大小寫。 標記集最多可以包含 10 個標記。 標籤索引鍵必須介於 1 到 128 個字元之間,而標籤值必須介於 0 到 256 個字元之間。 有效的標記索引鍵和值字元包括:小寫和大寫字母、 digits (0-9) , space >><< () , plus (+) , minus (-) , period (.) , solidus (/) , 冒號 (:) , equals (=) , 底線 (_)

12.4.0 版的新功能。

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

如果指定,upload_blob只有在 Blob 的租用作用中且符合此識別碼時才會成功。 如果 Blob 具有作用中租用,則為必要項目。

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 版的新功能。

premium_page_blob_tier
PremiumPageBlobTier

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

immutability_policy
ImmutabilityPolicy

指定 Blob、Blob 快照集或 Blob 版本的不變性原則。 目前,upload_blob () API 的此參數僅適用于 BlockBlob。

12.10.0 版的新功能:這是在 API 版本 '2020-10-02' 中引進的。

legal_hold
bool

如果應該在 Blob 上設定法務保存,則指定 。 目前,upload_blob () API 的此參數僅適用于 BlockBlob。

12.10.0 版的新功能:這是在 API 版本 '2020-10-02' 中引進的。

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。

timeout
int

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

傳回

Blob 更新的屬性聽寫 (Etag 和上次修改)

傳回類型

upload_blob_from_url

建立新的區塊 Blob,其中 Blob 的內容是從指定的 URL 讀取。 現有 Blob 的內容會以新的 Blob 覆寫。

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

參數

source_url
str
必要

長度上限為 2 KB 的 URL,指定檔案或 Blob。 此值應該像出現在要求 URI 中一樣以 URL 編碼。 如果來源位於另一個帳戶中,則來源必須是公用,或必須透過共用存取簽章進行驗證。 如果來源是公用的,則不需要驗證。 範例:https://myaccount.blob.core.windows.net/mycontainer/myblob

https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=

https://otheraccount.blob.core.windows.net/mycontainer/myblob?sastoken

overwrite
bool

要上傳的 Blob 是否應該覆寫目前的資料。 如果為 True,upload_blob將會覆寫現有的資料。 如果設定為 False,作業將會因為 ResourceExistsError 而失敗。

include_source_blob_properties
bool

指出是否應該複製來源 Blob 中的屬性。 預設值為 True。

tags
dict(str, str)

與 Blob 相關聯的名稱/值組作為標記。 標籤會區分大小寫。 標記集最多可以包含 10 個標籤。 標籤索引鍵必須介於 1 到 128 個字元之間,而標籤值必須介於 0 到 256 個字元之間。 有效的標記索引鍵和值字元包括:小寫和大寫字母、 digits (0-9) , space >><< () , plus (+) , 減 (-) , period (.) , solidus (/) , 冒號 (:) , equals (=) , 底線 (_)

source_content_md5
bytearray

指定用來驗證來源位元組完整性的 md5。

source_if_modified_since
datetime

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

source_if_unmodified_since
datetime

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

source_etag
str

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

source_match_condition
MatchConditions

要用於 etag 的來源比對條件。

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 的目的地比對條件。

destination_lease
BlobLeaseClientstr

為此標頭指定的租用識別碼必須符合目的地 Blob 的租用識別碼。 如果要求不包含租用識別碼或無效,作業會失敗,並顯示狀態碼 412 (先決條件失敗)。

timeout
int

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

content_settings
ContentSettings

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

cpk
CustomerProvidedEncryptionKey

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

encryption_scope
str

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

standard_blob_tier
StandardBlobTier

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

source_authorization
str

使用用戶端密碼以服務主體身分驗證以存取來源 Blob。 請確定 「bearer」 是source_authorization字串的前置詞。

upload_page

[上傳頁面] 作業會將一系列的頁面寫入分頁 Blob。

async upload_page(page: bytes, offset: int, length: int, **kwargs) -> Dict[str, str | datetime]

參數

page
bytes
必要

頁面的內容。

offset
int
必要

要用於寫入 Blob 區段的位元組範圍開始。 頁面必須對齊 512 位元組界限,開始位移必須是 512 的模數,長度必須是 512 的模數。

length
int
必要

要用於寫入 Blob 區段的位元組數目。 頁面必須對齊 512 位元組界限,開始位移必須是 512 的模數,長度必須是 512 的模數。

lease
BlobLeaseClientstr

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

validate_content
bool

如果為 true,則計算頁面內容的 MD5 雜湊。 儲存體服務會檢查已使用已傳送之雜湊抵達的內容雜湊。 這主要是在使用 HTTP 而不是 HTTPs 時偵測線路上的 bitflip,因為 HTTPs (預設) ,將會進行驗證。 請注意,此 MD5 雜湊不會隨 Blob 儲存。

if_sequence_number_lte
int

如果 Blob 的序號小於或等於指定的值,則要求會繼續;否則會失敗。

if_sequence_number_lt
int

如果 Blob 的序號小於指定的值,則要求會繼續;否則會失敗。

if_sequence_number_eq
int

如果 Blob 的序號等於指定的值,要求就會繼續;否則會失敗。

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 使用客戶提供的金鑰。 在要求中提供加密金鑰本身時,必須建立安全連線以傳輸金鑰。

encryption_scope
str

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

12.2.0 版的新功能。

encoding
str

預設為 UTF-8。

timeout
int

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

傳回

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

傳回類型

upload_pages_from_url

[上傳頁面] 作業會將一系列頁面寫入至從 URL 讀取內容的分頁 Blob。

async upload_pages_from_url(source_url: str, offset: int, length: int, source_offset: int, **kwargs) -> Dict[str, Any]

參數

source_url
str
必要

來源資料的 URL。 它可以指向任何 Azure Blob 或檔案,也就是公用或已附加共用存取簽章。

offset
int
必要

要用於寫入 Blob 區段的位元組範圍開始。 頁面必須對齊 512 位元組界限,開始位移必須是 512 的模數,長度必須是 512 的模數。

length
int
必要

要用於寫入 Blob 區段的位元組數目。 頁面必須對齊 512 位元組界限,開始位移必須是 512 的模數,長度必須是 512 的模數。

source_offset
int
必要

這表示必須從複製來源擷取 (包含) 位元組範圍的開頭。 服務會讀取與目的地範圍相同的位元組數目, (長度位移) 。

source_content_md5
bytes

如果指定,服務會計算區塊內容的 MD5 雜湊,並與此值進行比較。

source_if_modified_since
datetime

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

source_if_unmodified_since
datetime

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

source_etag
str

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

source_match_condition
MatchConditions

要用於 etag 的來源比對條件。

lease
BlobLeaseClientstr

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

if_sequence_number_lte
int

如果 Blob 的序號小於或等於指定的值,則要求會繼續;否則會失敗。

if_sequence_number_lt
int

如果 Blob 的序號小於指定的值,則要求會繼續;否則會失敗。

if_sequence_number_eq
int

如果 Blob 的序號等於指定的值,要求就會繼續;否則會失敗。

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 使用客戶提供的金鑰。 在要求中提供加密金鑰本身時,必須建立安全連線以傳輸金鑰。

encryption_scope
str

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

12.2.0 版的新功能。

timeout
int

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

source_authorization
str

使用用戶端密碼以服務主體身分驗證以存取來源 Blob。 請確定 「bearer」 是source_authorization字串的前置詞。

屬性

api_version

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

location_mode

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

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

primary_endpoint

完整的主要端點 URL。

primary_hostname

主要端點的主機名稱。

secondary_endpoint

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

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

例外狀況

secondary_hostname

次要端點的主機名稱。

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

url

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

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