Microsoft Azure Azure File Share Storage Client Library for Python

这些详情尚未由PyPI 验证

项目链接

主页

项目描述

Azure Storage File Share客户端库

Azure File Share存储提供云中的完全托管文件共享，可通过行业标准服务器消息块（SMB）协议访问。Azure文件共享可以由Windows、Linux和macOS的云或本地部署同时挂载。此外，Azure文件共享可以通过Azure File Sync在Windows服务器上缓存，以便快速访问数据使用的位置。

Azure文件共享可用于

替换或补充本地文件服务器
“提升和迁移”应用程序
通过共享应用程序设置、诊断共享和Dev/Test/Debug工具简化云开发

入门

先决条件

使用此包需要Python 3.8或更高版本。有关更多详细信息，请阅读我们关于Azure SDK for Python版本支持策略的页面。
您必须有一个Azure订阅和一个Azure存储帐户才能使用此包。

安装包

使用pip安装Azure Storage File Share客户端库

pip install azure-storage-file-share

创建存储帐户

如果您想创建一个新的存储帐户，可以使用Azure Portal、Azure PowerShell或Azure CLI

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

创建客户端

Azure Storage File Share客户端库允许您与四种类型的资源进行交互：存储帐户本身、文件共享、目录和文件。与这些资源的交互从一个客户端实例开始。要创建客户端对象，您需要存储帐户的文件服务URL和允许您访问存储帐户的凭据。

from azure.storage.fileshare import ShareServiceClient

service = ShareServiceClient(account_url="https://<my-storage-account-name>.file.core.windows.net/", credential=credential)

查找帐户URL

您可以使用Azure Portal、Azure PowerShell或Azure CLI查找存储帐户的文件服务URL。

# Get the file service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.file"

凭据类型

根据您希望使用的授权类型，credential参数可以以多种形式提供。

要使用共享访问签名（SAS）令牌，请将令牌作为字符串提供。如果您的帐户URL包含SAS令牌，则无需提供凭据参数。您可以从Azure Portal的“共享访问签名”部分生成SAS令牌，或使用generate_sas()函数之一为存储帐户、共享或文件创建SAS令牌。

from datetime import datetime, timedelta
from azure.storage.fileshare import ShareServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

share_service_client = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential=sas_token)

要使用存储帐户的共享密钥（也称为帐户密钥或访问密钥），请将密钥作为字符串提供。您可以在Azure Portal的“访问密钥”部分找到它，或者通过运行以下Azure CLI命令：

az storage account keys list -g MyResourceGroup -n MyStorageAccount

使用密钥作为凭据参数来验证客户端
```
from azure.storage.fileshare import ShareServiceClient
service = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential="<account_access_key>")
```

从连接字符串创建客户端

根据您的用例和授权方法，您可能更喜欢使用存储连接字符串初始化客户端实例，而不是分别提供帐户URL和凭据。为此，请将存储连接字符串传递给客户端的from_connection_string类方法。

from azure.storage.fileshare import ShareServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = ShareServiceClient.from_connection_string(conn_str=connection_string)

您的存储帐户的连接字符串可以在Azure Portal的“访问密钥”部分找到，或者通过运行以下CLI命令：

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Key concepts

以下组件构成了Azure文件共享服务

存储帐户本身
存储帐户内的文件共享
文件共享内的可选目录层次结构
文件共享中的一个文件，大小可能高达1 TiB

Azure 存储文件共享 Python 客户端库允许您通过使用专门的客户端对象与每个组件进行交互。

异步客户端

此库包括一个完整的异步 API，支持 Python 3.5+。要使用它，您必须首先安装异步传输，例如 aiohttp。有关更多信息，请参阅 azure-core 文档。

当不再需要时，应关闭异步客户端和凭证。这些对象是异步上下文管理器，并定义异步 close 方法。

客户端

提供了四个不同的客户端，用于与文件共享服务的各个组件进行交互

ShareServiceClient - 此客户端代表与 Azure 存储帐户本身的交互，并允许您获取预配置的客户端实例以访问其中的文件共享。它提供检索和配置服务属性的操作，以及列出、创建和删除帐户中的共享的操作。要执行特定共享的操作，请使用 get_share_client 方法检索客户端。
ShareClient - 此客户端代表与特定文件共享（可能尚不存在）的交互，并允许您获取预配置的客户端实例以访问其中的目录和文件。它提供创建、删除、配置共享以及创建共享快照的操作，包括创建和枚举其中目录内容的操作。要执行特定目录或文件的操作，请使用 get_directory_client 或 get_file_client 方法检索客户端。
ShareDirectoryClient - 此客户端代表与特定目录（可能尚不存在）的交互。它提供创建、删除或枚举立即或嵌套子目录内容的操作，并包括创建和删除其中文件的操作。对于与特定子目录或文件相关的操作，也可以使用 get_subdirectory_client 和 get_file_client 函数检索该实体的客户端。
ShareFileClient - 此客户端代表与特定文件（可能尚不存在）的交互。它提供上传、下载、创建、删除和复制文件的操作。

