你当前正在访问 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 存储 的请求。
Datex-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 的一些示例:
  • https://myaccount.file.core.windows.net/myshare/mydir/myfile
  • https://myaccount.file.core.windows.net/myshare/mydir/myfile?<sastoken>
x-ms-copy-source-authorization: <scheme> <signature> 自选。 指定复制源的授权方案和签名。 有关详细信息,请参阅 授权对 Azure 存储的请求。
Microsoft Entra 仅支持方案持有者。
版本 2020-10-02 及更高版本中支持此标头。
x-ms-write: { update } 必填。 必须仅指定 update。 如果使用 clear调用请求,则请求将失败。 update 值将请求正文指定的字节写入指定范围。
Rangex-ms-range 必填。 需要 Rangex-ms-range

指定要写入的字节范围。 必须指定范围的开始和结尾。 此标头由 HTTP/1.1 协议规范定义。

对于更新作,范围最大可以为 4 MiB 大小。

Azure 文件仅接受 Rangex-ms-range 标头的单个字节范围,并且必须采用以下格式指定字节范围:bytes=startByte-endByte

如果同时指定了 Rangex-ms-range,则服务将使用 x-ms-range的值。 有关详细信息,请参阅 指定 Azure 文件存储作的范围标头
x-ms-source-range 必填。 指定要从源读取的字节范围。 必须指定范围的开始和结尾。

Azure 文件仅接受 Rangex-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 及更高版本。 可以指定以下选项之一:
  • now:默认值。 将上次写入时间时间戳更新为请求的时间。
  • preserve:保持现有上次写入时间戳不变。
x-ms-file-request-intent 如果需要 Authorization 标头指定 OAuth 令牌。 可接受的值为 backup。 此标头指定,如果 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/actionMicrosoft.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(已创建)。

另请参阅

对文件