azure.storage.blob.BlobClient class

中止進行中的複製作業。

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

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

參數

copy_id: str 或 BlobProperties

必要

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

傳回類型

None

要求新的租用。

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

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 物件。

傳回類型

BlobLeaseClient

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

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

參數

data: bytes 或 str 或 Iterable

必要

區塊的內容。這可以是位元組、文字、可反覆運算或類似檔案的物件。

length: int

必要

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

validate_content: bool

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

maxsize_condition: int

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

appendpos_condition: int

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

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

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、上次修改、附加位移、認可區塊計數) 。

傳回類型

dict(str, Any)

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

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

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(offset: int, length: int, **kwargs: Any) -> Dict[str, str | datetime]

參數

offset: int

必要

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

length: int

必要

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

lease: BlobLeaseClient 或 str

如果 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 和上次修改) 。

傳回類型

dict(str, Any)

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

close()

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

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: BlobLeaseClient 或 str

如果 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 上運作。

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 和上次修改) 。

傳回類型

dict(str, Any)

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

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

lease: BlobLeaseClient 或 str

如果 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 和上次修改) 。

傳回類型

dict[str, Any]

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

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 (+) ， minus (-) ， period (.) ， solidus (/) ，冒號 (：) ， equals (=) ，底線 (_)

12.4.0 版的新功能。

sequence_number: int

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

lease: BlobLeaseClient 或 str

如果 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 和上次修改) 。

傳回類型

dict[str, Any]

建立 Blob 的快照集。

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

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

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 上以相符的值運作。

12.4.0 版的新功能。

lease: BlobLeaseClient 或 str

如果 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 和上次修改) 。

傳回類型

dict[str, Any]

將指定的 Blob 標記為刪除。

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

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

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: BlobLeaseClient 或 str

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

傳回類型

None

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

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

delete_immutability_policy(**kwargs: Any) -> None

參數

timeout: int

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

傳回

Blob 標記的索引鍵值組。

傳回類型

Dict[str, str]

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

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: 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

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

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

傳回類型

bool

從 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 用戶端。

傳回類型

BlobClient

從連接字串建立 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 用戶端。

傳回類型

BlobClient

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

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

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

傳回

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

傳回類型

dict(str, str)

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

get_blob_properties(**kwargs: Any) -> BlobProperties

參數

lease: BlobLeaseClient 或 str

如果 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

傳回類型

BlobProperties

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

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

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: BlobLeaseClient 或 str

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

timeout: int

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

傳回

Blob 標記的索引鍵值組。

傳回類型

Dict[str, str]

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

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

參數

block_list_type: str

必要

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

lease: BlobLeaseClient 或 str

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

if_tags_match_condition: str

在 Blob 標記上指定 SQL where 子句，以只在具有相符值的目的地 Blob 上運作。

12.4.0 版的新功能。

timeout: int

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

傳回

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

傳回類型

tuple(list(BlobBlock), list(BlobBlock))

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

注意

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

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

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

timeout: int

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

傳回

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

傳回類型

tuple(list(dict(str, str), list(dict(str, str))

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

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

傳回

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

傳回類型

tuple(list(dict(str, str), list(dict(str, str))

傳回分頁 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) -> ItemPaged[PageRange]

參數

offset: int

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

length: int

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

previous_snapshot: str 或 Dict[str, Any]

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

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

results_per_page: int

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

timeout: int

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

傳回

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

傳回類型

ItemPaged[PageRange]

可讓使用者藉由提供簡單的查詢運算式，在 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: DelimitedTextDialect 或 DelimitedJsonDialect 或 QuickQueryDialect 或 str

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

output_format: DelimitedTextDialect 或 DelimitedJsonDialect 或 list[ArrowDialect] 或 QuickQueryDialect 或 str

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

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

cpk: CustomerProvidedEncryptionKey

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

timeout: int

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

傳回

BlobQueryReader (串流物件)

傳回類型

BlobQueryReader

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

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

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

參數

size: int

必要

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

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

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 和上次修改) 。

傳回類型

dict(str, Any)

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

12.4.0 版的新功能。

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

參數

appendpos_condition: int

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

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

timeout: int

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

傳回

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

傳回類型

dict(str, Any)

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

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

參數

metadata: dict(str, str)

必要

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

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

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 和上次修改)

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

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

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: BlobLeaseClient 或 str

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

timeout: int

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

傳回

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

傳回類型

Dict[str, Any]

在 Blob 上設定系統屬性。

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

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

參數

content_settings: ContentSettings

必要

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

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

傳回

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

傳回類型

Dict[str, Any]

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

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

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 標記的索引鍵值組。

傳回類型

Dict[str, str]

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

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

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 標記的索引鍵值組。

傳回類型

Dict[str, Union[str, datetime, bool]]

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

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: BlobLeaseClient 或 str

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

傳回類型

None

設定 Blob 序號。

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

參數

sequence_number_action: str

必要

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

sequence_number: str

必要

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

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

傳回

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

傳回類型

dict(str, Any)

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

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

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

參數

standard_blob_tier: str 或 StandardBlobTier

必要

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

rehydrate_priority: RehydratePriority

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

version_id: str

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

12.4.0 版的新功能。

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

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: BlobLeaseClient 或 str

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

傳回類型

None

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

stage_block(block_id: str, data: Iterable | IO, length: int | None = None, **kwargs) -> Dict[str, Any]

參數

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: BlobLeaseClient 或 str

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

傳回

Blob 屬性聽寫。

傳回類型

dict[str, Any]

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

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) -> Dict[str, Any]