有关路径命名限制的详细信息，请参阅命名和引用共享、目录、文件和元数据。

示例

以下部分提供了几个代码片段，涵盖了 Storage File Share 的一些最常见任务，包括

创建文件共享
上传文件
下载文件
列出目录内容

创建文件共享

创建文件共享以存储您的文件

from azure.storage.fileshare import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
share.create_share()

使用异步客户端创建文件共享

from azure.storage.fileshare.aio import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
await share.create_share()

上传文件

将文件上传到共享

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    file_client.upload_file(source_file)

异步上传文件

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    await file_client.upload_file(source_file)

下载文件

从共享中下载文件

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = file_client.download_file()
    data.readinto(file_handle)

异步下载文件

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = await file_client.download_file()
    await data.readinto(file_handle)

列出目录内容

from azure.storage.fileshare import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_list = list(parent_dir.list_directories_and_files())
print(my_list)

异步列出目录内容

from azure.storage.fileshare.aio import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_files = []
async for item in parent_dir.list_directories_and_files():
    my_files.append(item)
print(my_files)

可选配置

可以在客户端和操作级别传递的可选关键字参数。

重试策略配置

在实例化客户端时使用以下关键字参数来配置重试策略

retry_total (int): 允许的总重试次数。优先于其他计数。如果要请求不重试，请传递 retry_total=0。默认为 10。
retry_connect (int): 在多少个连接相关错误上进行重试。默认为 3。
retry_read (int): 在读取错误时重试的次数。默认为3。
retry_status (int): 在遇到错误状态码时重试的次数。默认为3。
retry_to_secondary (bool): 是否在可能的情况下将请求重试到辅助服务器。这仅在RA-GRS账户使用且可以处理可能过期的数据时启用。默认为False。

其他客户端/操作配置

可以在客户端或每个操作中指定的其他可选配置关键字参数。

客户端关键字参数

connection_timeout (int): 客户端建立与服务器连接将等待的秒数。默认为20秒。
read_timeout (int): 客户端将在连续读取操作之间等待响应的秒数。这是一个套接字级别的超时，不受整体数据大小的影响。客户端端读取超时将被自动重试。默认为60秒。
transport (Any): 用户提供的用于发送HTTP请求的传输。

每个操作关键字参数

raw_response_hook (callable): 给定的回调使用从服务返回的响应。
raw_request_hook (callable): 给定的回调使用在发送到服务之前的需求。
client_request_id (str): 可选的用户指定请求标识。
user_agent (str): 将自定义值追加到随请求发送的用户代理头中。
logging_enable (bool): 启用DEBUG级别的日志记录。默认为False。也可以在客户端级别传入以启用所有请求的日志记录。
logging_body (bool): 启用记录请求和响应体。默认为False。也可以在客户端级别传入以启用所有请求的日志记录。
headers (dict): 以键值对的形式传递自定义头部。例如：headers={'CustomValue': value}

故障排除

通用

存储文件客户端抛出在Azure Core中定义的异常。

此列表可用于参考以捕获抛出的异常。要获取异常的特定错误代码，请使用error_code属性，即exception.error_code。

日志记录

此库使用标准的logging库进行日志记录。HTTP会话的基本信息（URL、头部等）以INFO级别进行记录。

可以通过在客户端中使用logging_enable参数启用详细的DEBUG级别日志记录，包括请求/响应体和未脱敏的头部。

import sys
import logging
from azure.storage.fileshare import ShareServiceClient

# Create a logger for the 'azure.storage.fileshare' SDK
logger = logging.getLogger('azure.storage.fileshare')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = ShareServiceClient.from_connection_string("your_connection_string", logging_enable=True)

类似地，logging_enable可以启用单个操作的详细日志记录，即使它没有为客户端启用。

service_client.get_service_properties(logging_enable=True)

下一步

其他文档

有关Azure文件共享存储的更详细文档，请参阅docs.microsoft.com上的Azure文件共享存储文档。

贡献

此项目欢迎贡献和建议。大多数贡献都需要您同意一份贡献者许可协议（CLA），声明您有权，并且实际上确实授予我们使用您贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并相应地装饰PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您只需要在整个使用我们的CLA的repo中进行一次。

本项目已采用Microsoft开源行为准则。有关更多信息，请参阅行为准则常见问题解答或联系opencode@microsoft.com获取任何额外的问题或评论。

