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

FileService 类

目前，服务器消息块 (SMB) 协议是本地使用的首选文件共享协议。 Microsoft Azure 文件服务使客户能够利用 Azure 云基础结构即服务 (IaaS) SMB 的可用性和可伸缩性，而无需重写 SMB 客户端应用程序。

Azure 文件服务还提供了一种极具吸引力的解决方案，以替代传统的直连存储 (DAS) 和存储域网络 (SAN) 解决方案。通常，这些传统的解决方案安装、配置和操作起来很复杂，而且成本又高。

继承

StorageClient

FileService

构造函数

FileService(account_name=None, account_key=None, sas_token=None, protocol='https', endpoint_suffix='core.windows.net', request_session=None, connection_string=None, socket_timeout=None)

参数

名称	说明
account_name	str 存储帐户名称。 这用于对使用帐户密钥签名的请求进行身份验证，并构造存储终结点。 除非提供连接字符串，否则是必需的。 默认值: None
account_key	str 存储帐户密钥。 这用于共享密钥身份验证。 默认值: None
sas_token	str 用于对请求进行身份验证的共享访问签名令牌，而不是帐户密钥。 如果同时指定了帐户密钥和 sas 令牌，则将使用帐户密钥进行签名。 默认值: None
protocol	str 用于请求的协议。 默认为 https。 默认值: https
endpoint_suffix	str URL 的主机基组件，减去帐户名称。 默认为 Azure (core.windows.net) 。 重写此项以使用中国云 (core.chinacloudapi.cn) 。 默认值: core.windows.net
request_session	<xref:requests.Session> 用于 http 请求的会话对象。 默认值: None
connection_string	str 如果指定，这将替代除请求会话以外的所有其他参数。 有关连接字符串格式，请参阅 http://azure.microsoft.com/en-us/documentation/articles/storage-configure-connection-string/ 。 默认值: None
socket_timeout	int 如果指定，这将覆盖默认套接字超时。 指定的超时以秒为单位。 有关默认值，请参阅 _constants.py 中的DEFAULT_SOCKET_TIMEOUT。 默认值: None

变量

名称	说明
MAX_SINGLE_GET_SIZE	int 如果max_connections大于 1，则第一个区域的大小由 get_file_to_* 方法执行。 如果文件小于此，将返回较少的数据。
MAX_CHUNK_GET_SIZE	int 如果max_connections大于 1 且文件大于 MAX_SINGLE_GET_SIZE，则后续区域的大小由 get_file_to_* 方法执行。 如果文件的其余部分小于此值，则返回的数据将更少。 如果此值设置为大于 4MB，content_validation将引发错误（如果启用）。 但是，如果不需要content_validation，则大于 4MB 的大小可能是最佳选择。 不建议将此设置为 4MB 以下。
MAX_RANGE_SIZE	int create_file_from_* 方法放置的范围的大小。 如果提供的数据较少，则可能会放置较小的范围。 服务支持的最大范围大小为 4MB。

方法

abort_copy_file	中止挂起的copy_file操作，并将目标文件保留为零长度和完整元数据。
clear_range	清除指定范围并释放存储中用于该范围的空间。
close_handles	返回一个生成器，用于关闭目录或指定共享下的文件上打开的句柄。 生成器将延迟跟踪服务返回的延续令牌，并在关闭所有句柄后停止。 产生的值表示在每个事务中关闭的句柄数。
copy_file	异步复制文件。 此操作返回复制操作属性对象，包括可用于检查或中止复制操作的副本 ID。 文件服务会尽力复制文件。 如果目标文件存在，它将被覆盖。 复制操作正在进行时，无法修改目标文件。
create_directory	在指定的共享目录或父目录下创建新目录。 如果已存在同名的目录，则服务上的操作将失败。 默认情况下，异常由客户端吞咽。 若要公开异常，请为 fail_on_exists 指定 True。
create_file	创建新文件。 有关使用自动分块和进度通知处理大型文件的创建和上传的高级函数，请参阅create_file_from_*。
create_file_from_bytes	使用自动分块和进度通知从字节数组创建新文件，或更新现有文件的内容。
create_file_from_path	从本地文件路径创建新的 Azure 文件，或使用自动分块和进度通知更新现有文件的内容。
create_file_from_stream	使用自动分块和进度通知从文件/流创建新文件，或更新现有文件的内容。
create_file_from_text	使用自动分块和进度通知从 str/unicode 创建新文件，或更新现有文件的内容。
create_permission_for_share	在共享级别 (安全描述符) 创建权限。 此“权限”可用于共享中的文件/目录。 如果“权限”已存在，应返回其密钥，否则会在共享级别创建新权限并返回其密钥。 ：returns 文件权限键 ：rtype str
create_share	在指定的帐户下创建新共享。 如果已存在同名共享，则服务上的操作将失败。 默认情况下，异常由客户端吞咽。 若要公开异常，请为fail_on_exists指定 True。
delete_directory	删除指定的空目录。 请注意，目录必须是空的，然后才能将其删除。 尝试删除不为空的目录将失败。 如果该目录不存在，则服务上的操作将失败。 默认情况下，异常由客户端吞没。 若要公开异常，请为fail_not_exist指定 True。
delete_file	标记要删除的指定文件。 稍后在垃圾回收期间删除该文件。
delete_share	标记要删除的指定共享。 如果共享不存在，则服务上的操作会失败。 默认情况下，异常由客户端吞没。 若要公开异常，请为fail_not_exist指定 True。
exists	返回一个布尔值，该值指示如果只给定共享名称，则共享是否存在。 如果指定directory_name，将返回一个布尔值，指示目录是否存在。 如果还指定了file_name，则将返回一个布尔值，指示文件是否存在。
extract_date_and_request_id
generate_account_shared_access_signature	为文件服务生成共享访问签名。 将返回的签名与 FileService 的 sas_token 参数一起使用。
generate_file_shared_access_signature	为文件生成共享访问签名。 将返回的签名与 fileService 的 sas_token 参数一起使用。
generate_share_shared_access_signature	为共享生成共享访问签名。 将返回的签名与 FileService 的 sas_token 参数一起使用。
get_directory_metadata	返回指定目录的所有用户定义的元数据。
get_directory_properties	返回指定目录的所有用户定义的元数据和系统属性。 返回的数据不包括目录的文件列表。
get_file_metadata	返回指定文件的所有用户定义的元数据。
get_file_properties	返回文件的所有用户定义的元数据、标准 HTTP 属性和系统属性。 返回 的实例 File 和 FileProperties 元数据听写。
get_file_service_properties	获取存储帐户的文件服务的属性，包括 Azure 存储分析。
get_file_to_bytes	以字节数组的形式下载文件，其中包含自动分块和进度通知。 返回具有属性、元数据和内容的 实例 File 。
get_file_to_path	使用自动分块和进度通知将文件下载到文件路径。 返回具有属性和元数据的 File 实例。
get_file_to_stream	使用自动分块和进度通知将文件下载到流。 返回具有属性和元数据的 File 实例。
get_file_to_text	以 unicode 文本的形式下载文件，并自动分块和进度通知。 返回具有属性、元数据和内容的 实例 File 。
get_permission_for_share	在共享级别 (安全描述符) 创建权限。 此“权限”可用于共享中的文件/目录。 如果“权限”已存在，则应返回其密钥，否则在共享级别创建一个新权限并返回其密钥。 ：返回 (可移植 SDDL) 的文件权限：rtype str
get_share_acl	获取指定共享的权限。
get_share_metadata	返回指定共享的所有用户定义的元数据。
get_share_properties	返回指定共享的所有用户定义的元数据和系统属性。 返回的数据不包括共享的文件或目录列表。
get_share_stats	获取存储在共享上的数据的近似大小，向上舍入为最接近的 GB。 请注意，此值可能不包括最近创建或最近重新调整大小的所有文件。
get_share_stats_in_bytes	获取存储在共享上的数据的近似大小（以字节为单位）。 请注意，此值可能不包括最近创建或最近重新调整大小的所有文件。
list_directories_and_files	返回一个生成器，用于列出指定共享下的目录和文件。 生成器将延迟跟踪服务返回的继续标记，并在返回所有目录和文件或到达num_results时停止。 如果指定了num_results，并且共享的文件和目录数超过该数目，则生成器在完成时将具有填充next_marker字段。 如果需要更多结果，可以使用此标记创建新的生成器。
list_handles	返回一个生成器，用于列出目录或指定共享下的文件上打开的句柄。 生成器将延迟跟踪服务返回的继续标记，并在返回所有句柄或到达num_results时停止。 如果指定了num_results，并且共享的文件和目录数超过该数目，则生成器在完成时将具有填充next_marker字段。 如果需要更多结果，可以使用此标记创建新的生成器。
list_ranges	检索文件的有效范围。
list_shares	返回一个生成器，用于列出指定帐户下的共享。 生成器将延迟跟踪服务返回的延续令牌，并在返回所有共享或达到num_results时停止。 如果指定了num_results，并且帐户的共享数超过该数目，则生成器在完成时将具有填充next_marker字段。 如果需要更多结果，可以使用此标记创建新的生成器。
make_file_url	创建用于访问文件的 URL。
resize_file	将文件调整为指定大小。 如果指定的字节值小于当前的文件大小，则会清除超过指定字节值的所有范围。
set_directory_metadata	为指定目录设置一个或多个用户定义的名称/值对。 每次调用此操作都会替换附加到该目录的所有现有元数据。 若要从目录中删除所有元数据，请调用此操作，不带元数据听写。
set_directory_properties
set_file_metadata	将指定文件的用户定义元数据设置为一个或多个名称/值对。
set_file_properties	设置文件上的系统属性。 如果为content_settings设置了一个属性，则将重写所有属性。
set_file_service_properties	设置存储帐户的文件服务的属性，包括 Azure 存储分析。 如果某个元素 (ex HourMetrics) 保留为 None，则保留该服务上针对该功能的现有设置。
set_proxy	设置 HTTP CONNECT 隧道的代理服务器主机和端口。
set_share_acl	设置可与共享访问签名一起使用的指定共享或存储访问策略的权限。
set_share_metadata	为指定的共享设置一个或多个用户定义的名称/值对。 每次调用此操作都会替换附加到该共享的所有现有元数据。 若要从共享中删除所有元数据，请在不带元数据 dict 的情况下调用此操作。
set_share_properties	设置指定共享的服务定义属性。
snapshot_share	在指定帐户下创建现有共享的快照。
update_range	将请求正文指定的字节写入指定范围。
update_range_from_file_url	将一个 Azure 文件终结点中的字节写入另一个 Azure 文件终结点的指定范围。

