共用方式為

ShareFileClient 類別

  • 參考

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

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

繼承
azure.storage.fileshare._shared.base_client.StorageAccountHostsMixin
ShareFileClient

建構函式

ShareFileClient(account_url: str, share_name: str, file_path: str, snapshot: str | Dict[str, Any] | None = None, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, *, token_intent: Literal['backup'] | None = None, **kwargs: Any)

參數

account_url
str
必要

儲存體帳戶的 URI。 若要在檔案的完整 URI 下建立用戶端，請使用 from_file_url classmethod。

share_name
str
必要

檔案的共用名稱稱。

file_path
str
必要

要與其互動之檔案的檔案路徑。 如果指定，此值將會覆寫檔案 URL 中指定的檔案值。

snapshot
str
預設值: None

要在其中操作的選擇性檔案快照集。 這可以是快照集識別碼字串或從 create_snapshot 傳回的回應。

credential
預設值: None

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

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

使用 TokenCredential 進行驗證時為必要專案，並忽略其他形式的驗證。 使用 TokenCredential 驗證時，指定所有要求的意圖。 可能的值包括：

backup - 指定要求適用于備份/管理員類型作業，這表示會略過所有檔案/目錄 ACL，並授與完整許可權。 使用者也必須具有必要的 RBAC 許可權。

allow_trailing_dot
bool

如果為 true，則不會從目標 URI 修剪尾端點。

allow_source_trailing_dot
bool

如果為 true，則不會從來源 URI 修剪尾端點。

api_version
str

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

12.1.0 版的新功能。

secondary_hostname
str

次要端點的主機名稱。

max_range_size
int

用於檔案上傳的範圍大小上限。 預設為 4*1024*1024。

audience
str

要求 Azure Active Directory 驗證權杖時要使用的物件。 只有在認證類型為 TokenCredential 時才會生效。 此值可以是 https://storage.azure.com/ 預設) 或 HTTPs：//.file.core.windows.net (。

方法

abort_copy

中止進行中的複製作業。

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

要求新的租用。

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

清除指定的範圍，並釋放該範圍儲存體中使用的空間。
close

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

關閉任何開啟的檔案控制碼。

這項作業將會封鎖，直到服務關閉所有開啟的控制碼為止。
close_handle

關閉開啟的檔案控制碼。
create_file

建立新檔案。

請注意，它只會初始化沒有內容的檔案。
delete_file

標記要刪除的指定檔案。 檔案稍後會在垃圾收集期間刪除。
download_file

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

從連接字串建立 ShareFileClient。
from_file_url

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

傳回檔案的所有使用者定義中繼資料、標準 HTTP 屬性和系統屬性。
get_ranges

傳回檔案或檔案快照集的有效頁面範圍清單。
get_ranges_diff

傳回檔案或檔案快照集的有效頁面範圍清單。

12.6.0 版的新功能。
list_handles

列出檔案的控制碼。
rename_file

重新命名原始程式檔。

:p aramtype file_attributes：~azure.storage.fileshare.NTFSAttributes 或 str ：keyword file_creation_time：

檔案的建立時間。

:p aramtype file_creation_time：~datetime.datetime 或 str ：keyword file_last_write_time：

檔案的上次寫入時間。

:p aramtype file_last_write_time：~datetime.datetime 或 str ：keyword file_change_time：

變更檔案的時間。 如果未指定，變更時間將會設定為目前的日期/時間。

12.8.0 版的新功能：此參數是在 API 版本 '2021-06-08' 中引進。
resize_file

將檔案調整為指定的大小。
set_file_metadata

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

每次呼叫這項作業都會取代附加至檔案的所有現有中繼資料。 若要從檔案中移除所有中繼資料，請呼叫沒有中繼資料聽寫的這項作業。
set_http_headers

設定檔案上的 HTTP 標頭。
start_copy_from_url

起始將資料從來源 URL 複製到用戶端所參考的檔案中。

您可以使用 get_properties 方法找到此複製作業的狀態。
upload_file

上傳新檔案。

param 資料：檔案的內容。

param int length：以位元組為單位的檔案長度。 指定其大小上限，最多 1 TiB。

