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

ShareClient 类

参考

用于与特定共享交互的客户端，尽管该共享可能尚不存在。

对于与此共享中的特定目录或文件相关的操作，也可以使用和 get_file_client 函数检索这些实体的get_directory_client客户端。

有关更多可选配置，请单击此处。

继承: azure.storage.fileshare._shared.base_client.StorageAccountHostsMixin

ShareClient

构造函数

ShareClient(account_url: str, share_name: 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_share_url classmethod。

share_name: 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”应为存储帐户名称，“密钥”应为存储帐户密钥。

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。

方法

acquire_lease	请求新的租约。如果共享没有活动租约，则共享服务将在共享上创建租约并返回新的租约。版本 12.5.0 中的新增功能。
close	此方法用于关闭客户端打开的套接字。与上下文管理器一起使用时，不需要使用它。
create_directory	在共享中创建一个目录，并返回一个要与该目录交互的客户端。
create_permission_for_share	在共享级别创建权限 (安全描述符) 。此“权限”可用于共享中的文件/目录。如果“权限”已存在，则应返回其密钥，否则在共享级别创建一个新权限并返回其密钥。
create_share	在帐户下创建新的共享。如果已存在同名的共享，则操作将失败。
create_snapshot	创建共享快照。快照是在某个时间点获取的共享的只读版本。它可以读取、复制或删除，但不能修改。快照提供了一种备份共享的方法，因为它出现在某个时刻。共享快照与从中获取快照的基本共享同名，并追加 DateTime 值以指示获取快照的时间。
delete_directory	标记要删除的目录。稍后在垃圾回收期间删除该目录。
delete_share	标记要删除的指定共享。稍后在垃圾回收期间删除该共享。
from_connection_string	从连接字符串创建 ShareClient。
from_share_url
get_directory_client	获取要与指定目录交互的客户端。该目录不需要已经存在。
get_file_client	获取要与指定文件交互的客户端。该文件不需要已经存在。
get_permission_for_share	获取给定密钥 (安全描述符) 的权限。此“权限”可用于共享中的文件/目录。
get_share_access_policy	获取共享的权限。权限指示是否可以公开访问共享中的文件。
get_share_properties	返回指定共享的所有用户定义元数据和系统属性。返回的数据不包括共享的文件或目录列表。
get_share_stats	获取存储在共享上的数据的近似大小（以字节为单位）。请注意，此值可能不包括最近创建或最近重新调整大小的所有文件。
list_directories_and_files	列出共享下的目录和文件。
set_share_access_policy	设置共享或存储访问策略的权限，这些策略可与共享访问签名一起使用。权限指示共享中的文件是否可以公开访问。
set_share_metadata	设置共享的元数据。每次调用此操作都会替换附加到该共享的所有现有元数据。若要从共享中删除所有元数据，请在不带元数据 dict 的情况下调用此操作。
set_share_properties	设置共享属性。版本 12.4.0 中的新增功能。
set_share_quota	设置共享的配额。

acquire_lease

请求新的租约。

如果共享没有活动租约，则共享服务将在共享上创建租约并返回新的租约。

版本 12.5.0 中的新增功能。

acquire_lease(**kwargs: Any) -> ShareLeaseClient

参数

lease_duration: int

指定租约的持续时间（秒），或者指定 -1 以表示永不过期的租约。有限期租约在 15 到 60 秒之间。不能使用续订或更改来更改租约持续时间。默认值为 -1， (无限租约) 。

lease_id: str

建议的租约 ID，采用 GUID 字符串格式。如果建议的租约 ID 格式不正确，共享服务将返回 400 (无效请求) 。

timeout: int

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

ShareLeaseClient 对象。

返回类型

ShareLeaseClient

示例

获取共享上的租约。


   share.create_directory("mydir")
   lease = share.acquire_lease()
   share.get_share_properties(lease=lease)
   share.delete_share(lease=lease)

close

此方法用于关闭客户端打开的套接字。与上下文管理器一起使用时，不需要使用它。

close()

create_directory

在共享中创建一个目录，并返回一个要与该目录交互的客户端。

create_directory(directory_name: str, **kwargs: Any) -> ShareDirectoryClient

参数

directory_name: str

必需

目录名。

metadata

与作为元数据的目录关联的名称/值对。

timeout: int

ShareDirectoryClient

返回类型

ShareDirectoryClient

在共享级别创建权限 (安全描述符) 。

此“权限”可用于共享中的文件/目录。如果“权限”已存在，则应返回其密钥，否则在共享级别创建一个新权限并返回其密钥。

create_permission_for_share(file_permission: str, **kwargs: Any) -> str

参数

file_permission: str

必需

文件权限，可移植 SDDL

timeout: int

文件权限密钥

返回类型

str

在帐户下创建新的共享。如果已存在同名的共享，则操作将失败。

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

参数

metadata: dict(str,str)

与作为元数据的共享关联的名称/值对。

quota: int

要分配的配额。

access_tier

指定共享的访问层。可能的值：“TransactionOptimized”、“Hot”、“Cool”

timeout: int

protocols: str 或 ShareProtocols

要对共享启用的协议。共享上只能启用一个协议。

root_squash: str 或 ShareRootSquash

要对共享设置的根 squash。仅对 NFS 共享有效。可能的值包括：“NoRootSquash”、“RootSquash”、“AllSquash”。

共享更新的属性 dict (Etag 和上次修改) 。

返回类型

Dict[str, Any]

示例

创建文件共享。


   # Create share with Access Tier set to Hot
   share.create_share(access_tier=ShareAccessTier("Hot"))

create_snapshot

创建共享快照。

快照是在某个时间点获取的共享的只读版本。它可以读取、复制或删除，但不能修改。快照提供了一种备份共享的方法，因为它出现在某个时刻。

共享快照与从中获取快照的基本共享同名，并追加 DateTime 值以指示获取快照的时间。

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

参数

metadata: dict(str,str)

与作为元数据的共享关联的名称/值对。

timeout: int

共享更新的属性 dict (快照 ID、Etag 和上次修改) 。

返回类型

dict[str, Any]

示例

创建文件共享的快照。


   share.create_snapshot()

delete_directory

标记要删除的目录。稍后在垃圾回收期间删除该目录。

delete_directory(directory_name: str, **kwargs: Any) -> None

参数

directory_name: str

必需

目录名。

timeout: int

返回类型

None

标记要删除的指定共享。稍后在垃圾回收期间删除该共享。

delete_share(delete_snapshots: bool | None = False, **kwargs) -> None

参数

delete_snapshots: bool

必需

指示是否要删除快照。

lease

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

版本 12.5.0 中的新增功能。

此关键字 (keyword) 参数是在 API 版本“2020-08-04”中引入的。

timeout: int

示例

删除共享和任何快照。


   share.delete_share(delete_snapshots=True)

from_connection_string

从连接字符串创建 ShareClient。

from_connection_string(conn_str: str, share_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 存储帐户的连接字符串。

share_name: str

必需

共享的名称。

snapshot: str

默认值: None

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

credential

默认值: None

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

共享客户端。

返回类型

ShareClient

示例

从连接字符串获取共享客户端。


   from azure.storage.fileshare import ShareClient
   share = ShareClient.from_connection_string(self.connection_string, "sharesamples2")

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

参数

share_url: str

必需

共享的完整 URI。

snapshot: str

默认值: None

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

credential

默认值: None

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

共享客户端。

返回类型

ShareClient

get_directory_client

获取要与指定目录交互的客户端。该目录不需要已经存在。

get_directory_client(directory_path: str | None = None) -> ShareDirectoryClient

参数

directory_path: str

默认值: None

指定目录的路径。

目录客户端。

返回类型

ShareDirectoryClient

get_file_client

获取要与指定文件交互的客户端。该文件不需要已经存在。

get_file_client(file_path: str) -> ShareFileClient

参数

file_path: str

必需

指定文件的路径。

文件客户端。

返回类型

ShareFileClient

获取给定密钥 (安全描述符) 的权限。

此“权限”可用于共享中的文件/目录。

get_permission_for_share(permission_key: str, **kwargs: Any) -> str

参数

permission_key: str

必需

要检索的文件权限的键

timeout: int

(可移植 SDDL) 的文件权限

返回类型

str

获取共享的权限。权限指示是否可以公开访问共享中的文件。

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

参数

timeout: int

lease

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

版本 12.5.0 中的新增功能。

此关键字 (keyword) 参数是在 API 版本“2020-08-04”中引入的。

访问 dict 中的策略信息。

返回类型

dict[str, Any]

返回指定共享的所有用户定义元数据和系统属性。返回的数据不包括共享的文件或目录列表。

get_share_properties(**kwargs: Any) -> ShareProperties

参数

timeout: int

lease

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

版本 12.5.0 中的新增功能。

此关键字 (keyword) 参数是在 API 版本“2020-08-04”中引入的。

共享属性。

返回类型

ShareProperties

示例

获取共享属性。


   properties = share.get_share_properties()

获取存储在共享上的数据的近似大小（以字节为单位）。

请注意，此值可能不包括最近创建或最近重新调整大小的所有文件。

get_share_stats(**kwargs: Any) -> int

参数

timeout: int

lease

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

版本 12.5.0 中的新增功能。

此关键字 (keyword) 参数是在 API 版本“2020-08-04”中引入的。

存储在共享上的数据) (的近似大小（以字节为单位）。

返回类型

int

list_directories_and_files

列出共享下的目录和文件。

list_directories_and_files(directory_name: str | None = None, name_starts_with: str | None = None, marker: str | None = None, **kwargs: Any) -> Iterable[Dict[str, str]]

参数

directory_name: str

必需

目录的名称。

name_starts_with: str

必需

筛选结果以仅返回名称以指定前缀开头的目录。

marker: str

必需

不透明的延续标记。可以从上一个生成器对象的 next_marker 字段中检索此值。如果指定，此生成器将从此开始返回结果。

include: list[str]

包含此参数可指定要包含在响应中的一个或多个数据集。可能的 str 值为“timestamps”、“Etag”、“Attributes”、“PermissionKey”。

版本 12.6.0 中的新增功能。

此关键字 (keyword) 参数是在 API 版本“2020-10-02”中引入的。

include_extended_info: bool

如果此值设置为 true，则会在列出的结果中返回文件 ID。

版本 12.6.0 中的新增功能。

此关键字 (keyword) 参数是在 API 版本“2020-10-02”中引入的。

timeout: int

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

类似于 dict 的 DirectoryProperties 和 FileProperties 的自动分页迭代

返回类型

Iterable[Dict[str,str]]

示例

列出共享中的目录和文件。


   # Create a directory in the share
   dir_client = share.create_directory("mydir")

   # Upload a file to the directory
   with open(SOURCE_FILE, "rb") as source_file:
       dir_client.upload_file(file_name="sample", data=source_file)

   # List files in the directory
   my_files = list(share.list_directories_and_files(directory_name="mydir"))
   print(my_files)

设置共享或存储访问策略的权限，这些策略可与共享访问签名一起使用。权限指示共享中的文件是否可以公开访问。

set_share_access_policy(signed_identifiers: Dict[str, AccessPolicy], **kwargs: Any) -> Dict[str, str]

参数

signed_identifiers: dict(str, AccessPolicy)

必需

要与共享关联的访问策略字典。字典最多可以包含 5 个元素。空字典将清除在服务上设置的访问策略。

timeout: int

lease

如果共享具有有效的租约，则为必需。值可以是 ShareLeaseClient 对象，也可以是作为字符串的租约 ID。

版本 12.5.0 中的新增功能。

API 版本“2020-08-04”中引入了此关键字 (keyword) 参数。

共享更新的属性 dict (Etag 和上次修改) 。

返回类型

dict(str, Any)

设置共享的元数据。

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

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

参数

metadata: dict(str, str)

必需

与共享关联的名称/值对（作为元数据）。

timeout: int

lease

如果共享具有有效的租约，则为必需。值可以是 ShareLeaseClient 对象，也可以是作为字符串的租约 ID。

版本 12.5.0 中的新增功能。

API 版本“2020-08-04”中引入了此关键字 (keyword) 参数。

共享更新的属性 dict (Etag 和上次修改) 。

返回类型

dict(str, Any)

示例

设置共享元数据。


   data = {'category': 'test'}
   share.set_share_metadata(metadata=data)

设置共享属性。

版本 12.4.0 中的新增功能。

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

参数

access_tier: str 或 <xref:azure.storage.fileshare.models.ShareAccessTier>

指定共享的访问层。可能的值：“TransactionOptimized”、“Hot”和“Cool”

quota: int

指定共享的最大大小 (GB)。必须大于 0，并且小于或等于 5TB。

timeout: int

root_squash: str 或 ShareRootSquash

要对共享设置的根 squash。仅对 NFS 共享有效。可能的值包括：“NoRootSquash”、“RootSquash”、“AllSquash”。

lease

如果共享具有有效的租约，则为必需。值可以是 ShareLeaseClient 对象，也可以是作为字符串的租约 ID。

共享更新的属性 dict (Etag 和上次修改) 。

返回类型

dict(str, Any)

示例

设置共享属性。


   # Set the tier for the first share to Hot
   share1.set_share_properties(access_tier="Hot")
   # Set the quota for the first share to 3
   share1.set_share_properties(quota=3)
   # Set the tier for the second share to Cool and quota to 2
   share2.set_share_properties(access_tier=ShareAccessTier("Cool"), quota=2)

   # Get the shares' properties
   print(share1.get_share_properties().access_tier)
   print(share1.get_share_properties().quota)
   print(share2.get_share_properties().access_tier)
   print(share2.get_share_properties().quota)

设置共享的配额。

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

参数

quota: int

必需

指定共享的最大大小 (GB)。必须大于 0，并且小于或等于 5TB。

timeout: int

lease

如果共享具有有效的租约，则为必需。值可以是 ShareLeaseClient 对象，也可以是作为字符串的租约 ID。

版本 12.5.0 中的新增功能。

API 版本“2020-08-04”中引入了此关键字 (keyword) 参数。

共享更新的属性 dict (Etag 和上次修改) 。

返回类型

dict(str, Any)

示例

设置共享配额。


   # Set the quota for the share to 1GB
   share.set_share_quota(quota=1)

属性

api_version

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

location_mode

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

默认情况下，此为“主要”。选项包括“primary”和“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

通过

ShareClient 类

构造函数

参数

方法

acquire_lease

参数

返回

返回类型

示例

close

create_directory

参数

返回

返回类型

create_permission_for_share

参数

返回

返回类型

create_share

参数

返回

返回类型

示例

create_snapshot

参数

返回

返回类型

示例

delete_directory

参数

返回类型

delete_share

参数

示例

from_connection_string

参数

返回

返回类型

示例

from_share_url

参数

返回

返回类型

get_directory_client

参数

返回

返回类型

get_file_client

参数

返回

返回类型

get_permission_for_share

参数

返回

返回类型

get_share_access_policy

参数

返回

返回类型

get_share_properties

参数

返回

返回类型

示例

get_share_stats

参数

返回

返回类型

list_directories_and_files

参数

返回

返回类型

示例

set_share_access_policy

参数

返回

返回类型

set_share_metadata

参数