你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
从 URL 放置范围
Put Range From URL
作创建一个新范围,作为从 URL 读取内容的文件的一部分提交。 在版本 2019-02-02 及更高版本中,启用了 SMB 协议的文件共享支持此作,在版本 2025-05-05 及更高版本中支持启用 NFS 协议的文件共享。
协议可用性
已启用文件共享协议 | 可用 |
---|---|
SMB |
![]() |
NFS |
![]() |
请求
Put Range From URL
请求构造如下。 建议使用 HTTPS。
方法 | 请求 URI | HTTP 版本 |
---|---|---|
放 | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
HTTP/1.1 |
将请求 URI 中显示的路径组件替换为你自己的路径组件,如下所示:
路径组件 | 描述 |
---|---|
myaccount |
存储帐户的名称。 |
myshare |
文件共享的名称。 |
mydirectorypath |
自选。 父目录的路径。 |
myfile |
文件的名称。 |
有关路径命名限制的信息,请参阅 名称和引用共享、目录、文件和元数据。
URI 参数
参数 | 描述 |
---|---|
timeout |
自选。
timeout 参数以秒为单位表示。 有关详细信息,请参阅 设置 Azure 文件存储作的超时。 |
请求标头
下表描述了必需和可选的请求标头:
常见请求标头
请求标头 | 描述 |
---|---|
Authorization |
必填。 指定授权方案、帐户名称和签名。 有关详细信息,请参阅 授权对 Azure 存储 的请求。 |
Date 或 x-ms-date |
必填。 指定请求的协调世界时(UTC)。 有关详细信息,请参阅 授权对 Azure 存储的请求。 |
x-ms-version |
所有授权请求都是必需的。 指定要用于此请求的作的版本。 在版本 2019-02-02 及更高版本中,启用了 SMB 协议的文件共享支持此作,在版本 2025-05-05 及更高版本中支持启用 NFS 协议的文件共享。 有关详细信息,请参阅 azure 存储服务 版本控制。 |
x-ms-copy-source:name |
必填。 指定源文件的 URL。 该值可以是长度最多为 2 KiB 的 URL,用于指定文件。 该值应采用 URL 编码,因为它将显示在请求 URI 中。 源文件必须是公共的,或者必须通过共享访问签名进行授权。 如果源文件是公共的,则无需授权才能执行该作。 下面是源对象 URL 的一些示例:
|
x-ms-copy-source-authorization: <scheme> <signature> |
自选。 指定复制源的授权方案和签名。 有关详细信息,请参阅 授权对 Azure 存储的请求。 Microsoft Entra 仅支持方案持有者。 版本 2020-10-02 及更高版本中支持此标头。 |
x-ms-write: { update } |
必填。 必须仅指定 update 。 如果使用 clear 调用请求,则请求将失败。
update 值将请求正文指定的字节写入指定范围。 |
Range 或 x-ms-range |
必填。 需要 Range 或 x-ms-range 。指定要写入的字节范围。 必须指定范围的开始和结尾。 此标头由 HTTP/1.1 协议规范定义。 对于更新作,范围最大可以为 4 MiB 大小。 Azure 文件仅接受 Range 和 x-ms-range 标头的单个字节范围,并且必须采用以下格式指定字节范围:bytes=startByte-endByte 。如果同时指定了 Range 和 x-ms-range ,则服务将使用 x-ms-range 的值。 有关详细信息,请参阅 指定 Azure 文件存储作的范围标头。 |
x-ms-source-range |
必填。 指定要从源读取的字节范围。 必须指定范围的开始和结尾。 Azure 文件仅接受 Range 和 x-ms-range 标头的单个字节范围,并且必须采用以下格式指定字节范围:bytes=startByte-endByte 。源范围的大小可达 4 MiB。 如果源范围大小超过 4 MiB,Azure 文件会返回状态代码 413(请求实体太大)。 如果源范围大小与范围(目标范围)大小不匹配,服务将返回状态代码 400(错误请求)。 |
Content-Length |
必填。 指定在请求正文中传输的字节数。 此标头的值必须设置为 0 。 如果未 0 长度,作将失败,状态代码为 400(错误请求)。 |
x-ms-client-request-id |
自选。 提供客户端生成的不透明值,该值具有配置日志记录时日志中记录的 1-kibibyte (KiB) 字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息,请参阅 监视 Azure 文件。 |
x-ms-source-content-crc64 |
自选。 URI 中指定范围的 CRC64 哈希。 此哈希用于验证从 URI 传输数据期间范围的完整性。 指定此标头后,Azure 文件会将从复制源到达的内容的哈希与此标头值进行比较。 注意:此 CRC64 哈希未随文件一起存储。 如果两个哈希不匹配,作将失败,错误代码为 400(请求错误)。 |
x-ms-source-if-match-crc64 |
自选。 CRC64 校验和值。 仅当从提供的校验和读取源匹配的给定范围的校验和时,才指定此标头来执行该作。 如果未满足指定的条件,Azure 文件存储将返回状态代码 412(前置条件失败)。 |
x-ms-source-if-none-match-crc64 |
自选。 CRC64 校验和值。 仅当从源读取的给定范围的校验和不同于提供的校验和时,才指定此标头来执行该作。 如果未满足指定的条件,Azure 文件存储将返回状态代码 412(前置条件失败)。 |
x-ms-lease-id: <ID> |
如果文件具有活动租约,则为必需。 适用于版本 2019-02-02 及更高版本。 如果文件位于启用了 NFS 协议的文件共享上,则忽略此标头,不支持文件租用。 |
x-ms-client-request-id |
自选。 提供客户端生成的不透明值,其字符限制为 1-kibibyte(KiB),该限制在启用 Azure 存储分析日志记录时记录在分析日志中。 强烈建议在将客户端活动与服务器收到的请求相关联时使用此标头。 有关详细信息,请参阅 监视 Blob 存储。 |
x-ms-file-last-write-time: { now ¦ preserve } |
自选。 版本 2021-06-08 及更高版本。 可以指定以下选项之一:
|
x-ms-file-request-intent |
如果需要 Authorization 标头指定 OAuth 令牌。 可接受的值为 backup 。 此标头指定,如果 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action 或 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 包含在分配给使用 Authorization 标头授权的标识的 RBAC 策略中,则应授予 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 。 适用于版本 2022-11-02 及更高版本。 |
x-ms-allow-trailing-dot: { <Boolean> } |
自选。 版本 2022-11-02 及更高版本。 布尔值指定是否应剪裁请求 URL 中存在的尾随点。 如果目标位于启用了 NFS 协议的文件共享上,则默认支持尾随点,则忽略此标头。 有关详细信息,请参阅 命名和引用共享、目录、文件和元数据。 |
x-ms-source-allow-trailing-dot: { <Boolean> } |
自选。 版本 2022-11-02 及更高版本。 布尔值指定是否应剪裁源 URL 中存在的尾随点。 仅当复制源位于 Azure 文件共享上时,才应指定此标头。 任何其他复制源类型都不支持此标头。 如果复制源位于启用了 NFS 协议的文件共享上,则默认支持尾随点,则忽略此标头。 有关详细信息,请参阅 命名和引用共享、目录、文件和元数据。 |
仅 SMB 请求标头
没有。
仅 NFS 请求标头
没有。
请求正文
无请求正文。
示例请求
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/mydir/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-page-write: update
x-ms-copy-source: http://myaccount2.file.core.windows.net/myshare2/mydirectory2/myfile2?sv=2018-11-09&sp=r&sr=s&se=2018-08-22T09%3A59%3A28.2185790Z&sig=Qn6QEET3Gn%2FhCEVcXuwG7ssatIYiYRM5pNIy4Q3N0cQ%3D
x-ms-date: Fri, 22 Aug 2018 01:15:50 GMT
x-ms-version: 2019-02-02
x-ms-range: bytes=100-1023
x-ms-source-range: bytes=200-1123
x-ms-source-content-crc64: 3bedb8b3730fc205
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 0
响应
响应包括 HTTP 状态代码和一组响应标头。
状态代码
成功的作返回状态代码 201(已创建)。 有关状态代码的详细信息,请参阅 状态和错误代码。
响应标头
此作的响应包括下表中的标头。 响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范。
常见响应标头
响应标头 | 描述 |
---|---|
ETag |
包含可用于有条件地执行作的值。 该值用引号引起来。 |
Last-Modified |
上次修改文件的日期和时间。 日期格式遵循 RFC 1123。 有关详细信息,请参阅 标头中的日期/时间值的表示形式。 对文件的任何写入作(包括对文件的元数据或属性的更新)更改文件的上次修改时间。 |
x-ms-request-id |
唯一标识已发出的请求,可以使用它对请求进行故障排除。 有关详细信息,请参阅 API作疑难解答。 |
x-ms-version |
指示用于执行请求的 FileREST API 版本。 |
Date |
由服务生成的 UTC 日期/时间值,该值指示启动响应的时间。 |
x-ms-content-crc64 |
返回以便客户端可以检查消息内容完整性。 此标头的值由 Azure 文件存储计算。 它不一定与请求标头中指定的值相同。 |
x-ms-client-request-id |
可用于对请求和相应的响应进行故障排除。 如果此标头存在于请求中,则此标头的值等于 x-ms-client-request-id 标头的值,并且该值包含不超过 1,024 个可见 ASCII 字符。 如果请求中不存在 x-ms-client-request-id 标头,则响应中不会显示该标头。 |
x-ms-file-last-write-time |
版本 2021-06-08 及更高版本。 文件的上次写入时间,采用 ISO 8601 格式(例如,2017-05-10T17:52:33.9551861Z )。 |
仅 SMB 响应标头
没有。
仅 NFS 响应标头
没有。
响应正文
没有。
示例响应
Response Status:
HTTP/1.1 201 Created
Response Headers:
Date: Sun, 22 Aug 2020 01:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Wed, 22 Aug 2020 01:13:31 GMT
x-ms-version: 2019-02-02
x-ms-content-crc64: 3bedb8b3730fc205
Content-Length: 0
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
授权
只有帐户所有者才能调用此作。
言论
Put Range From URL
作将一系列数据写入文件,其行为类似于 Put Range
作。 它使用指定源上的 Get File
作来读取源文件的数据、元数据和其他属性。 在版本 2020-10-02 及更高版本中,复制作的源支持Microsoft Entra 授权。
仅当指定的范围写入文件时,Put Range From URL
作才会返回成功 201(已创建)。