參數

block_id: str

必要

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

source_url: str

必要

URL。

source_offset: int

必要

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

source_length: int

必要

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

source_content_md5: bytearray

必要

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

lease: BlobLeaseClient 或 str

如果 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字串的前置詞。

傳回

Blob 屬性聽寫。

傳回類型

dict[str, Any]

從指定的 URL 複製 Blob。

此作業會傳回包含 copy_status 和 copy_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 會擁有與來源相同的認可區塊計數。

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 (+) ， minus (-) ， period (.) ， solidus (/) ，冒號 (：) ， equals (=) ，底線 (_) 。

(區分大小寫的) 常值「COPY」可以改為傳遞，以從來源 Blob 複製標記。只有在 incremental_copy=False 和 requires_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 的目的地比對條件。

destination_lease: BlobLeaseClient 或 str

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

source_lease: BlobLeaseClient 或 str

只有在指定的租用識別碼符合來源 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) 複製 (屬性的字典。

傳回類型

dict[str, Union[str, datetime]]

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

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

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

undelete_blob(**kwargs: Any) -> None

參數

timeout: int

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

傳回類型

None

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

upload_blob(data: bytes | str | Iterable | 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: BlobLeaseClient 或 str

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

premium_page_blob_tier: PremiumPageBlobTier

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

standard_blob_tier: StandardBlobTier

要設定 Blob 的標準 Blob 層值。針對此版本的程式庫，這只適用于標準儲存體帳戶上的區塊 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' 中引進的。

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。

timeout: int

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

傳回

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

傳回類型

dict[str, Any]

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

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 (+) ， minus (-) ， 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: BlobLeaseClient 或 str

為此標頭指定的租用識別碼必須符合目的地 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字串的前置詞。

上傳頁面作業會將頁面範圍寫入分頁 Blob。

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: BlobLeaseClient 或 str

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

validate_content: bool

如果為 true，則會計算頁面內容的 MD5 雜湊。儲存體服務會檢查與已傳送雜湊一起抵達之內容的雜湊。如果使用 HTTP 而非 HTTPs，這主要是在使用 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 和上次修改) 。

傳回類型

dict(str, Any)

上傳頁面作業會將頁面範圍寫入至從 URL 讀取內容的分頁 Blob。

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: BlobLeaseClient 或 str

如果 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 版本。

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

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

完整的主要端點 URL。

主要端點的主機名稱。

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

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

例外狀況

ValueError

次要端點的主機名稱。

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

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

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

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_block 或 append_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.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_status 和 copy_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。

BlobClient 類別

建構函式

參數

方法

abort_copy

參數

傳回類型

acquire_lease

參數

傳回

傳回類型

append_block

參數

傳回

傳回類型

append_block_from_url

參數

clear_page

參數

傳回

傳回類型

close

commit_block_list

參數

傳回

傳回類型

create_append_blob

參數

傳回

傳回類型

create_page_blob

參數

傳回

傳回類型

create_snapshot

參數

傳回

傳回類型

delete_blob

參數

傳回類型

delete_immutability_policy

參數

傳回

傳回類型

download_blob

參數

傳回

傳回類型

exists

參數

傳回

傳回類型

from_blob_url

參數

傳回

傳回類型

from_connection_string

參數

傳回

傳回類型

get_account_information

傳回

傳回類型

get_blob_properties

參數

傳回

傳回類型

get_blob_tags

參數

傳回

傳回類型

get_block_list

參數

傳回

傳回類型

get_page_range_diff_for_managed_disk

參數

傳回

傳回類型