发布历史

12.18.0 (2024-09-17)

新增功能

12.18.0b1的稳定版本功能

12.18.0b1（2024-08-07）

新增功能

增加了对2024-11-04服务版本的支持。
增加了对所有之前未启用的数据平面文件操作启用Entra ID身份验证的支持。
为Share的create_share和set_share_properties API以及get_share_properties API增加了设置paid_bursting_enabled、paid_bursting_bandwidth_mibps和paid_bursting_iops的支持，并且可以在get_share_properties API中检索它们。
为Share的create_permission_for_share和get_permission_for_share API、文件的create_file、rename_file和set_http_headers API以及目录的rename_directory和set_http_headers API增加了file_permission_format以指定权限格式。

其他更改

将最低azure-core依赖项提升到1.30.0。

12.17.0 (2024-07-18)

新增功能

12.17.0b1的稳定版本功能

12.17.0b1（2024-06-11）

新增功能

在遇到授权错误时增加了更详细的授权错误消息。

12.16.0 (2024-05-07)

新增功能

12.16.0b1的稳定版本功能

12.16.0b1（2024-04-16）

此版本以及所有未来版本将需要Python 3.8+。Python 3.7不再受支持。

新增功能

为ShareFileClient增加了exists方法以检查文件是否存在。
增加了对2024-05-04服务版本的支持。
已向 generate_account_sas API 添加了 services 参数，该参数允许生成可用于多个服务的 SAS 令牌。默认情况下，SAS 令牌的服务范围将默认为当前服务。
向 Handle 添加了 client_name 属性。
向 get_ranges_diff() 添加了对 support_rename 的支持。

修复了错误

修复了由 get_subdirectory_client 返回的 ShareDirectoryClient（指向文件共享的根目录）引发 InvalidResourceName 的问题。
将 typing-extensions 依赖项升级到 >=4.6.0 以避免在 Python 3.12 上使用 typing.TypeVar 时出现潜在的 TypeError。
修复了使用异步 OAuth 凭证时，认证错误可能会引发 AttributeError 而不是 ClientAuthenticationError 的问题。
修复了 delete_share API 中的参数 delete_snapshots 不支持所有可能的枚举值的问题。此更改使 delete_snapshots 现在可以接受字符串字面量 'include' 和 'include-leased'。
修复了将精度小于 7 位的日期时间对象指定为输入时可能由于精度解析不当而引发 InvalidHeaderValue 的问题。

12.15.0 (2023-11-07)

新增功能

12.15.0b1 的功能稳定版

12.15.0b1（2023-10-17）

新增功能

添加了对服务版本 2023-11-03 的支持。
在具有 credential 参数的 API 中添加了作为可选关键字指定的 audience。此关键字仅在提供的凭证类型为 TokenCredential 时才有效。

12.14.2 (2023-10-10)

修复了错误

修复了在客户端构建过程中为 credential 提供无效类型时，对象 __str__ 会出现在异常消息中并因此可能被记录的问题。

12.14.1 (2023-09-13)

修复了错误

修复了 create_configuration 中的破坏性错误 KeyError: 'sdk_moniker'。注意：这不是一个导出方法，因此不应直接导入/调用。

12.14.0 (2023-09-12)

新增功能

12.14.0b1 的功能稳定版

12.14.0b1（2023-08-08）

新增功能

添加了对服务版本 2023-05-03 和 2023-08-03 的支持。

12.13.0 (2023-07-11)

新增功能

12.13.0b1 的功能稳定版

12.13.0b1（2023-05-30）

新增功能

添加了对服务版本 2023-01-03 的支持。
向 Handle 添加了 access_rights 属性。

12.12.0 (2023-04-12)

新增功能

12.12.0b1 的功能稳定版

12.12.0b1（2023-03-28）

新增功能

添加了对服务版本 2022-11-02 的支持。
添加了对 TokenCredential 用于认证的支持。可以为任何客户端构造函数的 credential 参数提供 TokenCredential。注意：当使用 TokenCredential 时，必须提供新的关键字参数 token_intent。此外，此形式的认证仅支持数据平面 SDK 中的某些操作。
在客户端构建时添加了对 allow_trailing_dot 和 allow_source_trailing_dot 的支持。当提供 allow_trailing_dot 时，服务将不会从该客户端进行的所有操作中静默地删除目录/文件名中的任何尾随 . 字符。allow_source_trailing_dot 将在执行重命名或复制操作时将此规则应用于源文件。

12.11.1 (2023-03-08)

修复了错误

修复了 "duplicate type signatures" MyPy 错误。

12.11.0 (2023-02-22)

新增功能

12.11.0b1 的功能稳定版

12.11.0b1（2023-02-02）

