你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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 类方法。

share_name

str

必需

文件的共享的名称。

file_path

str

必需

要与之交互的文件的文件路径。 如果指定，此值将替代文件 URL 中指定的文件值。

snapshot

str

默认值: None

要在其上运行的可选文件快照。 这可以是快照 ID 字符串，也可以是从 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 () 将文件下载到流中。 使用 chunks () 将返回一个迭代器，该迭代器允许用户循环访问区块中的内容。
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	将指定文件的用户定义元数据设置为一个或多个名称/值对。 每次调用此操作都会替换附加到该文件的所有现有元数据。 若要从文件中删除所有元数据，请调用此操作，不带元数据 dict。
set_http_headers	在文件上设置 HTTP 标头。
start_copy_from_url	启动将数据从源 URL 复制到客户端引用的文件中。 可以使用 get_properties 方法找到此复制操作的状态。
upload_file	上传新文件。 参数数据：文件的内容。 param int length：文件的长度（以字节为单位）。 指定其最大大小，最大为 1 TiB。 param file_attributes：文件和目录的文件系统属性。 如果未设置，则默认值为“None”，属性将设置为“Archive”。 下面是 var 类型为 str 时的示例：“Temporary|存档”。 file_attributes值不区分大小写。 type file_attributes：str 或 ~azure.storage.fileshare.NTFSAttributes param file_creation_time：文件的创建时间 默认值：现在。 type file_creation_time：str 或 ~datetime.datetime param file_last_write_time：文件的上次写入时间 默认值：现在。 type file_last_write_time：str 或 ~datetime.datetime param file_permission：如果指定了权限 (应为目录/文件设置安全描述符) 。 如果权限大小 <= 8KB，则可以使用此标头，否则应使用 x-ms-file-permission-key 标头。 默认值：Inherit。 如果将 SDDL 指定为输入，则它必须具有所有者、组和 dacl。 注意：只应指定一个 x-ms-file-permission 或 x-ms-file-permission-key。 type file_permission： str param permission_key：要为目录/文件设置的权限的键。 注意：只应指定一个 x-ms-file-permission 或 x-ms-file-permission-key。 type 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

必需

要中止的复制操作。 这可以是 ID，也可以是 FileProperties 的实例。

lease

ShareLeaseClient 或 str

如果文件具有活动租约，则为必需。 值可以是 ShareLeaseClient 对象，也可以是作为字符串的租约 ID。

版本 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

必需

建议的租约 ID，采用 GUID 字符串格式。 如果建议的租约 ID 格式不正确，则文件服务将返回 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 对象，也可以是作为字符串的租约 ID。

版本 12.1.0 中的新增功能。

timeout

int

设置操作的服务器端超时（以秒为单位）。 有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

返回