param file_attributes：檔案和目錄的檔案系統屬性。 如果未設定，預設值會是 「None」，而且屬性會設定為 「Archive」。 以下是 var 類型為 str 時的範例：'暫存|封存'。 file_attributes值不區分大小寫。

類型file_attributes：str 或 ~azure.storage.fileshare.NTFSAttributes

param file_creation_time：檔案預設值的建立時間：現在。

類型file_creation_time：str 或 ~datetime.datetime

param file_last_write_time：檔案的上次寫入時間預設值：現在。

類型file_last_write_time：str 或 ~datetime.datetime

param file_permission：如果指定許可權 (安全性描述元) 應設定目錄/檔案。 如果許可權大小為 < = 8KB，則可以使用此標頭，否則應該使用 x-ms-file-permission-key 標頭。 預設值：繼承。 如果 SDDL 指定為輸入，它必須具有擁有者、群組和 dacl。 注意：應該只指定其中一個 x-ms-file-permission 或 x-ms-file-permission-key。

類型file_permission：str

param permission_key：要為目錄/檔案設定的許可權索引鍵。 注意：應該只指定其中一個 x-ms-file-permission 或 x-ms-file-permission-key。

類型permission_key：str
upload_range

將位元組範圍上傳至檔案。
upload_range_from_url

將位元組從一個 Azure 檔案端點寫入另一個 Azure 檔案端點的指定範圍。

abort_copy

中止進行中的複製作業。

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

abort_copy(copy_id: str | FileProperties, **kwargs: Any) -> None

參數

copy_id
str 或 FileProperties
必要

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

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

timeout
int

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

傳回類型

None

acquire_lease

要求新的租用。

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

acquire_lease(lease_id: str | None = None, **kwargs: Any) -> ShareLeaseClient

參數

lease_id
str
必要

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

timeout
int

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

傳回

ShareLeaseClient 物件。

傳回類型

ShareLeaseClient

範例

取得檔案上的租用。


   source_file.create_file(1024)
   lease = source_file.acquire_lease()
   source_file.upload_file(b'hello world', lease=lease)

   lease.release()

clear_range

清除指定的範圍，並釋放該範圍儲存體中使用的空間。

clear_range(offset: int, length: int, **kwargs) -> Dict[str, Any]

參數

offset
int
必要

要用來清除檔案區段的位元組範圍開始。 此範圍的大小上限為 4 MB。

length
int
必要

用於清除檔案區段的位元組數目。 此範圍的大小上限為 4 MB。

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

Dict[str, Any]

close

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

close()

close_all_handles

關閉任何開啟的檔案控制碼。

這項作業將會封鎖，直到服務關閉所有開啟的控制碼為止。

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

參數

timeout
int

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

傳回