新增功能

添加了对服务版本 2021-12-02 的支持。
添加了对包含无效 XML 字符的文件和目录路径的支持。当列出或检索属性时，服务将编码非法字符，而 SDK 现在将自动解码它们。
将 AsyncIterable 添加为异步文件上传的数据类型。

修复了错误

修复了 list_shares 异步 API 中未正确传递关键字 name_starts_with 的问题。

其他更改

移除了 msrest 依赖项。
添加了依赖项 typing-extensions>=4.0.1。
添加了依赖项 isodate>=0.6.1。
为安装可选的异步依赖项添加了额外依赖项 aio。使用 pip install azure-storage-file-share[aio] 进行安装。

12.10.1 (2022-10-18)

修复了错误

修复了当通过 Azurite 下载空文件时可能引发的非法内容范围导致的 ValueError。

12.10.0 (2022-10-11)

新增功能

12.10.0b1 版本的功能的稳定发布。

修复了错误

修复了一个问题，当使用无效的 base64 编码的帐户密钥调用 download_file 时，会引发 AttributeError 而不是正确的 AzureSigningError。

其他更改

将所有客户端的 read_timeout 的默认值更改为 60 秒。

12.10.0b1 (2022-08-23)

此版本和所有未来版本将需要 Python 3.7+。Python 3.6 不再受支持。

新增功能

添加了对 AzureNamedKeyCredential 作为有效 credential 类型的支持。

12.9.0 (2022-07-07)

新增功能

12.9.0b1 版本的功能的稳定发布。
通过新的可选回调 progress_hook，添加了对 upload_file() 和 download_file() 进度跟踪的支持。

12.9.0b1 (2022-06-15)

新增功能

为 start_copy_from_url API 添加了对 file_change_time 的支持。

12.8.0 (2022-05-09)

新增功能

12.8.0b1 版本的功能的稳定发布。

修复了错误

修复了上一个测试版中引入的 bug，该 bug 导致在尝试使用某些服务级别操作使用 Account SAS 时出现身份验证错误。

12.8.0b1 (2022-04-14)

新增功能

添加了对服务版本 2021-06-08 的支持。
为 create_directory() 添加了对缺失参数的支持，包括 file_attributes、file_creation_time、file_last_write_time、file_permission 和 file_permission_key。
为 rename_file() 添加了对设置 content_type 的支持。
为 create_directory()、set_http_headers()（目录）rename_directory()、create_file()、set_http_headers()（文件）和 rename_file() 添加了对设置 file_change_time 的支持。
为 upload_range() 和 upload_range_from_url() 添加了对设置 file_last_write_mode 的支持，可能的值为 Now 或 Preserve。

修复了错误

更新了 create_share() 的文档字符串，以具有正确的返回类型 None。

12.7.0 (2022-03-08)

此版本和所有未来版本将需要 Python 3.6+。Python 2.7 不再受支持。

预览功能的稳定发布。

添加了对服务版本 2021-02-12、2021-04-10 的支持。
添加了对高级文件共享预配带宽属性的支持。
添加了对使用 exists() 检查目录是否存在的支持。
添加了对 rename_directory() 和 rename_file() 的支持。
添加了对 Share SAS 的 Create (c) SAS 权限的支持。

修复了错误

修复了一个 bug，其中 start_copy_from_url() 没有正确发送 ignore_read_only 参数。

12.7.0b2 (2022-02-08)

此版本和所有未来版本将需要 Python 3.6+。Python 2.7 不再受支持。

新增功能

添加了对服务版本 2021-04-10 的支持。
添加了对 rename_directory() 和 rename_file() 的支持。
添加了对 Share SAS 的 Create (c) SAS 权限的支持。

修复了错误

更新 azure-core 依赖项，以避免安装不一致的依赖项。
修复了上一个测试版中引入的 bug，其中 generate_account_sas() 没有生成正确的 SAS 签名。

12.7.0b1 (2021-12-13)

新增功能

添加了对服务版本 2021-02-12 的支持。
添加了对高级文件共享预配带宽属性的支持。
添加了对使用 exists() 检查目录是否存在的支持。

12.6.0 (2021-09-15)

预览功能的稳定发布。

添加了对服务版本 2020-10-02 (STG78) 的支持。
为文件复制源添加了对 OAuth 的支持。

12.6.0b1 (2021-07-27)

新功能

为文件复制源添加了对 OAuth 的支持。

修复

确保如果文件在下载过程中被修改，则下载失败

12.5.0 (2021-06-09)

新功能

为共享添加了对租赁操作的支持，例如 acquire_lease

12.5.0b1 (2021-05-12)

新功能

为共享添加了对租赁操作的支持，例如 acquire_lease