abort_copy_file

中止挂起的copy_file操作，并将目标文件保留为零长度和完整元数据。

abort_copy_file(share_name, directory_name, file_name, copy_id, timeout=None)

参数

名称	说明
share_name 必需	str 目标共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 目标文件的名称。
copy_id 必需	str 原始copy_file操作 copy.id 中提供的复制标识符。
timeout	int 超时参数以秒表示。 默认值: None

clear_range

清除指定范围并释放存储中用于该范围的空间。

clear_range(share_name, directory_name, file_name, start_range, end_range, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
start_range 必需	int 用于清除文件的某一部分的字节范围的起始。 范围最大可以为 4 MB。 start_range和end_range参数是包容性的。 例如：start_range=0，end_range=511 将下载前 512 个字节的文件。
end_range 必需	int 用于清除文件的某个部分的字节范围的结束。 范围最大可以为 4 MB。 start_range和end_range参数是包容性的。 例如：start_range=0，end_range=511 将下载前 512 个字节的文件。
timeout	int 超时参数以秒表示。 默认值: None

close_handles

返回一个生成器，用于关闭目录或指定共享下的文件上打开的句柄。 生成器将延迟跟踪服务返回的延续令牌，并在关闭所有句柄后停止。 产生的值表示在每个事务中关闭的句柄数。

close_handles(share_name, directory_name=None, file_name=None, recursive=None, handle_id=None, marker=None, snapshot=None, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name	str 目录的路径。 默认值: None
file_name	str 现有文件的名称。 默认值: None
recursive	bool 布尔值，指定操作是否应应用于 URI 中指定的目录、其文件、子目录及其文件。 默认值: None
handle_id	str 必需。 指定要关闭的文件或目录上打开的句柄 ID。 Astrix ('*') 是指定所有句柄的通配符。 默认值: None
marker	str 不透明的延续标记。 如果上一个生成器对象的next_marker字段尚未完成关闭句柄，则可以从该值检索该值。 如果指定，此生成器将从上一个生成器停止的点开始关闭句柄。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None
timeout	int 超时参数以秒表示。 默认值: None

copy_file

异步复制文件。 此操作返回复制操作属性对象，包括可用于检查或中止复制操作的副本 ID。 文件服务会尽力复制文件。

如果目标文件存在，它将被覆盖。 复制操作正在进行时，无法修改目标文件。

copy_file(share_name, directory_name, file_name, copy_source, metadata=None, timeout=None)

参数

名称	说明
share_name 必需	str 目标共享的名称。 共享必须存在。
directory_name 必需	str 目标目录的名称。 该目录必须存在。
file_name 必需	str 目标文件的名称。 如果目标文件存在，它将被覆盖。 如果不存在，则创建该 URI。
copy_source 必需	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
metadata	dict(str, str)<xref:./> 作为元数据、与文件关联的名称-值对。 如果未指定名称/值对，则操作会将元数据从源 Blob 或文件复制到目标文件。 如果指定了一个或多个名称/值对，则使用指定的元数据创建目标文件，并且不会从源 Blob 或文件复制元数据。 默认值: None
timeout	int 超时参数以秒表示。 默认值: None

返回

类型	说明
CopyProperties	复制操作属性，例如状态、源和 ID。

create_directory

在指定的共享目录或父目录下创建新目录。 如果已存在同名的目录，则服务上的操作将失败。 默认情况下，异常由客户端吞咽。 若要公开异常，请为 fail_on_exists 指定 True。

create_directory(share_name, directory_name, metadata=None, fail_on_exist=False, timeout=None, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 要创建的目录的名称，包括父目录的路径。
metadata	dict(str, str)<xref::> 一个包含name_value对的 dict，以元数据的形式与共享相关联。 示例：{'Category'：'test'} 默认值: None
fail_on_exist	bool 指定在目录存在时是否引发异常。 默认值为 False。 默认值: False
file_permission	str 文件权限，可移植 SDDL 默认值: None
smb_properties	SMBProperties 设置与 SMB 相关的文件属性
timeout	int 超时参数以秒表示。 默认值: None

返回

类型	说明
bool	如果已创建目录，则为 True;如果目录已存在，则为 False。

create_file

创建新文件。

有关使用自动分块和进度通知处理大型文件的创建和上传的高级函数，请参阅create_file_from_*。

create_file(share_name, directory_name, file_name, content_length, content_settings=None, metadata=None, timeout=None, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 要创建或更新的文件的名称。
content_length 必需	int 文件的长度（以字节为单位）。
content_settings	ContentSettings 用于设置文件属性的 ContentSettings 对象。 默认值: None
metadata	dict(str, str) 作为元数据、与文件关联的名称-值对。 默认值: None
file_permission	str 文件权限，可移植 SDDL 默认值: None
smb_properties	SMBProperties 设置与 SMB 相关的文件属性
timeout	int 超时参数以秒表示。 默认值: None

create_file_from_bytes

使用自动分块和进度通知从字节数组创建新文件，或更新现有文件的内容。

create_file_from_bytes(share_name, directory_name, file_name, file, index=0, count=None, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 要创建或更新的文件的名称。
file 必需	str 作为字节数组的文件内容。
index	int 开始字节数组中的索引。 默认值: 0
count	int 要上传的字节数。 设置为“无”或“负值”，以上传从索引开始的所有字节。 默认值: None
content_settings	ContentSettings 用于设置文件属性的 ContentSettings 对象。 默认值: None
metadata	dict(str, str) 作为元数据、与文件关联的名称-值对。 默认值: None
validate_content	bool 如果为 true，则计算文件的每个范围的 MD5 哈希。 存储服务会检查已随发送的哈希一起到达的内容的哈希。 如果使用 http 而不是 https 作为 https，则这主要用于检测网络上的 bitflips， (默认) 已验证。 请注意，此 MD5 哈希不随 文件一起存储。 默认值: False
progress_callback	<xref:func>(<xref:current>, <xref:total>) 使用签名函数的进度回调 (当前、总计) ，其中 current 是到目前为止传输的字节数，total 是文件大小;如果总大小未知，则为 None。 默认值: None
max_connections	int 要使用的并行连接数上限。 默认值: 2
file_permission	str 文件权限，可移植 SDDL 默认值: None
smb_properties	SMBProperties 设置与 SMB 相关的文件属性
timeout	int 超时参数以秒表示。 此方法可能会对 Azure 服务进行多次调用，超时将分别应用于每个调用。 默认值: None

create_file_from_path

从本地文件路径创建新的 Azure 文件，或使用自动分块和进度通知更新现有文件的内容。

create_file_from_path(share_name, directory_name, file_name, local_file_path, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 要创建或更新的文件的名称。
local_file_path 必需	str 要作为文件内容上传的本地文件的路径。
content_settings	ContentSettings 用于设置文件属性的 ContentSettings 对象。 默认值: None
metadata	dict(str, str) 作为元数据、与文件关联的名称-值对。 默认值: None
validate_content	bool 如果为 true，则计算文件的每个范围的 MD5 哈希。 存储服务会检查已随发送的哈希一起到达的内容的哈希。 如果使用 http 而不是 https 作为 https，则这主要用于检测网络上的 bitflips， (默认) 已验证。 请注意，此 MD5 哈希不随 文件一起存储。 默认值: False
progress_callback	<xref:func>(<xref:current>, <xref:total>) 使用签名函数的进度回调 (当前、总计) ，其中 current 是到目前为止传输的字节数，total 是文件大小;如果总大小未知，则为 None。 默认值: None
max_connections	int 要使用的并行连接数上限。 默认值: 2
file_permission	str 文件权限，可移植 SDDL 默认值: None
smb_properties	SMBProperties 设置与 SMB 相关的文件属性
timeout	int 超时参数以秒表示。 此方法可能会对 Azure 服务进行多次调用，超时将分别应用于每个调用。 默认值: None

create_file_from_stream

使用自动分块和进度通知从文件/流创建新文件，或更新现有文件的内容。

create_file_from_stream(share_name, directory_name, file_name, stream, count, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 要创建或更新的文件的名称。
stream 必需	IOBase 已打开文件/流，以文件内容的形式上传。
count 必需	int 要从流中读取的字节数。 这是必需的，如果计数未知，则无法创建文件。
content_settings	ContentSettings 用于设置文件属性的 ContentSettings 对象。 默认值: None
metadata	dict(str, str) 作为元数据、与文件关联的名称-值对。 默认值: None
validate_content	bool 如果为 true，则计算文件的每个范围的 MD5 哈希。 存储服务会检查已随发送的哈希一起到达的内容的哈希。 如果使用 http 而不是 https 作为 https，则这主要用于检测网络上的 bitflips， (默认) 已验证。 请注意，此 MD5 哈希不随 文件一起存储。 默认值: False
progress_callback	<xref:func>(<xref:current>, <xref:total>) 使用签名函数的进度回调 (当前、总计) ，其中 current 是到目前为止传输的字节数，total 是文件大小;如果总大小未知，则为 None。 默认值: None
max_connections	int 要使用的并行连接数上限。 请注意，并行上传需要可查找流。 默认值: 2
file_permission	str 文件权限，可移植 SDDL 默认值: None
smb_properties	SMBProperties 设置与 SMB 相关的文件属性
timeout	int 超时参数以秒表示。 此方法可能会对 Azure 服务进行多次调用，超时将分别应用于每个调用。 默认值: None

create_file_from_text

使用自动分块和进度通知从 str/unicode 创建新文件，或更新现有文件的内容。

create_file_from_text(share_name, directory_name, file_name, text, encoding='utf-8', content_settings=None, metadata=None, validate_content=False, timeout=None, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 要创建或更新的文件的名称。
text 必需	str 要上传到文件的文本。
encoding	str 用于将文本转换为字节的 Python 编码。 默认值: utf-8
content_settings	ContentSettings 用于设置文件属性的 ContentSettings 对象。 默认值: None
metadata	dict(str, str) 作为元数据、与文件关联的名称-值对。 默认值: None
validate_content	bool 如果为 true，则计算文件的每个范围的 MD5 哈希。 存储服务会检查已随发送的哈希一起到达的内容的哈希。 如果使用 http 而不是 https 作为 https，则这主要用于检测网络上的 bitflips， (默认) 已验证。 请注意，此 MD5 哈希不随 文件一起存储。 默认值: False
file_permission	str 文件权限，可移植 SDDL 默认值: None
smb_properties	SMBProperties 设置与 SMB 相关的文件属性
timeout	int 超时参数以秒表示。 此方法可能会对 Azure 服务进行多次调用，超时将分别应用于每个调用。 默认值: None

create_permission_for_share

在共享级别 (安全描述符) 创建权限。 此“权限”可用于共享中的文件/目录。 如果“权限”已存在，应返回其密钥，否则会在共享级别创建新权限并返回其密钥。

：returns 文件权限键 ：rtype str

create_permission_for_share(share_name, file_permission, timeout=None)

参数

名称	说明
share_name 必需	共享的名称。
file_permission 必需	文件权限，可移植 SDDL
timeout	超时参数以秒表示。 默认值: None

create_share

在指定的帐户下创建新共享。 如果已存在同名共享，则服务上的操作将失败。 默认情况下，异常由客户端吞咽。 若要公开异常，请为fail_on_exists指定 True。

create_share(share_name, metadata=None, quota=None, fail_on_exist=False, timeout=None)

参数

名称	说明
share_name 必需	str 要创建的共享的名称。
metadata	dict(str, str) 一个包含name_value对的 dict，以元数据的形式与共享相关联。 示例：{'Category'：'test'} 默认值: None
quota	int 指定共享的最大大小 (GB)。 必须大于 0 且小于或等于 5 TB (5120)。 默认值: None
fail_on_exist	bool 指定在共享存在时是否引发异常。 默认值为 False。 默认值: False
timeout	int 超时参数以秒表示。 默认值: None

返回

类型	说明
bool	如果已创建共享，则为 True;如果共享已存在，则为 False。

delete_directory

删除指定的空目录。 请注意，目录必须是空的，然后才能将其删除。 尝试删除不为空的目录将失败。

如果该目录不存在，则服务上的操作将失败。 默认情况下，异常由客户端吞没。 若要公开异常，请为fail_not_exist指定 True。

delete_directory(share_name, directory_name, fail_not_exist=False, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 要删除的目录的名称，包括父目录的路径。
fail_not_exist	bool 指定在目录不存在时是否引发异常。 默认值: False
timeout	int 超时参数以秒表示。 默认值: None

返回

类型	说明
bool	如果删除目录，则为 True;否则为 False。

delete_file

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

delete_file(share_name, directory_name, file_name, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
timeout	int 超时参数以秒表示。 默认值: None

delete_share

标记要删除的指定共享。 如果共享不存在，则服务上的操作会失败。 默认情况下，异常由客户端吞没。 若要公开异常，请为fail_not_exist指定 True。

delete_share(share_name, fail_not_exist=False, timeout=None, snapshot=None, delete_snapshots=None)

参数

名称	说明
share_name 必需	str 要删除的共享的名称。
fail_not_exist	bool 指定当共享不存在时是否引发异常。 默认值为 False。 默认值: False
timeout	int 超时参数以秒表示。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 指定此参数以仅删除特定快照。 如果指定了此项，delete_snapshots必须为 None。 默认值: None
delete_snapshots	DeleteSnapshot 若要删除包含快照的共享，必须将其指定为 DeleteSnapshot.Include。 默认值: None

返回

类型	说明
bool	如此 如果共享被删除，假共享不存在。

exists

返回一个布尔值，该值指示如果只给定共享名称，则共享是否存在。 如果指定directory_name，将返回一个布尔值，指示目录是否存在。 如果还指定了file_name，则将返回一个布尔值，指示文件是否存在。

exists(share_name, directory_name=None, file_name=None, timeout=None, snapshot=None)

参数

名称	说明
share_name 必需	str 共享的名称。
directory_name	str 目录的路径。 默认值: None
file_name	str 文件的名称。 默认值: None
timeout	int 超时参数以秒表示。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

返回

类型	说明
bool	一个布尔值，指示资源是否存在。

extract_date_and_request_id

static extract_date_and_request_id(retry_context)

参数

名称	说明
retry_context 必需

generate_account_shared_access_signature

为文件服务生成共享访问签名。 将返回的签名与 FileService 的 sas_token 参数一起使用。

generate_account_shared_access_signature(resource_types, permission, expiry, start=None, ip=None, protocol=None)

参数

名称	说明
resource_types 必需	<xref:ResourceTypes> 指定可通过帐户 SAS 访问的资源类型。
permission 必需	<xref:AccountPermissions> 与共享访问签名关联的权限。 用户只能执行权限允许的操作。 必需，除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定，则必须省略此字段。
expiry 必需	datetime 或 str 共享访问签名失效的时间。 必需，除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定，则必须省略此字段。 Azure 始终会将值转换为 UTC。 如果传入的日期没有时区信息，则假定该日期为 UTC。
start	datetime 或 str 共享访问签名生效的时间。 如果省略，将假定此调用的开始时间就是存储服务收到请求的时间。 Azure 始终会将值转换为 UTC。 如果传入的日期没有时区信息，则假定该日期为 UTC。 默认值: None
ip	str 指定要从中接受请求的 IP 地址或 IP 地址范围。 如果请求源自的 IP 地址与 SAS 令牌上指定的 IP 地址或地址范围不匹配，则不会对请求进行身份验证。 例如，在 SAS 上指定 sip=168.1.5.65 或 sip=168.1.5.60-168.1.5.70 会将请求限制为这些 IP 地址。 默认值: None
protocol	str 指定所发出请求所允许的协议。 可能的值为 HTTPS 和 HTTP (https、http) 或仅 https) (HTTPS。 默认值为 https，http。 请注意，“仅限 HTTP”是不允许的值。 默认值: None

返回

类型	说明
str	共享访问签名 (sas) 令牌。

generate_file_shared_access_signature

为文件生成共享访问签名。 将返回的签名与 fileService 的 sas_token 参数一起使用。

generate_file_shared_access_signature(share_name, directory_name=None, file_name=None, permission=None, expiry=None, start=None, id=None, ip=None, protocol=None, cache_control=None, content_disposition=None, content_encoding=None, content_language=None, content_type=None)

参数

名称	说明
share_name 必需	str 共享的名称。
directory_name	str 目录的名称。 无法为目录创建 SAS 令牌，因此仅当提供了file_name时才应存在此参数。 默认值: None
file_name	str 文件的名称。 默认值: None
permission	FilePermissions 与共享访问签名关联的权限。 用户只能执行权限允许的操作。 权限必须排序读取、创建、写入、删除、列出。 必需，除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定，则必须省略此字段。 默认值: None
expiry	datetime 或 str 共享访问签名失效的时间。 必需，除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定，则必须省略此字段。 Azure 始终会将值转换为 UTC。 如果传入的日期没有时区信息，则假定该日期为 UTC。 默认值: None
start	datetime 或 str 共享访问签名生效的时间。 如果省略，将假定此调用的开始时间就是存储服务收到请求的时间。 Azure 始终会将值转换为 UTC。 如果传入的日期没有时区信息，则假定该日期为 UTC。 默认值: None
id	str 与存储访问策略相关的最大长度为 64 个字符的唯一值。 若要创建存储访问策略，请使用 set_file_service_properties。 默认值: None
ip	str 指定要从中接受请求的 IP 地址或 IP 地址范围。 如果请求源自的 IP 地址与 SAS 令牌上指定的 IP 地址或地址范围不匹配，则不会对请求进行身份验证。 例如，在 SAS 上指定 sip=168.1.5.65 或 sip=168.1.5.60-168.1.5.70 会将请求限制为这些 IP 地址。 默认值: None
protocol	str 指定所发出请求所允许的协议。 可能的值为 HTTPS 和 HTTP (https、http) 或仅 https) (HTTPS。 默认值为 https，http。 请注意，“仅限 HTTP”是不允许的值。 默认值: None
cache_control	str 使用此共享访问签名访问资源时 Cache-Control 的响应标头值。 默认值: None
content_disposition	str 使用此共享访问签名访问资源时 Content-Disposition 的响应标头值。 默认值: None
content_encoding	str 使用此共享访问签名访问资源时内容编码的响应标头值。 默认值: None
content_language	str 使用此共享访问签名访问资源时，Content-Language 的响应标头值。 默认值: None
content_type	str 使用此共享访问签名访问资源时，Content-Type 的响应标头值。 默认值: None

返回

类型	说明
str	共享访问签名 (sas) 令牌。

generate_share_shared_access_signature

为共享生成共享访问签名。 将返回的签名与 FileService 的 sas_token 参数一起使用。

generate_share_shared_access_signature(share_name, permission=None, expiry=None, start=None, id=None, ip=None, protocol=None, cache_control=None, content_disposition=None, content_encoding=None, content_language=None, content_type=None)

参数

名称	说明
share_name 必需	str 共享的名称。
permission	SharePermissions 与共享访问签名关联的权限。 用户只能执行权限允许的操作。 权限必须按顺序进行读取、创建、写入、删除、列表。 必需，除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定，则必须省略此字段。 默认值: None
expiry	datetime 或 str 共享访问签名变为无效的时间。 必需，除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定，则必须省略此字段。 Azure 将始终将值转换为 UTC。 如果传入的日期没有时区信息，则假定该日期为 UTC。 默认值: None
start	datetime 或 str 共享访问签名生效的时间。 如果省略，将假定此调用的开始时间就是存储服务收到请求的时间。 Azure 将始终将值转换为 UTC。 如果传入的日期没有时区信息，则假定该日期为 UTC。 默认值: None
id	str 一个唯一值，长度最多为 64 个字符，与存储访问策略相关。 若要创建存储访问策略，请使用 set_share_acl。 默认值: None
ip	str 指定从中接受请求的 IP 地址或 IP 地址范围。 如果请求源自的 IP 地址与 SAS 令牌上指定的 IP 地址或地址范围不匹配，则不会对请求进行身份验证。 例如，在 SAS 上指定 sip=168.1.5.65 或 sip=168.1.5.60-168.1.5.70 会将请求限制为这些 IP 地址。 默认值: None
protocol	str 指定允许发出的请求的协议。 可能的值为 HTTPS 和 HTTP (https、http) 或 HTTPS，仅 (https) 。 默认值为 https，http。 请注意，“仅限 HTTP”是不允许的值。 默认值: None
cache_control	str 使用此共享访问签名访问资源时 Cache-Control 的响应标头值。 默认值: None
content_disposition	str 使用此共享访问签名访问资源时的内容处置的响应标头值。 默认值: None
content_encoding	str 使用此共享访问签名访问资源时的内容编码的响应标头值。 默认值: None
content_language	str 使用此共享访问签名访问资源时的内容语言的响应标头值。 默认值: None
content_type	str 使用此共享访问签名访问资源时 Content-Type 的响应标头值。 默认值: None

返回

类型	说明
str	共享访问签名 (sas) 令牌。

get_directory_metadata

返回指定目录的所有用户定义的元数据。

get_directory_metadata(share_name, directory_name, timeout=None, snapshot=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
timeout	int 超时参数以秒表示。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

返回

类型	说明
dict(str, str)	表示目录元数据名称、值对的字典。

get_directory_properties

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

get_directory_properties(share_name, directory_name, timeout=None, snapshot=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 现有目录的路径。
timeout	int 超时参数以秒表示。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

返回

类型	说明
Directory	目录对象中指定目录的属性。

get_file_metadata

返回指定文件的所有用户定义的元数据。

get_file_metadata(share_name, directory_name, file_name, timeout=None, snapshot=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
timeout	int 超时参数以秒表示。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

返回

类型	说明
dict(str, str)	表示文件元数据名称、值对的字典。

get_file_properties

返回文件的所有用户定义的元数据、标准 HTTP 属性和系统属性。 返回 的实例 File 和 FileProperties 元数据听写。

get_file_properties(share_name, directory_name, file_name, timeout=None, snapshot=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
timeout	int 超时参数以秒表示。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

返回

类型	说明
File	包含属性和元数据的文件对象。

get_file_service_properties

获取存储帐户的文件服务的属性，包括 Azure 存储分析。

get_file_service_properties(timeout=None)

参数

名称	说明
timeout	int 超时参数以秒表示。 默认值: None

返回

类型	说明
ServiceProperties	文件服务属性。

get_file_to_bytes

以字节数组的形式下载文件，其中包含自动分块和进度通知。 返回具有属性、元数据和内容的 实例 File 。

get_file_to_bytes(share_name, directory_name, file_name, start_range=None, end_range=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None, snapshot=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
start_range	int 要用于下载文件的节的字节范围的起始。 如果未提供end_range，则将下载start_range后的所有字节。 start_range和end_range参数是包容性的。 例如：start_range=0，end_range=511 将下载前 512 个字节的文件。 默认值: None
end_range	int 用于下载文件的节的字节范围的结束。 如果提供了end_range，则必须提供start_range。 start_range和end_range参数是包容性的。 例如：start_range=0，end_range=511 将下载前 512 个字节的文件。 默认值: None
validate_content	bool 如果设置为 true，则验证文件每个检索部分的 MD5 哈希。 如果使用 http 而不是 https 作为 https，则这主要用于检测网络上的 bitflips， (默认) 已验证。 请注意，该服务将仅返回 4MB 或更小的区块的事务 MD5，因此第一个获取请求的大小为自身。MAX_CHUNK_GET_SIZE而不是自我。MAX_SINGLE_GET_SIZE。 如果为 self。MAX_CHUNK_GET_SIZE设置为大于 4MB，将引发错误。 由于计算 MD5 需要处理时间，并且由于区块大小减小，需要执行更多请求，延迟可能会有所增加。 默认值: False
progress_callback	<xref:func>(<xref:current>, <xref:total>) 签名函数的进度回调 (当前，总) ，其中 current 是到目前为止传输的字节数，总计是文件大小（如果已知）。 默认值: None
max_connections	int 如果设置为 2 或更大，则将为第一个自身完成初始获取。MAX_SINGLE_GET_SIZE个字节的文件。 如果这是整个文件，则 方法此时返回 。 如果不是，它将使用等于max_connections的线程数并行下载剩余数据。 每个区块的大小均为自身。MAX_CHUNK_GET_SIZE。 如果设置为 1，将完成单个大型获取请求。 通常不建议这样做，但如果应使用很少的线程、网络请求非常昂贵或不可查找的流阻止并行下载，则此选项可用。 如果同时修改文件以强制实施原子性，或者如果许多文件预期为空，如果max_connections大于 1，则需要对空文件执行额外的请求，则这也可能很有用。 默认值: 2
timeout	int 超时参数以秒表示。 此方法可能会对 Azure 服务进行多次调用，超时将分别应用于每个调用。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

返回

类型	说明
File	包含属性、内容和元数据的文件。

get_file_to_path

使用自动分块和进度通知将文件下载到文件路径。 返回具有属性和元数据的 File 实例。

get_file_to_path(share_name, directory_name, file_name, file_path, open_mode='wb', start_range=None, end_range=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None, snapshot=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
file_path 必需	str 要写入的文件的路径。
open_mode	str 打开文件时要使用的模式。 请注意，仅指定追加open_mode会阻止并行下载。 因此，如果使用此open_mode，必须将max_connections设置为 1。 默认值: wb
start_range	int 要用于下载文件的节的字节范围的起始。 如果未提供end_range，则将下载start_range后的所有字节。 start_range和end_range参数是包含的。 例如：start_range=0，end_range=511 将下载前 512 字节的文件。 默认值: None
end_range	int 用于下载文件的节的字节范围的结束。 如果提供了end_range，则必须提供start_range。 start_range和end_range参数是包含的。 例如：start_range=0，end_range=511 将下载前 512 字节的文件。 默认值: None
validate_content	bool 如果设置为 true，则验证文件的每个检索部分的 MD5 哈希。 如果使用 http 而不是 https 作为 https， (默认) 已验证，则这主要用于检测网络上的 bitflips。 请注意，该服务将仅返回 4MB 或更小区块的事务 MD5，因此第一个获取请求的大小为自身。MAX_CHUNK_GET_SIZE而不是自我。MAX_SINGLE_GET_SIZE。 如果为 self。MAX_CHUNK_GET_SIZE设置为大于 4MB，将引发错误。 由于计算 MD5 需要处理时间，并且由于区块大小减小，需要完成更多请求，延迟可能会有所增加。 默认值: False
progress_callback	<xref:func>(<xref:current>, <xref:total>) 使用签名函数 (当前、总计) 的进度回调，其中 current 是到目前为止传输的字节数，而 total 是文件的大小（如果已知）。 默认值: None
max_connections	int 如果设置为 2 或更大，则将为第一个自身执行初始获取。MAX_SINGLE_GET_SIZE个字节的文件。 如果这是整个文件，则方法此时返回 。 否则，它将使用等于 max_connections 的线程数并行下载剩余数据。 每个区块的大小为自身。MAX_CHUNK_GET_SIZE。 如果设置为 1，将完成单个大型获取请求。 通常不建议这样做，但如果应使用很少的线程、网络请求非常昂贵，或者不可查找的流阻止并行下载，则此选项可用。 如果同时修改文件以强制实施原子性，或者如果许多文件预期为空，如果max_connections大于 1，则需要对空文件执行额外的请求，则这也可能很有用。 默认值: 2
timeout	int 超时参数以秒表示。 此方法可能会对 Azure 服务进行多次调用，超时将分别应用于每个调用。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

返回

类型	说明
File	包含属性和元数据的文件。

get_file_to_stream

使用自动分块和进度通知将文件下载到流。 返回具有属性和元数据的 File 实例。

get_file_to_stream(share_name, directory_name, file_name, stream, start_range=None, end_range=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None, snapshot=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
stream 必需	IOBase 已打开要写入的文件/流。
start_range	int 要用于下载文件的某个部分的字节范围的起始。 如果未提供end_range，则将下载start_range后的所有字节。 start_range和end_range参数是包含的。 例如：start_range=0，end_range=511 将下载前 512 字节的文件。 默认值: None
end_range	int 用于下载文件的节的字节范围的结束。 如果提供了end_range，则必须提供start_range。 start_range和end_range参数是包含的。 例如：start_range=0，end_range=511 将下载前 512 字节的文件。 默认值: None
validate_content	bool 如果设置为 true，则验证文件的每个检索部分的 MD5 哈希。 如果使用 http 而不是 https 作为 https， (默认) 已验证，则这主要用于检测网络上的 bitflips。 请注意，该服务将仅返回 4MB 或更小区块的事务 MD5，因此第一个获取请求的大小为自身。MAX_CHUNK_GET_SIZE而不是自我。MAX_SINGLE_GET_SIZE。 如果为 self。MAX_CHUNK_GET_SIZE设置为大于 4MB，将引发错误。 由于计算 MD5 需要处理时间，并且由于区块大小减小，需要完成更多请求，延迟可能会有所增加。 默认值: False
progress_callback	<xref:func>(<xref:current>, <xref:total>) 使用签名函数 (当前、总计) 的进度回调，其中 current 是到目前为止传输的字节数，而 total 是文件的大小（如果已知）。 默认值: None
max_connections	int 如果设置为 2 或更大，则将为第一个自身执行初始获取。MAX_SINGLE_GET_SIZE个字节的文件。 如果这是整个文件，则方法此时返回 。 否则，它将使用等于 max_connections 的线程数并行下载剩余数据。 每个区块的大小为自身。MAX_CHUNK_GET_SIZE。 如果设置为 1，将完成单个大型获取请求。 通常不建议这样做，但如果应使用很少的线程、网络请求非常昂贵，或者不可查找的流阻止并行下载，则此选项可用。 如果同时修改文件以强制实施原子性，或者如果许多文件预期为空，如果max_connections大于 1，则需要对空文件执行额外的请求，则这也可能很有用。 默认值: 2
timeout	int 超时参数以秒表示。 此方法可能会对 Azure 服务进行多次调用，超时将分别应用于每个调用。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

返回

类型	说明
File	包含属性和元数据的文件。

get_file_to_text

以 unicode 文本的形式下载文件，并自动分块和进度通知。 返回具有属性、元数据和内容的 实例 File 。

get_file_to_text(share_name, directory_name, file_name, encoding='utf-8', start_range=None, end_range=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None, snapshot=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
encoding	str 解码文件数据时要使用的 Python 编码。 默认值: utf-8
start_range	int 要用于下载文件的某个部分的字节范围的起始。 如果未提供end_range，则将下载start_range后的所有字节。 start_range和end_range参数是包含的。 例如：start_range=0，end_range=511 将下载前 512 字节的文件。 默认值: None
end_range	int 用于下载文件的节的字节范围的结束。 如果提供了end_range，则必须提供start_range。 start_range和end_range参数是包含的。 例如：start_range=0，end_range=511 将下载前 512 字节的文件。 默认值: None
validate_content	bool 如果设置为 true，则验证文件的每个检索部分的 MD5 哈希。 如果使用 http 而不是 https 作为 https， (默认) 已验证，则这主要用于检测网络上的 bitflips。 请注意，该服务将仅返回 4MB 或更小区块的事务 MD5，因此第一个获取请求的大小为自身。MAX_CHUNK_GET_SIZE而不是自我。MAX_SINGLE_GET_SIZE。 如果为 self。MAX_CHUNK_GET_SIZE设置为大于 4MB，将引发错误。 由于计算 MD5 需要处理时间，并且由于区块大小减小，需要完成更多请求，延迟可能会有所增加。 默认值: False
progress_callback	<xref:func>(<xref:current>, <xref:total>) 使用签名函数 (当前、总计) 的进度回调，其中 current 是到目前为止传输的字节数，而 total 是文件的大小（如果已知）。 默认值: None
max_connections	int 如果设置为 2 或更大，则将为第一个自身执行初始获取。MAX_SINGLE_GET_SIZE个字节的文件。 如果这是整个文件，则方法此时返回 。 否则，它将使用等于 max_connections 的线程数并行下载剩余数据。 每个区块的大小为自身。MAX_CHUNK_GET_SIZE。 如果设置为 1，将完成单个大型获取请求。 通常不建议这样做，但如果应使用很少的线程、网络请求非常昂贵，或者不可查找的流阻止并行下载，则此选项可用。 如果同时修改文件以强制实施原子性，或者如果许多文件预期为空，如果max_connections大于 1，则需要对空文件执行额外的请求，则这也可能很有用。 默认值: 2
timeout	int 超时参数以秒表示。 此方法可能会对 Azure 服务进行多次调用，超时将分别应用于每个调用。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

返回

类型	说明
File	包含属性、内容和元数据的文件。

get_permission_for_share

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

：返回 (可移植 SDDL) 的文件权限：rtype str

get_permission_for_share(share_name, file_permission_key, timeout=None)

参数

名称	说明
share_name 必需	共享的名称。
file_permission_key 必需	要检索的文件权限的键
timeout	超时参数以秒表示。 默认值: None

get_share_acl

获取指定共享的权限。

get_share_acl(share_name, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
timeout	int 超时参数以秒表示。 默认值: None

返回

类型	说明
dict(str, AccessPolicy)	与共享关联的访问策略字典。

get_share_metadata

返回指定共享的所有用户定义的元数据。

get_share_metadata(share_name, timeout=None, snapshot=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
timeout	int 超时参数以秒表示。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

返回

类型	说明
dict(str, str)	表示共享元数据名称、值对的字典。

get_share_properties

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

get_share_properties(share_name, timeout=None, snapshot=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
timeout	int 超时参数以秒表示。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

返回

类型	说明
Share	公开属性和元数据的共享。

get_share_stats

获取存储在共享上的数据的近似大小，向上舍入为最接近的 GB。

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

get_share_stats(share_name, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
timeout	int 超时参数以秒表示。 默认值: None

返回

类型	说明
int	共享上存储的数据的近似大小。

get_share_stats_in_bytes

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

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

get_share_stats_in_bytes(share_name, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
timeout	int 超时参数以秒表示。 默认值: None

返回

类型	说明
int	共享上存储的数据的近似大小。

list_directories_and_files

返回一个生成器，用于列出指定共享下的目录和文件。 生成器将延迟跟踪服务返回的继续标记，并在返回所有目录和文件或到达num_results时停止。

如果指定了num_results，并且共享的文件和目录数超过该数目，则生成器在完成时将具有填充next_marker字段。 如果需要更多结果，可以使用此标记创建新的生成器。

list_directories_and_files(share_name, directory_name=None, num_results=None, marker=None, timeout=None, prefix=None, snapshot=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name	str 目录的路径。 默认值: None
num_results	int 指定要返回的最大文件数，包括所有目录元素。 如果请求未指定num_results或指定的值大于 5,000，则服务器将返回最多 5,000 个项目。 将num_results设置为小于或等于零的值会导致错误响应代码 400 (错误的请求) 。 默认值: None
marker	str 不透明的延续标记。 如果指定了num_results并且该生成器已完成枚举结果，则可以从上一个生成器对象的 next_marker 字段中检索此值。 如果指定，此生成器将从上一个生成器停止的点开始返回结果。 默认值: None
timeout	int 超时参数以秒表示。 默认值: None
prefix	str 仅列出具有给定前缀的文件和/或目录。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

list_handles

返回一个生成器，用于列出目录或指定共享下的文件上打开的句柄。 生成器将延迟跟踪服务返回的继续标记，并在返回所有句柄或到达num_results时停止。

如果指定了num_results，并且共享的文件和目录数超过该数目，则生成器在完成时将具有填充next_marker字段。 如果需要更多结果，可以使用此标记创建新的生成器。

list_handles(share_name, directory_name=None, file_name=None, recursive=None, max_results=None, marker=None, snapshot=None, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name	str 目录的路径。 默认值: None
file_name	str 现有文件的名称。 默认值: None
recursive	bool 布尔值，指定操作是否应应用于 URI 中指定的目录、其文件、子目录及其文件。 默认值: None
max_results	int 指定要返回的文件和/或目录的最大句柄数。 如果请求未指定max_results或指定大于 5,000 的值，则服务器将返回最多 5,000 项。 将max_results设置为小于或等于零的值会导致错误响应代码 400 (错误的请求) 。 默认值: None
marker	str 不透明的延续标记。 如果指定了max_results并且该生成器已完成枚举结果，则可以从上一个生成器对象的next_marker字段中检索此值。 如果指定，此生成器将从上一个生成器停止的点开始返回结果。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None
timeout	int 超时参数以秒表示。 默认值: None

list_ranges

检索文件的有效范围。

list_ranges(share_name, directory_name, file_name, start_range=None, end_range=None, timeout=None, snapshot=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
start_range	int 指定要列出范围的字节的起始偏移量。 start_range和end_range参数是包容性的。 例如：start_range=0，end_range=511 将下载前 512 个字节的文件。 默认值: None
end_range	int 指定要列出范围的字节的结束偏移量。 start_range和end_range参数是包容性的。 例如：start_range=0，end_range=511 将下载前 512 个字节的文件。 默认值: None
timeout	int 超时参数以秒表示。 默认值: None
snapshot	str 表示快照版本的字符串（如果适用）。 默认值: None

返回

类型	说明
<xref:a> list <xref:of> FileRange	有效范围列表

list_shares

返回一个生成器，用于列出指定帐户下的共享。 生成器将延迟跟踪服务返回的延续令牌，并在返回所有共享或达到num_results时停止。

如果指定了num_results，并且帐户的共享数超过该数目，则生成器在完成时将具有填充next_marker字段。 如果需要更多结果，可以使用此标记创建新的生成器。

list_shares(prefix=None, marker=None, num_results=None, include_metadata=False, timeout=None, include_snapshots=False)

参数

名称	说明
prefix	str 筛选结果以仅返回名称以指定前缀开头的共享。 默认值: None
num_results	int 指定要返回的最大共享数。 默认值: None
include_metadata	bool 指定在响应中返回共享元数据。 默认值: False
marker	str 不透明的延续标记。 如果指定了num_results并且该生成器已完成枚举结果，则可以从上一个生成器对象的 next_marker 字段中检索此值。 如果指定，此生成器将从上一个生成器停止的点开始返回结果。 默认值: None
timeout	int 超时参数以秒表示。 默认值: None
include_snapshots	bool 指定在响应中返回共享快照。 默认值: False

make_file_url

创建用于访问文件的 URL。

make_file_url(share_name, directory_name, file_name, protocol=None, sas_token=None)

参数

名称	说明
share_name 必需	str 共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 文件的名称。
protocol	str 要使用的协议：“http”或“https”。 如果未指定，请使用初始化 FileService 时指定的协议。 默认值: None
sas_token	str 使用 generate_shared_access_signature 创建的共享访问签名令牌。 默认值: None

返回

类型	说明
str	文件访问 URL。

resize_file

将文件调整为指定大小。 如果指定的字节值小于当前的文件大小，则会清除超过指定字节值的所有范围。

resize_file(share_name, directory_name, file_name, content_length, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
content_length 必需	int 要调整文件大小到的长度。
timeout	int 超时参数以秒表示。 默认值: None

set_directory_metadata

为指定目录设置一个或多个用户定义的名称/值对。 每次调用此操作都会替换附加到该目录的所有现有元数据。 若要从目录中删除所有元数据，请调用此操作，不带元数据听写。

set_directory_metadata(share_name, directory_name, metadata=None, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
metadata	dict(str, str)<xref:./> 包含要作为元数据与目录关联的名称/值对的 dict。 示例：{'category'：'test'} 默认值: None
timeout	int 超时参数以秒表示。 默认值: None

set_directory_properties

set_directory_properties(share_name, directory_name, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>, timeout=None)

参数

名称	说明
share_name 必需	共享的名称
directory_name 必需	目录的名称
file_permission	str 文件权限，可移植 SDDL 默认值: None
smb_properties	SMBProperties 设置与 SMB 相关的文件属性
timeout	int 超时参数以秒表示。 默认值: None

set_file_metadata

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

set_file_metadata(share_name, directory_name, file_name, metadata=None, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
metadata	dict(str, str) 包含名称和值对的 Dict。 每次调用此操作都会替换附加到该文件的所有现有元数据。 要从该文件中删除所有元数据，请不带任何元数据头调用此操作。 默认值: None
timeout	int 超时参数以秒表示。 默认值: None

set_file_properties

设置文件上的系统属性。 如果为content_settings设置了一个属性，则将重写所有属性。

set_file_properties(share_name, directory_name, file_name, content_settings, timeout=None, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
content_settings 必需	ContentSettings 用于设置文件属性的 ContentSettings 对象。
file_permission	str 文件权限，可移植 SDDL 默认值: None
smb_properties	SMBProperties 设置与 SMB 相关的文件属性
timeout	int 超时参数以秒表示。 默认值: None

set_file_service_properties

设置存储帐户的文件服务的属性，包括 Azure 存储分析。 如果某个元素 (ex HourMetrics) 保留为 None，则保留该服务上针对该功能的现有设置。

set_file_service_properties(hour_metrics=None, minute_metrics=None, cors=None, timeout=None)

参数

名称	说明
hour_metrics	<xref:Metrics> 小时指标设置提供按 API 分组的请求统计信息的摘要，按文件的每小时聚合。 默认值: None
minute_metrics	<xref:Metrics> 分钟指标设置提供文件每分钟的请求统计信息。 默认值: None
cors	list(CorsRule) 列表中最多可以包含五个 CorsRule 元素。 如果指定了空列表，则将删除所有 CORS 规则，并且将为服务禁用 CORS。 默认值: None
timeout	int 超时参数以秒表示。 默认值: None

set_proxy

设置 HTTP CONNECT 隧道的代理服务器主机和端口。

set_proxy(host, port, user=None, password=None)

参数

名称	说明
host 必需	str 代理的地址。 例如：'192.168.0.100'
port 必需	int 代理的端口。 例如：6000
user	str 用于代理授权的用户。 默认值: None
password	str 代理授权的密码。 默认值: None

set_share_acl

设置可与共享访问签名一起使用的指定共享或存储访问策略的权限。

set_share_acl(share_name, signed_identifiers=None, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
signed_identifiers	dict(str, AccessPolicy) 要与共享关联的访问策略字典。 字典最多可以包含 5 个元素。 空字典将清除在服务上设置的访问策略。 默认值: None
timeout	int 超时参数以秒表示。 默认值: None

set_share_metadata

为指定的共享设置一个或多个用户定义的名称/值对。 每次调用此操作都会替换附加到该共享的所有现有元数据。 若要从共享中删除所有元数据，请在不带元数据 dict 的情况下调用此操作。

set_share_metadata(share_name, metadata=None, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
metadata	dict(str, str) 包含要作为元数据与共享关联的名称/值对的 dict。 示例：{'category'：'test'} 默认值: None
timeout	int 超时参数以秒表示。 默认值: None

set_share_properties

设置指定共享的服务定义属性。

set_share_properties(share_name, quota, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
quota 必需	int 指定共享的最大大小 (GB)。 必须大于 0 且小于或等于 5 TB (5120 GB) 。
timeout	int 超时参数以秒表示。 默认值: None

snapshot_share

在指定帐户下创建现有共享的快照。

snapshot_share(share_name, metadata=None, quota=None, timeout=None)

参数

名称	说明
share_name 必需	str 要创建快照的共享的名称。
metadata	<xref:<xref:a dict> of <xref:str to str:>> 包含name_value对的 dict，这些对作为元数据与共享相关联。 示例：{'Category'：'test'} 默认值: None
quota	int 指定共享的最大大小 (GB)。 必须大于 0 且小于或等于 5 TB (5120)。 默认值: None
timeout	int 超时参数以秒表示。 默认值: None

返回

类型	说明
Share	快照属性

update_range

将请求正文指定的字节写入指定范围。

update_range(share_name, directory_name, file_name, data, start_range, end_range, validate_content=False, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
data 必需	bytes 范围的内容。
start_range 必需	int 用于更新文件的节的字节范围的开头。 该范围的大小最大为 4 MB。 start_range和end_range参数是包含的。 例如：start_range=0，end_range=511 将下载前 512 字节的文件。
end_range 必需	int 用于更新文件的节的字节范围结束。 该范围的大小最大为 4 MB。 start_range和end_range参数是包含的。 例如：start_range=0，end_range=511 将下载前 512 字节的文件。
validate_content	bool 如果为 true，则计算页面内容的 MD5 哈希。 存储服务会检查随发送的哈希一起到达的内容的哈希。 如果使用 http 而不是 https 作为 https， (默认) 已验证，则这主要用于检测网络上的 bitflips。 请注意，此 MD5 哈希不随 文件一起存储。 默认值: False
timeout	int 超时参数以秒表示。 默认值: None

update_range_from_file_url

将一个 Azure 文件终结点中的字节写入另一个 Azure 文件终结点的指定范围。

update_range_from_file_url(share_name, directory_name, file_name, start_range, end_range, source, source_start_range, timeout=None)

参数

名称	说明
share_name 必需	str 现有共享的名称。
directory_name 必需	str 目录的路径。
file_name 必需	str 现有文件的名称。
start_range 必需	int 用于更新文件的节的字节范围的开头。 该范围的大小最大为 4 MB。 start_range和end_range参数是包含的。 例如：start_range=0，end_range=511 将下载前 512 字节的文件。
end_range 必需	int 用于更新文件的节的字节范围结束。 该范围的大小最大为 4 MB。 start_range和end_range参数是包含的。 例如：start_range=0，end_range=511 将下载前 512 字节的文件。
source 必需	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_start_range 必需	int 用于更新文件的节的字节范围的开头。 该范围的大小最大为 4 MB。 start_range和end_range参数是包含的。 例如：start_range=0，end_range=511 将下载前 512 字节的文件。
timeout	int 超时参数以秒表示。 默认值: None

属性

protocol

request_session

socket_timeout

MAX_CHUNK_GET_SIZE

MAX_CHUNK_GET_SIZE = 8388608

MAX_RANGE_SIZE

MAX_RANGE_SIZE = 4194304

MAX_SINGLE_GET_SIZE

MAX_SINGLE_GET_SIZE = 33554432