如果找不到指定的控制碼，) 且控制碼數目無法在聽寫中關閉，則關閉 (的控制碼數目可能會是 0。

傳回類型

dict[str, int]

close_handle

關閉開啟的檔案控制碼。

close_handle(handle: str | Handle, **kwargs: Any) -> Dict[str, int]

參數

handle
str 或 Handle
必要

要關閉的特定控制碼。

timeout
int

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

傳回

如果找不到指定的控制碼，) 且控制碼數目無法在聽寫中關閉，則關閉 (的控制碼數目可能會是 0。

傳回類型

dict[str, int]

create_file

建立新檔案。

請注意，它只會初始化沒有內容的檔案。

create_file(size: int, file_attributes: str | NTFSAttributes = 'none', file_creation_time: str | datetime | None = 'now', file_last_write_time: str | datetime | None = 'now', file_permission: str | None = None, permission_key: str | None = None, **kwargs: Any) -> Dict[str, Any]

參數

size
int
必要

指定檔案的大小上限，最多 1 TB。

file_attributes
NTFSAttributes
必要

檔案和目錄的檔案系統屬性。 如果未設定，預設值會是 「None」，而且屬性會設定為 「Archive」。 以下是 var 類型為 str 時的範例：'暫存|封存'。 file_attributes值不區分大小寫。

file_creation_time
str 或 datetime
必要

檔案預設值的建立時間：現在。

file_last_write_time
str 或 datetime
必要

檔案的上次寫入時間預設值：現在。

file_permission
str
必要

如果指定許可權 (安全性描述元) 應設定目錄/檔案。 如果許可權大小為 < = 8KB，則可以使用此標頭，否則應該使用 x-ms-file-permission-key 標頭。 預設值：繼承。 如果 SDDL 指定為輸入，它必須具有擁有者、群組和 dacl。 注意：應該只指定其中一個 x-ms-file-permission 或 x-ms-file-permission-key。

permission_key
str
必要

要為目錄/檔案設定之許可權的索引鍵。 注意：應該只指定其中一個 x-ms-file-permission 或 x-ms-file-permission-key。

file_change_time
str 或 datetime

變更檔案的時間。 如果未指定，變更時間將會設定為目前的日期/時間。

12.8.0 版的新功能：此參數是在 API 版本 '2021-06-08' 中引進。

content_settings
ContentSettings

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

metadata
dict(str,str)

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

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

dict(str, Any)

範例

建立檔案。


   # Create and allocate bytes for the file (no content added yet)
   my_allocated_file.create_file(size=100)

delete_file

標記要刪除的指定檔案。 檔案稍後會在垃圾收集期間刪除。

delete_file(**kwargs: Any) -> None

參數

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

timeout
int

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

傳回類型

None

範例

刪除檔案。


   my_file.delete_file()

download_file

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

download_file(offset: int | None = None, length: int | None = None, **kwargs: Any) -> StorageStreamDownloader

參數

offset
int
必要

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

length
int
必要

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

max_concurrency
int

要使用的平行連線數目上限。

validate_content
bool

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

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

progress_hook
Callable[[int, int], None]

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

timeout
int

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

傳回

StorageStreamDownloader (串流物件)

傳回類型

<xref:azure.storage.fileshare.StorageStreamDownloader>

範例

下載檔案。


   with open(DEST_FILE, "wb") as data:
       stream = my_file.download_file()
       data.write(stream.readall())

from_connection_string

從連接字串建立 ShareFileClient。

from_connection_string(conn_str: str, share_name: str, file_path: 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 儲存體帳戶連接字串。

share_name
str
必要

共用的名稱。

file_path
str
必要

檔案路徑。

snapshot
str
預設值: None

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

credential
預設值: None

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

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

要求 Azure Active Directory 驗證權杖時要使用的物件。 只有在認證類型為 TokenCredential 時才會生效。 此值可以是 https://storage.azure.com/ 預設) 或 HTTPs：//.file.core.windows.net (。

傳回

檔案用戶端。

傳回類型

ShareFileClient

範例

使用 連接字串 建立檔案用戶端。


   from azure.storage.fileshare import ShareFileClient
   file = ShareFileClient.from_connection_string(
       self.connection_string,
       share_name="helloworld2",
       file_path="myfile")

from_file_url

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

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

參數

file_url
str
必要

檔案的完整 URI。

snapshot
str
預設值: None

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

credential
預設值: None

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

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

要求 Azure Active Directory 驗證權杖時要使用的物件。 只有在認證類型為 TokenCredential 時才會生效。 此值可以是 https://storage.azure.com/ 預設) 或 HTTPs：//.file.core.windows.net (。

傳回

檔案用戶端。

傳回類型

ShareFileClient

get_file_properties

傳回檔案的所有使用者定義中繼資料、標準 HTTP 屬性和系統屬性。

get_file_properties(**kwargs: Any) -> FileProperties

參數

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

timeout
int

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

傳回

FileProperties

傳回類型

FileProperties

get_ranges

傳回檔案或檔案快照集的有效頁面範圍清單。

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

參數

offset
int
必要

指定要取得範圍的位元組開始位移。

length
int
必要

要用來取得範圍的位元組數目。

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

timeout
int

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

傳回

有效範圍的清單。

傳回類型

List[dict[str, int]]

get_ranges_diff

傳回檔案或檔案快照集的有效頁面範圍清單。

12.6.0 版的新功能。

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

參數

offset
int
必要

指定要取得範圍的位元組開始位移。

length
int
必要

要用來取得範圍的位元組數目。

previous_sharesnapshot
str
必要

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

lease
ShareLeaseClient 或 str

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

timeout
int

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

傳回

兩個檔案範圍的 Tuple 做為具有 'start' 和 'end' 索引鍵的字典。 第一個專案是填滿的檔案範圍，第 2 個元素會清除檔案範圍。

傳回類型

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

list_handles

列出檔案的控制碼。

list_handles(**kwargs: Any) -> ItemPaged[Handle]

參數

timeout
int

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

傳回

可逐一檢查控制碼的自動分頁

傳回類型

ItemPaged[Handle]

rename_file

重新命名原始程式檔。

:p aramtype file_attributes：~azure.storage.fileshare.NTFSAttributes 或 str ：keyword file_creation_time：

檔案的建立時間。

:p aramtype file_creation_time：~datetime.datetime 或 str ：keyword file_last_write_time：

檔案的上次寫入時間。

:p aramtype file_last_write_time：~datetime.datetime 或 str ：keyword file_change_time：

變更檔案的時間。 如果未指定，變更時間將會設定為目前的日期/時間。

12.8.0 版的新功能：此參數是在 API 版本 '2021-06-08' 中引進。

rename_file(new_name: str, **kwargs: Any) -> ShareFileClient

參數

content_type
str

新檔案的內容類型。

12.8.0 版的新功能：此參數是在 API 版本 '2021-06-08' 中引進。

metadata
Dict[str,str]

要與檔案儲存物件建立關聯的名稱/值組。

source_lease
ShareLeaseClient 或 str

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

destination_lease
ShareLeaseClient 或 str

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

傳回

新的檔案用戶端。

傳回類型

ShareFileClient

resize_file

將檔案調整為指定的大小。

resize_file(size: int, **kwargs: Any) -> Dict[str, Any]

參數

size
int
必要

將檔案大小調整為位元組) (大小

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

Dict[str, Any]

set_file_metadata

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

每次呼叫這項作業都會取代附加至檔案的所有現有中繼資料。 若要從檔案中移除所有中繼資料，請呼叫沒有中繼資料聽寫的這項作業。

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

參數

metadata
dict(str, str)
必要

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

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

dict(str, Any)

set_http_headers

設定檔案上的 HTTP 標頭。

set_http_headers(content_settings: ContentSettings, file_attributes: str | NTFSAttributes = 'preserve', file_creation_time: str | datetime | None = 'preserve', file_last_write_time: str | datetime | None = 'preserve', file_permission: str | None = None, permission_key: str | None = None, **kwargs: Any) -> Dict[str, Any]

參數

content_settings
ContentSettings
必要

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

file_attributes
NTFSAttributes
必要

檔案和目錄的檔案系統屬性。 如果未設定，表示保留現有的值。 以下是 var 類型為 str 時的範例：'暫存|封存'

file_creation_time
str 或 datetime
必要

檔案預設值的建立時間：保留。

file_last_write_time
str 或 datetime
必要

檔案的上次寫入時間預設值：保留。

file_permission
str
必要

如果指定許可權 (安全性描述元) 應設定目錄/檔案。 如果許可權大小為 < = 8KB，則可以使用此標頭，否則應該使用 x-ms-file-permission-key 標頭。 預設值：繼承。 如果 SDDL 指定為輸入，它必須具有擁有者、群組和 dacl。 注意：應該只指定其中一個 x-ms-file-permission 或 x-ms-file-permission-key。

permission_key
str
必要

要為目錄/檔案設定之許可權的索引鍵。 注意：應該只指定其中一個 x-ms-file-permission 或 x-ms-file-permission-key。

file_change_time
str 或 datetime

變更檔案的時間。 如果未指定，變更時間將會設定為目前的日期/時間。

12.8.0 版的新功能：此參數是在 API 版本 '2021-06-08' 中引進。

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

dict(str, Any)

start_copy_from_url

起始將資料從來源 URL 複製到用戶端所參考的檔案中。

您可以使用 get_properties 方法找到此複製作業的狀態。

start_copy_from_url(source_url: str, **kwargs: Any) -> Any

參數

source_url
str
必要

指定來源檔案的 URL。

file_permission
str

如果指定許可權 (安全性描述元) 應設定目錄/檔案。 這個值可以設定為 「來源」，以從來源檔案複製安全性描述元。 否則，如果設定，這個值將用來覆寫來源值。 如果未設定，許可權值會繼承自目標檔案的父目錄。 如果許可權大小為 < = 8KB，則可以使用此設定，否則應該使用permission_key。 如果 SDDL 指定為輸入，它必須具有擁有者、群組和 dacl。 注意：應該只指定其中一個file_permission或permission_key。

12.1.0 版的新功能：此參數是在 API 版本 '2019-07-07' 中引進。

permission_key
str

要為目錄/檔案設定之許可權的索引鍵。 這個值可以設定為 「來源」，以從來源檔案複製安全性描述元。 否則，如果設定，這個值將用來覆寫來源值。 如果未設定，許可權值會繼承自目標檔案的父目錄。 注意：應該只指定其中一個file_permission或permission_key。

12.1.0 版的新功能：此參數是在 API 版本 '2019-07-07' 中引進。

file_attributes
NTFSAttributes

這個值可以設定為 「source」，將檔案屬性從來源檔案複製到目標檔案，或清除所有屬性，它可以設定為 「None」。 否則，它可以設定為在目標檔案上設定的屬性清單。 如果未設定此設定，預設值為 「封存」。

12.1.0 版的新功能：此參數是在 API 版本 '2019-07-07' 中引進。

file_creation_time
str 或 datetime

這個值可以設定為「來源」，將建立時間從來源檔案複製到目標檔案，或設定為目標檔案上建立時間的日期時間。 這也可以是 ISO 8601 格式的字串。 如果未設定，建立時間會設定為建立 (的日期時間值，或複製引擎覆寫目標檔案) 的時間值。

12.1.0 版的新功能：此參數是在 API 版本 '2019-07-07' 中引進。

file_last_write_time
str 或 datetime

這個值可以設定為 「來源」，將來源檔案的最後一次寫入時間複製到目標檔案，或設定為目標檔案上上次寫入時間的日期時間。 這也可以是 ISO 8601 格式的字串。 如果未設定，則值會是複製引擎對檔案的最後一次寫入時間。

12.1.0 版的新功能：此參數是在 API 版本 '2019-07-07' 中引進。

file_change_time
str 或 datetime

變更檔案的時間。 如果未指定，變更時間將會設定為目前的日期/時間。

12.9.0 版的新功能：此參數是在 API 版本 '2021-06-08' 中引進。

ignore_read_only
bool

指定選項，如果目標檔案已經存在且已設定唯讀屬性，則為覆寫目標檔案。

12.1.0 版的新功能：此參數是在 API 版本 '2019-07-07' 中引進。

set_archive_attribute
bool

指定在目標檔案上設定封存屬性的選項。 True 表示即使屬性覆寫或來源檔案狀態，仍會在目標檔案上設定封存屬性。

12.1.0 版的新功能：此參數是在 API 版本 '2019-07-07' 中引進。

metadata

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

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

timeout
int

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

傳回類型

dict(str, Any)

範例

從 URL 複製檔案


   destination_file.start_copy_from_url(source_url=source_url)

upload_file

上傳新檔案。

param 資料：檔案的內容。

param int length：以位元組為單位的檔案長度。 指定其大小上限，最多 1 TiB。

param file_attributes：檔案和目錄的檔案系統屬性。 如果未設定，預設值會是 「None」，而且屬性會設定為 「Archive」。 以下是 var 類型為 str 時的範例：'暫存|封存'。 file_attributes值不區分大小寫。

類型file_attributes：str 或 ~azure.storage.fileshare.NTFSAttributes

param file_creation_time：檔案預設值的建立時間：現在。

類型file_creation_time：str 或 ~datetime.datetime

param file_last_write_time：檔案的上次寫入時間預設值：現在。

類型file_last_write_time：str 或 ~datetime.datetime

param file_permission：如果指定許可權 (安全性描述元) 應設定目錄/檔案。 如果許可權大小為 < = 8KB，則可以使用此標頭，否則應該使用 x-ms-file-permission-key 標頭。 預設值：繼承。 如果 SDDL 指定為輸入，它必須具有擁有者、群組和 dacl。 注意：應該只指定其中一個 x-ms-file-permission 或 x-ms-file-permission-key。

類型file_permission：str

param permission_key：要為目錄/檔案設定的許可權索引鍵。 注意：應該只指定其中一個 x-ms-file-permission 或 x-ms-file-permission-key。

類型permission_key：str

upload_file(data: bytes | str | Iterable | IO, length: int | None = None, file_attributes: str | NTFSAttributes = 'none', file_creation_time: str | datetime | None = 'now', file_last_write_time: str | datetime | None = 'now', file_permission: str | None = None, permission_key: str | None = None, **kwargs) -> Dict[str, Any]

參數

file_change_time

變更檔案的時間。 如果未指定，變更時間將會設定為目前的日期/時間。

12.8.0 版的新功能：此參數是在 API 版本 '2021-06-08' 中引進。

paramtype file_change_time：str 或 ~datetime.datetime

關鍵字聽寫 (str，str) 中繼資料：與檔案相關聯的名稱/值組作為中繼資料。

關鍵字 ~azure.storage.fileshare.ContentSettings content_settings：用來設定檔案屬性的 ContentSettings 物件。 用來設定內容類型、編碼、語言、處置、md5 和快取控制項。

關鍵字 bool validate_content：如果為 true，則會針對檔案的每個範圍計算 MD5 雜湊。 儲存體服務會檢查已使用已傳送之雜湊抵達的內容雜湊。 如果使用 HTTP 而非 HTTPs 作為 HTTPs， (預設) 已驗證，這主要對於偵測線路上的 bitflip 相當重要。 請注意，這個 MD5 雜湊不會與檔案一起儲存。

關鍵字 int max_concurrency：要使用的平行連線數目上限。

關鍵字租用：如果檔案具有作用中的租用，則為必要專案。 值可以是 ShareLeaseClient 物件或租用識別碼作為字串。

12.1.0 版的新功能。

paramtype 租用：~azure.storage.fileshare.ShareLeaseClient 或 str

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

paramtype progress_hook： Callable[[int， Optional[int]，None]

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

關鍵字 str 編碼：預設為 UTF-8。

會傳回：檔案更新的屬性聽寫 (Etag 和上次修改) 。

rtype：dict (str、Any)

範例：上傳檔案。


   with open(SOURCE_FILE, "rb") as source:
       my_file.upload_file(source)

upload_range

將位元組範圍上傳至檔案。

upload_range(data: bytes, offset: int, length: int, **kwargs) -> Dict[str, Any]

參數

data
bytes
必要

要上傳的資料。

offset
int
必要

要用於上傳檔案區段的位元組範圍開始。 此範圍的大小上限為 4 MB。

length
int
必要

用於上傳檔案區段的位元組數目。 此範圍的大小上限為 4 MB。

validate_content
bool

如果為 true，則計算頁面內容的 MD5 雜湊。 儲存體服務會檢查已使用已傳送之雜湊抵達的內容雜湊。 如果使用 HTTP 而非 HTTPs 作為 HTTPs， (預設) 已驗證，這主要對於偵測線路上的 bitflip 相當重要。 請注意，這個 MD5 雜湊不會與檔案一起儲存。

file_last_write_mode
Literal["preserve", "now"]

如果應該保留或覆寫檔案上次寫入時間。 可能的值為 「preserve」 或 「now」。 如果未指定，則檔案上次寫入時間會變更為目前的日期/時間。

12.8.0 版的新功能：此參數是在 API 版本 '2021-06-08' 中引進。

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

timeout
int

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

encoding
str

預設為 UTF-8。

傳回

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

傳回類型

Dict[str, Any]

upload_range_from_url

將位元組從一個 Azure 檔案端點寫入另一個 Azure 檔案端點的指定範圍。

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

參數

offset
int
必要

要用於更新檔案區段的位元組範圍開始。 此範圍的大小上限為 4 MB。

length
int
必要

用於更新檔案區段的位元組數目。 此範圍的大小上限為 4 MB。

source_url
str
必要

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

source_offset
int
必要

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

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

file_last_write_mode
Literal["preserve", "now"]

如果應該保留或覆寫檔案上次寫入時間。 可能的值為 「preserve」 或 「now」。 如果未指定，則檔案上次寫入時間會變更為目前的日期/時間。

12.8.0 版的新功能：此參數是在 API 版本 '2021-06-08' 中引進。

lease
ShareLeaseClient 或 str

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

12.1.0 版的新功能。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-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 關鍵字引數。

例外狀況

ValueError

secondary_hostname

次要端點的主機名稱。

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

url

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

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