12.4.2 (2021-04-20)

修复

使 conn_str 中的 AccountName、AccountKey 等等变为不区分大小写
修复了 downloader.chunks() 返回不同大小的块的问题 (#9419, #15648)
修复了未关闭的 ThreadPoolExecutor (#8955)

12.4.1 (2021-01-20)

修复

修复了 msrest 依赖项问题 (#16250)

12.4.0 (2021-01-13)

预览功能的稳定发布。

添加了对启用文件共享的根 squash 和共享协议的支持。
添加了对 AzureSasCredential 的支持，以允许在长生命周期的客户端中进行 SAS 轮换。

12.4.0b1 (2020-12-07)

新功能

添加了对启用文件共享的根 squash 和共享协议的支持。

12.3.0 (2020-11-10)

预览功能的稳定发布。

预览功能：启用共享服务的SMB多通道。
在ShareFileClient上预览功能 get_ranges。

新功能

添加了set_share_properties，允许设置共享层。

注意

已更新依赖项azure-core，从azure-core<2.0.0,> =1.2.2 更新到azure-core<2.0.0,> =1.9.0，以获取AzureError上的continuation_token属性。

12.3.0b1 (2020-10-02)

新功能

添加了对启用共享服务SMB多通道的支持。
添加了对租赁共享的支持。
添加了对获取当前文件和快照之间的范围差异以及获取两个文件快照之间的差异的支持。

12.2.0 (2020-08-13)

预览功能的稳定发布。

在FileShareServiceClient上预览功能 undelete_share。

12.2.0b1 (2020-07-07)

新功能

在FileShareServiceClient上添加了undelete_share，以便用户可以在启用了共享软删除的账户上恢复已删除的共享。用户还可以在指定include_deleted=True时通过list_shares列出已删除的共享。

12.1.2

修复

改进了使用max_concurrency时的上传性能。

12.1.1 (2020-03-10)

注意

StorageUserAgentPolicy现在已替换为来自azure-core的UserAgentPolicy。因此，自定义用户代理现在作为前缀而不是追加。

12.1.0

新功能

添加了对2019-07-07服务版本的支持，并为客户端添加了api_version参数。
在SDK的同步和异步版本中引入了ShareLeaseClient，允许用户对文件租赁执行操作。
在close_handle和close_all_handles结果中包含了failed_handles_count信息。
在list_shares和get_share_properties中添加了对获取高级文件属性的支持。
添加了对额外的start_copy_from_url参数的支持 - file_permission、permission_key、file_attributes、file_creation_time、file_last_write_time、ignore_read_only和set_archive_attribute。

修复和改进

修复了一个错误：clear_range API不起作用。

修复

响应始终以UTF8解码。

12.0.0

新功能

向share_client添加了delete_directory方法。
所有客户端现在都有一个close()方法，用于在未使用上下文管理器时关闭客户端打开的套接字。

修复和改进

修复了一个错误，即在提供无效fileno时，确定长度的过程在上传文件时中断。

破坏性更改

close_handle(handle)和close_all_handles()不再返回int。这些函数返回一个字典，包含已关闭的句柄数和无法关闭的句柄数。

12.0.0b5

重要：此包之前名为azure-storage-file

从现在开始，要使用此SDK，请安装azure-storage-file-share。此外

包内的命名空间也已重命名为azure.storage.fileshare。
FileServiceClient已重命名为ShareServiceClient。
DirectoryClient已重命名为ShareDirectoryClient。
FileClient已重命名为ShareFileClient。

其他破坏性更改

ShareClient现在仅接受带有强制字符串参数share_name的account_url。要使用share_url，必须使用方法from_share_url。
ShareDirectoryClient现在仅接受带有强制字符串参数share_name和directory_path的account_url。要使用directory_url，必须使用方法from_directory_url。
ShareFileClient现在仅接受带有强制字符串参数share_name和file_path的account_url。要使用file_url，必须使用方法from_file_url。
file_permission_key参数已重命名为permission_key。
set_share_access_policy需要参数signed_identifiers。
已删除NoRetry策略。使用关键字参数retry_total=0进行无重试。
删除了从两个模块中意外暴露的类型。现在只需从 azure.storage.fileshare.aio 导入 ShareServiceClient、ShareClient、ShareDirectoryClient 和 ShareFileClient。
一些参数已变为关键字参数，而不是位置参数。一些例子包括
- loop
- max_concurrency
- validate_content
- timeout 等。
客户端和模型文件已被设置为内部使用。用户应仅从顶级模块 azure.storage.fileshare 和 azure.storage.fileshare.aio 导入。
每个 ShareServiceClient、ShareClient 和 ShareFileClient 上的 generate_shared_access_signature 方法已被模块级别的函数 generate_account_sas、generate_share_sas 和 generate_file_sas 替换。
start_range 和 end_range 参数现在已被重命名为 offset 和 length，并在以下 API 中具有相应的行为
- download_file
- upload_range
- upload_range_from_url
- clear_range
- get_ranges
StorageStreamDownloader 现在不再可迭代。要遍历文件数据流，请使用 StorageStreamDownloader.chunks。
StorageStreamDownloader 的公共属性已限制为
- name (str)：文件的名称。
- path (str)：文件的完整路径。
- share (str)：文件将从该共享中下载。
- properties (FileProperties)：文件的属性。
- size (int)：下载的大小。可以是总文件大小，也可以是指定子部分的大小。以前称为 download_size。
StorageStreamDownloader 现在有新功能
- readall()：读取完整的下载流，返回字节。这取代了已弃用的函数 content_as_bytes 和 content_as_text。
- readinto(stream)：将完整的流下载到提供的可写流中，返回写入的字节数。这取代了已弃用的函数 download_to_stream。
ShareFileClient.close_handles 和 ShareDirectoryClient.close_handles 都已被两个函数各自替换；close_handle(handle) 和 close_all_handles()。这些函数是阻塞的，并返回整数（关闭的句柄数）而不是轮询对象。
get_service_properties 现在返回一个具有与 set_service_properties 关键字一致的键的字典。

新功能

ResourceTypes、NTFSAttributes 和 Services 现在有 from_string 方法，该方法接受字符串作为参数。

12.0.0b4

破坏性更改

权限模型。
- AccountPermissions、SharePermissions 和 FilePermissions 分别重命名为 AccountSasPermissions、ShareSasPermissions 和 FileSasPermissions。
- 从这三个中删除了类似枚举的列表参数。
- 移除了 __add__ 和 __or__ 方法。
max_connections 现在已重命名为 max_concurrency。

新功能

AccountSasPermissions、FileSasPermissions、ShareSasPermissions 现在有 from_string 方法，该方法接受字符串作为参数。

12.0.0b3

新功能

添加了 upload_range_from_url API，用于将一个 Azure 文件端点的字节数写入另一个 Azure 文件端点的指定范围。
添加了为 directory_client、create_permission_for_share 和 get_permission_for_share API 设置 HTTP 头的函数。
为与 create_file*、create_directory* 相关的 API 和 set_http_headers API 相关的 smb 属性相关参数添加了可选参数。
更新了目录和文件的 get_properties，以便响应具有 SMB 属性。

依赖项更新

采用 azure-core 1.0.0b3
- 如果您稍后想恢复到 azure-storage-file 的先前版本或其他需要 azure-core 1.0.0b1 或 azure-core 1.0.0b2 的 Azure SDK 库，您必须显式安装 azure-core 的特定版本。例如
pip install azure-core==1.0.0b2 azure-storage-file==12.0.0b2

修复和改进

修复了在请求中未明确提及时添加 content-type 的问题。

12.0.0b2

破坏性更改

将 copy_file_from_url 重命名为 start_copy_from_url，并更改行为以返回包含复制属性的字典，而不是轮询对象。可以通过 get_file_properties 操作检索复制操作的状态。
向 FileClient 类中添加了 abort_copy 操作。这取代了之前的复制状态轮询操作上的中止操作。
列出操作的行为已修改
- 已删除之前的 marker 参数。
- 可迭代的响应对象现在支持一个 by_page 函数，该函数将返回一个包含结果批次的二级迭代器。此函数支持一个 continuation_token 参数，用于替换之前的 marker 参数。
新的列出行为也由 receive_messages 操作采用
- 接收操作现在返回消息迭代器，与之前相同。
- 返回的迭代器支持一个 by_page 操作，以批量接收消息。

新功能

向子命名空间 azure.storage.file.aio 中添加了异步 API。
现在支持分布式跟踪框架 OpenCensus。

依赖项更新

采用 azure-core 1.0.0b2
- 如果您之后想回滚到 azure-storage-file 12.0.0b1 或需要 azure-core 1.0.0b1 的其他 Azure SDK 库，您必须显式安装 azure-core 1.0.0b1。例如
pip install azure-core==1.0.0b1 azure-storage-file==12.0.0b1

修复和改进

关闭文件句柄的修复 - 连续令牌没有被传递到后续调用。
对重复和共享代码进行了一般重构。

12.0.0b1

版本 12.0.0b1 是我们创建用户友好和 Pythonic 的 Azure Storage Files 客户端库努力的第一个预览版本。有关更多信息，以及其他 Azure SDK 库的预览版本，请访问 https://aka.ms/azure-sdk-preview1-python。

破坏性变更：新的 API 设计

操作现在限定于特定的客户端
- FileServiceClient：此客户端处理账户级别的操作。这包括管理服务属性和列出账户内的共享。
- ShareClient：客户端处理特定共享的操作。这包括创建或删除该共享，以及列出该共享内的目录，并管理属性和元数据。
- DirectoryClient：客户端处理特定目录的操作。这包括创建或删除该目录，以及列出文件和子目录，并管理属性和元数据。
- FileClient：客户端处理特定文件的操作。这包括创建或删除该文件，以及上传和下载数据，并管理属性。
可以通过导航客户端层次结构或直接使用资源（账户、共享、目录或文件）的 URL 实例化这些客户端。有关新 API 的完整详细信息，请参阅参考文档。
复制文件操作现在返回一个轮询对象，可以用于检查操作状态，以及中止操作。
close_handles 操作现在返回一个轮询对象，可以用于检查操作状态。
下载操作现在返回一个流对象，可以以多种方式下载数据
- 迭代：流器是一个可迭代的对象，将以块的形式下载并产生内容。仅支持单线程下载。
- content_as_bytes：以字节形式返回整个文件内容。阻塞操作，支持多线程下载。
- content_as_text：以解码文本形式返回整个文件内容。阻塞操作，支持多线程下载。
- download_to_stream：将整个内容下载到打开的流句柄（例如打开的文件）。支持多线程下载。
新的底层 REST 管道实现，基于新的 azure.core 库。
客户端和管道配置现在可以通过关键字参数在客户端级别和操作级别进行设置。请参阅参考文档以获取可选配置参数的完整列表。
新的错误层次结构
- 所有服务错误现在将使用基本类型：azure.core.exceptions.HttpResponseError
- 从该基本类型派生了一些特定的异常类型，用于常见的错误场景
  - ResourceNotFoundError：找不到资源（例如，队列、消息）。通常是一个404状态码。
  - ResourceExistsError：资源冲突 - 通常在尝试创建已存在的资源时发生。
  - ResourceModifiedError：资源已被修改（例如，被覆盖）并且当前操作存在冲突。或者，如果操作的条件不满足，也可能引发此错误。
  - ClientAuthenticationError：认证失败。
操作 set_file_properties 已重命名为 set_http_headers。
操作 get_file_to_<output> 已被替换为 download_file。请参见上述内容以获取下载输出选项。
操作 create_file_from_<input> 已被替换为 upload_file。
操作 get_share_acl 和 set_share_acl 已重命名为 get_share_access_policy 和 set_share_access_policy。
操作 set_share_properties 已重命名为 set_share_quota。
操作 snapshot_share 已重命名为 create_snapshot。
操作 copy_file 已重命名为 copy_file_from_url。
不再有针对 get_metadata 的特定操作 - 请使用 get_properties 代替。
不再有针对 exists 的特定操作 - 请使用 get_properties 代替。
操作 update_range 已重命名为 upload_range。

2.0.1

更新了对 azure-storage-common 的依赖。

2.0.0

支持 2018-11-09 REST 版本。请参阅我们的 REST API 文档和博客以获取有关相关新增功能的更多信息。
添加了获取以字节为单位的共享统计信息的选项。
添加了对列出和关闭文件句柄的支持。

1.4.0

在 Python 3 中不再安装 azure-storage-nspkg（基于 PEP420 的命名空间包）

1.3.1

修复了设计缺陷，当 max_connections 设置为 1 时，get_file_to_* 方法会缓冲整个文件。

1.3.0

支持 2018-03-28 REST 版本。请参阅我们的 REST API 文档和博客以获取有关相关新增功能的更多信息。

1.2.0rc1

支持 2017-11-09 REST 版本。请参阅我们的 REST API 文档和博客以获取有关相关新增功能的更多信息。

1.1.0

支持 2017-07-29 REST 版本。请参阅我们的 REST API 文档和博客以获取有关相关新增功能的更多信息。
错误信息现在包含来自 x-ms-error-code 报头值的 ErrorCode。

1.0.0

该软件包已从 Apache 2.0 许可证切换到 MIT 许可证。
修复了当 start_range 和 end_range 都等于 0 时，get_file_to_* 无法获取单个字节的错误。
从服务获取元数据键时现在会保留大小写。以前，库会将它们转换为小写。

项目详情

这些详情尚未由PyPI 验证

项目链接

主页

发布历史发布通知 | RSS 源

本版本

12.18.0

2024年9月17日

12.18.0b1 预发布

2024年8月7日

12.17.0

2024年7月18日

12.17.0b1 预发布

2024年6月11日

12.16.0

2024年5月8日

12.16.0b1 预发布

2024年4月16日

12.15.0

2023年11月7日

12.15.0b1 预发布

2023年10月17日

12.14.2

2023年10月10日

12.14.1

2023年9月13日

12.14.0

2023年9月12日

12.14.0b1 预发布

2023年8月8日

12.13.0

2023年7月11日

12.13.0b1 预发布

2023年5月31日

12.12.0

2023年4月13日

12.12.0b1 预发布

2023年3月28日

12.11.1

2023年3月9日

12.11.0

2023年2月22日

12.11.0b1 预发布

2023年2月3日

12.10.1

2022年10月19日

12.10.0

2022年10月11日

12.10.0b1 预发布

2022年8月23日

12.9.0

2022年7月7日

12.9.0b1 预发布

2022年6月15日

12.8.0

2022年5月10日

12.8.0b1 预发布

2022年4月14日

12.7.0

2022年3月9日

12.7.0b2 预发布

2022年2月7日

12.7.0b1 预发布

2021年12月14日

12.6.0

2021年9月20日

12.6.0b1 预发布

2021年7月28日

12.5.0

2021年6月10日

12.5.0b1 预发布

2021年5月14日

12.4.2

2021年4月22日

12.4.1

2021年1月21日

12.4.0

2021年1月14日

12.4.0b1 预发布

2020年12月7日

12.3.0

2020年11月11日

12.3.0b1 预发布

2020年10月2日

12.2.0

2020年8月13日

12.2.0b1 预发布

2020年7月8日

12.1.2

2020年6月12日

12.1.1

2020年3月11日

12.1.0

2020年2月12日

12.0.0

2019年12月4日

12.0.0b5 预发布

2019年10月31日

下载文件

下载适用于您平台的文件。如果您不确定选择哪个，请了解更多关于安装包的信息。

源分布

azure_storage_file_share-12.18.0.tar.gz (333.5 kB 查看散列值)

上传时间 2024年9月17日 源

构建分布

azure_storage_file_share-12.18.0-py3-none-any.whl (274.6 kB 查看散列值)

上传时间 2024年9月17日 Python 3

散列值 for azure_storage_file_share-12.18.0.tar.gz

散列值 for azure_storage_file_share-12.18.0.tar.gz
算法	散列摘要
SHA256	`0a81daee5e13598accde3c73b1aeccc6edfdcec5e957bf40150c0622fb95dc76`
MD5	`1879cb0f5879c0a28b5c114504aa9dc6`
BLAKE2b-256	`e12d6c7b69d3c29dbcdb81e6b87211f99878d131aa30fecc3a4f5c7a321d1b81`

散列值 for azure_storage_file_share-12.18.0-py3-none-any.whl

散列值 for azure_storage_file_share-12.18.0-py3-none-any.whl
算法	散列摘要
SHA256	`23ca35206a0cb8af0decd9d1363d0ad8ab31584a5e55cfc64528d7192ff748a9`
MD5	`2ab06b931469d500597ef0ff3144b966`
BLAKE2b-256	`3e332289f460906f1f70048665b158947da8e776dd44059e2e8b46fb3f64bb60`

azure-storage-file-share 12.18.0

导航

验证详情

维护者

未验证详情

项目链接

元信息

分类

项目描述

Azure Storage File Share客户端库

入门

先决条件

安装包

创建存储帐户

创建客户端

查找帐户URL

凭据类型

从连接字符串创建客户端

Key concepts

异步客户端

客户端

示例

创建文件共享

上传文件

下载文件

列出目录内容

可选配置

重试策略配置

其他客户端/操作配置

故障排除

通用

日志记录

下一步

更多示例代码

其他文档

贡献

发布历史

12.18.0 (2024-09-17)

新增功能

12.18.0b1（2024-08-07）

新增功能

其他更改

12.17.0 (2024-07-18)

新增功能

12.17.0b1（2024-06-11）

新增功能

12.16.0 (2024-05-07)

新增功能

12.16.0b1（2024-04-16）

新增功能

修复了错误

12.15.0 (2023-11-07)

新增功能

12.15.0b1（2023-10-17）

新增功能

12.14.2 (2023-10-10)

修复了错误

12.14.1 (2023-09-13)

修复了错误

12.14.0 (2023-09-12)

新增功能

12.14.0b1（2023-08-08）

新增功能

12.13.0 (2023-07-11)

新增功能

12.13.0b1（2023-05-30）

新增功能

12.12.0 (2023-04-12)

新增功能

12.12.0b1（2023-03-28）

新增功能

12.11.1 (2023-03-08)

修复了错误

12.11.0 (2023-02-22)

新增功能

12.11.0b1（2023-02-02）

新增功能

修复了错误

其他更改

12.10.1 (2022-10-18)

发布历史发布通知 | RSS 源