文件更新的属性 dict (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 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

返回

如果) 找不到指定的句柄，并且句柄数未能在 dict 中关闭，则 (关闭的句柄数可能为 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 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

返回

如果) 找不到指定的句柄，并且句柄数未能在 dict 中关闭，则 (关闭的句柄数可能为 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 时的示例：“Temporary|存档”。 file_attributes值不区分大小写。

file_creation_time

str 或 datetime

必需

文件的创建时间 默认值：现在。

file_last_write_time

str 或 datetime

必需

文件的上次写入时间 默认值：现在。

file_permission

str

必需

如果指定了权限 (应为目录/文件设置安全描述符) 。 如果权限大小 <= 8KB，则可以使用此标头，否则应使用 x-ms-file-permission-key 标头。 默认值：Inherit。 如果将 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 对象，也可以是字符串格式的租用 ID。

版本 12.1.0 中的新增功能。

timeout

int

设置操作的服务器端超时时间（以秒为单位）。 有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

返回

文件更新的属性 dict (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 对象，也可以是字符串格式的租用 ID。

版本 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 () 将文件下载到流中。 使用 chunks () 将返回一个迭代器，该迭代器允许用户循环访问区块中的内容。

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， (默认) 已验证，则这主要用于检测网络上的 bitflips。 请注意，此 MD5 哈希不随 文件一起存储。 另请注意，如果启用，将不会使用内存高效上传算法，因为计算 MD5 哈希需要缓冲整个块，这样做会破坏内存高效算法的用途。

lease

ShareLeaseClient 或 str

如果文件具有活动租约，则为必需。 值可以是 ShareLeaseClient 对象，也可以是字符串格式的租用 ID。

版本 12.1.0 中的新增功能。

progress_hook

Callable[[int, int], None]

用于跟踪长时间运行的下载进度的回调。 签名是函数 (current： 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

要对其操作的可选文件快照。 这可以是快照 ID 字符串或从 create_snapshot返回的响应。

credential

默认值: None

用于进行身份验证的凭据。 如果帐户 URL 已有 SAS 令牌，则这是可选的。 该值可以是 SAS 令牌字符串、AzureSasCredential 的实例或 azure.core.credentials 中的 AzureNamedKeyCredential、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。 如果资源 URI 已包含 SAS 令牌，则会忽略此令牌，转而使用显式凭据

• AzureSasCredential 的情况除外，其中冲突的 SAS 令牌将引发 ValueError。 如果使用 AzureNamedKeyCredential 的实例，则“name”应为存储帐户名称，“密钥”应为存储帐户密钥。

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

要对其操作的可选文件快照。 这可以是快照 ID 字符串或从 create_snapshot返回的响应。

credential

默认值: None

用于进行身份验证的凭据。 如果帐户 URL 已有 SAS 令牌，则这是可选的。 该值可以是 SAS 令牌字符串、AzureSasCredential 的实例或 azure.core.credentials 中的 AzureNamedKeyCredential、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。 如果资源 URI 已包含 SAS 令牌，则会忽略此令牌，转而使用显式凭据

• AzureSasCredential 的情况除外，其中冲突的 SAS 令牌将引发 ValueError。 如果使用 AzureNamedKeyCredential 的实例，则“name”应为存储帐户名称，“密钥”应为存储帐户密钥。

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 对象，也可以是字符串格式的租用 ID。

版本 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 对象，也可以是字符串格式的租用 ID。

版本 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 对象，也可以是字符串格式的租用 ID。

timeout

int

设置操作的服务器端超时时间（以秒为单位）。 有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

返回

包含两个文件范围列表的元组，作为带有“start”和“end”键的字典。 第一个元素是填充的文件范围，第二个元素是清除的文件范围。

返回类型

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 对象，也可以是字符串格式的租用 ID。

destination_lease

ShareLeaseClient 或 str

如果目标文件具有活动租约，则为必需。 值可以是 ShareLeaseClient 对象，也可以是字符串格式的租用 ID。

返回

新的文件客户端。

返回类型

ShareFileClient

resize_file

将文件调整为指定大小。

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

参数

size

int

必需

将文件大小调整为 (的大小（以字节) 为单位）

lease

ShareLeaseClient 或 str

如果文件具有活动租约，则为必需。 值可以是 ShareLeaseClient 对象，也可以是字符串格式的租用 ID。

版本 12.1.0 中的新增功能。

timeout

int

设置操作的服务器端超时时间（以秒为单位）。 有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

返回

文件更新的属性 dict (Etag 和上次修改) 。

返回类型

Dict[str, Any]

set_file_metadata

将指定文件的用户定义元数据设置为一个或多个名称/值对。

每次调用此操作都会替换附加到该文件的所有现有元数据。 若要从文件中删除所有元数据，请调用此操作，不带元数据 dict。

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

参数

metadata

dict(str, str)

必需

作为元数据、与文件关联的名称-值对。

lease

ShareLeaseClient 或 str

如果文件具有活动租约，则为必需。 值可以是 ShareLeaseClient 对象，也可以是字符串格式的租用 ID。

版本 12.1.0 中的新增功能。

timeout

int

设置操作的服务器端超时时间（以秒为单位）。 有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

返回

文件更新的属性 dict (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 时的示例：“Temporary|存档'

file_creation_time

str 或 datetime

必需

文件的创建时间 默认值：保留。

file_last_write_time

str 或 datetime

必需

文件的上次写入时间 默认值：保留。

file_permission

str

必需

如果指定了权限 (应为目录/文件设置安全描述符) 。 如果权限大小 <= 8KB，则可以使用此标头，否则应使用 x-ms-file-permission-key 标头。 默认值：Inherit。 如果将 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 对象，也可以是字符串格式的租用 ID。

版本 12.1.0 中的新增功能。

timeout

int

设置操作的服务器端超时时间（以秒为单位）。 有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

返回

文件更新的属性 dict (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

如果指定了权限 (应为目录/文件设置安全描述符) 。 此值可以设置为“source”，以便从源文件复制安全描述符。 否则，如果设置，此值将用于替代源值。 如果未设置，则权限值继承自目标文件的父目录。 如果权限大小 <= 8KB，则可以使用此设置，否则应使用permission_key。 如果将 SDDL 指定为输入，则它必须具有所有者、组和 dacl。 注意：只应指定一个file_permission或permission_key。

版本 12.1.0 中的新增功能：此参数是在 API 版本“2019-07-07”中引入的。

permission_key

str

要为目录/文件设置的权限的键。 此值可以设置为“source”，以便从源文件复制安全描述符。 否则，如果设置，此值将用于替代源值。 如果未设置，则权限值继承自目标文件的父目录。 注意：只应指定一个file_permission或permission_key。

版本 12.1.0 中的新增功能：此参数是在 API 版本“2019-07-07”中引入的。

file_attributes

NTFSAttributes

此值可以设置为“source”，以将源文件中的文件属性复制到目标文件，或者要清除所有属性，可以将该值设置为“None”。 否则，可以将其设置为要对目标文件设置的属性列表。 如果未设置此值，则默认值为“Archive”。

版本 12.1.0 中的新增功能：此参数是在 API 版本“2019-07-07”中引入的。

file_creation_time

str 或 datetime

此值可以设置为“source”以将创建时间从源文件复制到目标文件，或者将日期时间设置为目标文件的创建时间。 这也可以是 ISO 8601 格式的字符串。 如果未设置，则创建时间将设置为创建 (的日期时间值，或者当它被复制引擎) 目标文件覆盖时。

版本 12.1.0 中的新增功能：此参数是在 API 版本“2019-07-07”中引入的。

file_last_write_time

str 或 datetime

此值可以设置为“source”以将上次写入时间从源文件复制到目标文件，或设置为目标文件上最后一次写入时间的日期时间。 这也可以是 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 对象，也可以是字符串格式的租用 ID。

版本 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 int length：文件的长度（以字节为单位）。 指定其最大大小，最大为 1 TiB。

param file_attributes：文件和目录的文件系统属性。 如果未设置，则默认值为“None”，属性将设置为“Archive”。 下面是 var 类型为 str 时的示例：“Temporary|存档”。 file_attributes值不区分大小写。

type file_attributes：str 或 ~azure.storage.fileshare.NTFSAttributes

param file_creation_time：文件的创建时间 默认值：现在。

type file_creation_time：str 或 ~datetime.datetime

param file_last_write_time：文件的上次写入时间 默认值：现在。

type file_last_write_time：str 或 ~datetime.datetime

param file_permission：如果指定了权限 (应为目录/文件设置安全描述符) 。 如果权限大小 <= 8KB，则可以使用此标头，否则应使用 x-ms-file-permission-key 标头。 默认值：Inherit。 如果将 SDDL 指定为输入，则它必须具有所有者、组和 dacl。 注意：只应指定一个 x-ms-file-permission 或 x-ms-file-permission-key。

type file_permission： str

param permission_key：要为目录/文件设置的权限的键。 注意：只应指定一个 x-ms-file-permission 或 x-ms-file-permission-key。

type 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

关键字 (keyword) dict (str，str) 元数据：与作为元数据的文件关联的名称-值对。

关键字 (keyword) ~azure.storage.fileshare.ContentSettings content_settings：用于设置文件属性的 ContentSettings 对象。 用于设置内容类型、编码、语言、处置、md5 和缓存控制。

关键字 (keyword) bool validate_content：如果为 true，则计算文件的每个范围的 MD5 哈希。 存储服务会检查随发送的哈希一起到达的内容的哈希。 如果使用 http 而不是 https 作为 https， (默认) 已验证，则这主要用于检测网络上的 bitflips。 请注意，此 MD5 哈希不随 文件一起存储。

关键字 (keyword) int max_concurrency：要使用的最大并行连接数。

关键字 (keyword) 租约：如果文件具有活动租约，则为必需项。 值可以是 ShareLeaseClient 对象，也可以是字符串格式的租用 ID。

版本 12.1.0 中的新增功能。

paramtype lease：~azure.storage.fileshare.ShareLeaseClient or str

关键字 (keyword) progress_hook：用于跟踪长时间运行的上传进度的回调。 签名是函数 (current： int， total： Optional[int]) 其中 current 是到目前为止传输的字节数，而 total 是 blob 的大小，如果大小未知，则为 None。

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

关键字 (keyword) int 超时：设置操作的服务器端超时时间（以秒为单位）。 有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

关键字 (keyword) str 编码：默认为 UTF-8。

返回结果：文件更新的属性 dict (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， (默认) 已验证，则这主要用于检测网络上的 bitflips。 请注意，此 MD5 哈希不随 文件一起存储。

file_last_write_mode

Literal["preserve", "now"]

是否应保留或覆盖文件上次写入时间。 可能的值为“preserve”或“now”。 如果未指定，文件上次写入时间将更改为当前日期/时间。

版本 12.8.0 中的新增功能：此参数是在 API 版本“2021-06-08”中引入的。

lease

ShareLeaseClient 或 str

如果文件具有活动租约，则为必需。 值可以是 ShareLeaseClient 对象，也可以是字符串格式的租用 ID。

版本 12.1.0 中的新增功能。

timeout

int

设置操作的服务器端超时时间（以秒为单位）。 有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

encoding

str

默认为 UTF-8。

返回

文件更新的属性 dict (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。 此值应为 URL 编码，如同它显示在请求 URI 中那样。 如果源位于另一个帐户中，则源必须是公共的，或者必须通过共享访问签名进行身份验证。 如果源是公共的，则无需身份验证。 示例：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 对象，也可以是字符串格式的租用 ID。

版本 12.1.0 中的新增功能。

timeout

int

设置操作的服务器端超时时间（以秒为单位）。 有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

source_authorization

str

使用客户端密码作为服务主体进行身份验证，以访问源 Blob。 确保“持有者”是source_authorization字符串的前缀。

属性

api_version

用于请求的存储 API 的版本。

location_mode

客户端当前使用的位置模式。

默认情况下，此为“主要”。 选项包括“主要”和“secondary”。

primary_endpoint

完整的主终结点 URL。

primary_hostname

主终结点的主机名。

secondary_endpoint

完整的辅助终结点 URL（如果已配置）。

如果不可用，将引发 ValueError。 若要显式指定辅助主机名，请在实例化时使用可选的 secondary_hostname 关键字 (keyword) 参数。

例外

ValueError

secondary_hostname

辅助终结点的主机名。

如果不可用，则为“无”。 若要显式指定辅助主机名，请在实例化时使用可选的 secondary_hostname 关键字 (keyword) 参数。

url

此实体的完整终结点 URL，包括 SAS 令牌（如果使用）。

这可以是主终结点，也可以是辅助终结点，具体取决于当前 location_mode。 ：returns：此实体的完整终结点 URL，包括 SAS 令牌（如果使用）。 :rtype：str