共用方式為


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
strFileProperties
必要

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

lease
ShareLeaseClientstr

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

12.1.0 版的新功能。

timeout
int

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

傳回類型

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

傳回類型

範例

取得檔案上的租用。


   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
ShareLeaseClientstr

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

12.1.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

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。

傳回類型

close_handle

關閉開啟的檔案控制碼。

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

參數

handle
strHandle
必要

要關閉的特定控制碼。

timeout
int

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

傳回

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

傳回類型

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
strdatetime
必要

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

file_last_write_time
strdatetime
必要

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

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
strdatetime

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

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

content_settings
ContentSettings

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

metadata
dict(str,str)

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

lease
ShareLeaseClientstr

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

12.1.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

範例

建立檔案。


   # 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
ShareLeaseClientstr

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

12.1.0 版的新功能。

timeout
int

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

傳回類型

範例

刪除檔案。


   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
ShareLeaseClientstr

如果檔案具有作用中的租用,則為必要專案。 值可以是 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 (。

傳回

檔案用戶端。

傳回類型

範例

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


   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 (。

傳回

檔案用戶端。

傳回類型

get_file_properties

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

get_file_properties(**kwargs: Any) -> FileProperties

參數

lease
ShareLeaseClientstr

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

12.1.0 版的新功能。

timeout
int

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

傳回

FileProperties

傳回類型

get_ranges

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

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

參數

offset
int
必要

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

length
int
必要

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

lease
ShareLeaseClientstr

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

12.1.0 版的新功能。

timeout
int

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

傳回

有效範圍的清單。

傳回類型

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
ShareLeaseClientstr

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

timeout
int

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

傳回

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

傳回類型

list_handles

列出檔案的控制碼。

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

參數

timeout
int

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

傳回

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

傳回類型

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
ShareLeaseClientstr

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

destination_lease
ShareLeaseClientstr

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

傳回

新的檔案用戶端。

傳回類型

resize_file

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

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

參數

size
int
必要

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

lease
ShareLeaseClientstr

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

12.1.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

set_file_metadata

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

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

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

參數

metadata
dict(str, str)
必要

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

lease
ShareLeaseClientstr

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

12.1.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

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
strdatetime
必要

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

file_last_write_time
strdatetime
必要

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

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
strdatetime

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

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

lease
ShareLeaseClientstr

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

12.1.0 版的新功能。

timeout
int

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

傳回

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

傳回類型

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
strdatetime

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

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

file_last_write_time
strdatetime

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

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

file_change_time
strdatetime

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

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
ShareLeaseClientstr

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

12.1.0 版的新功能。

timeout
int

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

傳回類型

範例

從 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
ShareLeaseClientstr

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

12.1.0 版的新功能。

timeout
int

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

encoding
str

預設為 UTF-8。

傳回

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

傳回類型

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
ShareLeaseClientstr

如果檔案具有作用中的租用,則為必要專案。 值可以是 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 關鍵字引數。

例外狀況

secondary_hostname

次要端點的主機名稱。

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

url

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

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