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

从 URL 复制 Blob

Copy Blob From URL 操作将 Blob 同步复制到存储帐户中的目标,以便源 blob 大小高达 256 mb (MiB) 。 此 API 从版本 2018-03-28 开始提供。

操作的 Copy Blob From URL 源可以是任何 Azure 存储帐户中提交的任何块 Blob,这些存储帐户是具有共享访问签名的公共或已授权的。

请求

可以按如下所示构造 Copy Blob From URL 请求。 建议使用 HTTPS。 将 myaccount 替换为存储帐户的名称,将 mycontainer 替换为容器的名称,将 myblob 替换为目标 Blob 的名称。

PUT 方法请求 URI HTTP 版本
https://myaccount.blob.core.windows.net/mycontainer/myblob HTTP/1.1

模拟存储服务的 URI

针对模拟存储服务发出请求时,请指定仿真器主机名和Azure Blob 存储端口127.0.0.1:10000,如下所示,后跟模拟存储帐户的名称:

PUT 方法请求 URI HTTP 版本
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob HTTP/1.1

有关详细信息,请参阅使用 Azurite 模拟器进行本地 Azure 存储开发

URI 参数

可以在请求 URI 上指定以下附加参数:

参数 说明
timeout 可选。 timeout 参数以秒表示。 有关详细信息,请参阅设置 Blob 存储操作的超时

请求标头

下表描述了必需和可选的请求标头:

请求标头 说明
Authorization 必需。 指定授权方案、帐户名称和签名。 有关详细信息,请参阅授权对Azure 存储的请求
Datex-ms-date 必需。 指定请求的协调世界时 (UTC)。 有关详细信息,请参阅授权对Azure 存储的请求
x-ms-version 所有授权请求都是必需的。 有关详细信息,请参阅 Azure 存储服务的版本控制
x-ms-meta-name:value 可选。 指定与 blob 关联的用户定义的名称/值配对。 如果未指定名称/值对,该操作会将元数据从源 Blob 或文件复制到目标 Blob。 如果指定了一个或多个名称/值对,则使用指定的元数据创建目标 Blob,并且不会从源 Blob 或文件复制元数据。

从版本 2009-09-19 开始,元数据名称必须遵循 C# 标识符的命名规则。 有关详细信息,请参阅 命名和引用容器、Blob 和元数据
x-ms-encryption-scope 可选。 指示加密请求内容的加密范围。 版本 2020-12-06 及更高版本中支持此标头。
x-ms-tags 可选。 设置 blob 上的查询字符串编码标记。 标记不会从复制源复制。 有关详细信息,请参阅 “备注”。 版本 2019-12-12 及更高版本中受支持。
x-ms-copy-source-tag-option 可选。 可能的值为 REPLACECOPY 区分大小写) (。 默认值为 REPLACE

如果 COPY 指定,源 Blob 中的标记将复制到目标 Blob。 源 Blob 必须是专用的,并且请求必须具有对源 Blob 上的“获取 Blob 标记 ”操作的权限,以及目标 Blob 上的 “设置 Blob 标记 ”操作。 这会产生对 Get Blob Tags 源帐户上的操作的额外调用。

REPLACE 将设置标头在目标 Blob 上指定的标记 x-ms-tags 。 如果 x-ms-tags 指定 REPLACE 且无标记,则目标 Blob 上不会设置任何标记。 指定 COPYx-ms-tags 将导致 409 (冲突) 错误。

版本 2021-04-10 及更高版本中受支持。
x-ms-source-if-modified-since 可选。 一个 DateTime 值。 如果指定此条件头,则仅当源 Blob 自指定日期/时间后发生了修改时才复制 Blob。 如果源 blob 尚未修改,Blob 存储返回状态代码 412 (前置条件失败) 。 如果源是 Azure 文件,则无法指定此标头。
x-ms-source-if-unmodified-since 可选。 一个 DateTime 值。 如果指定此条件头,则仅当源 Blob 自指定日期/时间后未修改时才复制 Blob。 如果源 blob 已修改,Blob 存储将返回状态代码 412 (前置条件失败) 。 如果源是 Azure 文件,则无法指定此标头。
x-ms-source-if-match 可选。 一个 ETag 值。 仅当源 Blob 的值与指定值匹配时 ETag ,才指定此条件标头以复制源 Blob。 如果值不匹配,Blob 存储返回状态代码 412 (前置条件失败) 。 如果源是 Azure 文件,则无法指定此标头。
x-ms-source-if-none-match 可选。 一个 ETag 值。 仅当 Blob 值与指定值不匹配时 ETag ,才指定此条件标头以复制 blob。 如果值相同,Blob 存储返回状态代码 412 (前置条件失败) 。 如果源是 Azure 文件,则无法指定此标头。
If-Modified-Since 可选。 一个 DateTime 值。 如果指定此条件头,则仅当目标 Blob 自指定日期/时间后发生了修改时才复制 Blob。 如果未修改目标 blob,Blob 存储返回状态代码 412 (前置条件失败) 。
If-Unmodified-Since 可选。 一个 DateTime 值。 如果指定此条件头,则仅当目标 Blob 自指定日期/时间后未修改时才复制 Blob。 如果目标 blob 已修改,Blob 存储返回状态代码 412 (前置条件失败) 。
If-Match 可选。 一个 ETag 值。 仅当指定的ETag值与现有目标 Blob 的值匹配ETag时,才指定此ETag条件标头的值以复制 blob。 如果值不匹配,Blob 存储返回状态代码 412 (前置条件失败) 。
If-None-Match 可选。 值 ETag 或通配符 (*) 。

仅当指定的ETag值与目标 Blob 的值不匹配ETag时,才指定此ETag条件标头的值以复制 blob。

仅当目标 blob 不存在时,才指定通配符 (*) 来执行该操作。

如果未满足指定条件,Blob 存储返回状态代码 412 (前置条件失败) 。
x-ms-copy-source:name 必需。 指定源 Blob 的 URL。 该值可以是最多 2 个基字节的 URL, (KiB) 长度指定 blob。 此值应为 URL 编码,如同它显示在请求 URI 中那样。 源 Blob 必须是公共的,或者必须通过共享访问签名获得授权。 如果源 Blob 是公共的,则无需授权才能执行该操作。 如果源 blob 的大小大于 256 MiB,则请求失败,并出现 409 (冲突) 错误。 源 Blob 的 Blob 类型必须是块 Blob。 下面是源对象 URL 的一些示例:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> 可选。 指定复制源的授权方案和签名。 有关详细信息,请参阅授权请求Azure 存储
只有Azure Active Directory支持方案持有者。
版本 2020-10-02 及更高版本中支持此标头。
x-ms-requires-sync:true 必需。 指示这是同步 Copy Blob From URL 操作,而不是异步 Copy Blob 操作。
x-ms-source-content-md5 可选。 指定 URI 中 Blob 内容的 MD5 哈希。 此哈希用于验证从 URI 传输数据期间 Blob 的完整性。 指定此标头后,存储服务会将从复制源到达的内容的哈希与此标头值进行比较。

MD5 哈希未随 Blob 一起存储。

如果两个哈希不匹配,则操作失败,错误代码为 400 (错误请求) 。
x-ms-lease-id:<ID> 如果目标 Blob 有活动租约,则是必需的。 此标头的租约 ID 必须与目标 Blob 的租约 ID 匹配。 如果请求不包含租约 ID 或无效,则操作失败,状态代码为 412 (前置条件失败) 。

如果指定了此标头,并且目标 Blob 当前没有活动租约,则操作失败,状态代码为 412 (前置条件失败) 。

在版本 2012-02-12 及更高版本中,此值必须为租用的 Blob 指定活动无限租约。 有限持续时间租约 ID 失败,状态代码 412 (前置条件失败) 。
x-ms-client-request-id 可选。 提供客户端生成的不透明值,其中包含配置日志记录时在 Azure Monitor 日志中记录的 1-KiB 字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息,请参阅 Azure 日志记录:使用日志跟踪存储请求

请求正文

无。

响应

响应包括 HTTP 状态代码和一组响应标头。

状态代码

成功的操作将返回状态代码 202(已接受)。

有关状态代码的信息,请参阅 状态代码和错误代码

响应头

此操作的响应包括以下标头。 响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范

响应标头 说明
ETag 如果副本已完成,则包含 ETag 目标 Blob 的值。 如果副本未完成,则包含 ETag 复制开始时创建的空 Blob 的值。

该值 ETag 以引号表示。
Last-Modified 返回复制到目标 Blob 的日期/时间。
x-ms-request-id 唯一标识已发出的请求。 可以使用它对请求进行故障排除。 有关详细信息,请参阅 API 操作疑难解答
x-ms-version 指示用于执行请求的 Blob 存储版本。
Date 一个 UTC 日期/时间值,该值指示服务发送响应的时间。
x-ms-copy-id: <id> 此复制操作的字符串标识符。
x-ms-copy-status: <success> 指示复制操作的状态。 一个值 success ,表示操作成功完成。
x-ms-client-request-id 可用于对请求和相应的响应进行故障排除。 如果此标头存在于请求中并且该值最多为 1,024 个可见 ASCII 字符,则此标头的值等于标头的值 x-ms-client-request-idx-ms-client-request-id如果请求中不存在标头,则响应中不会存在此标头。
x-ms-request-server-encrypted: true/false Set to true if the contents of the request are successfully encrypted through the specified algorithm. 否则,此值为 false
x-ms-encryption-scope 如果请求使用了加密范围,则返回该请求,因此客户端可以确保通过加密范围成功加密请求的内容。

响应正文

无。

示例响应

下面是 Blob 复制请求的示例响应:

Response Status:  
HTTP/1.1 202 Accepted  
  
Response Headers:   
Last-Modified: <date>   
ETag: "0x8CEB669D794AFE2"  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2018-03-28  
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-copy-status: success  
Date: <date>  
  

授权

此操作可由帐户所有者和具有共享访问签名的任何人调用,他们有权写入此 Blob 或其容器。

对源 blob 或文件的访问权限单独获得授权,如请求标头 x-ms-copy-source的详细信息中所述。

如果请求使用请求标头指定标记 x-ms-tags ,则调用方必须满足 “设置 Blob 标记 ”操作的授权要求。

注解

操作的源 Blob 和目标 Blob Copy Blob From URL 必须是块 Blob。

在版本 2020-10-02 及更高版本中,复制操作源支持Azure Active Directory授权。

Copy Blob From URL 操作始终复制整个源 Blob。 不支持复制字节范围或块集。

可以将源 Blob 复制到具有不同名称的目标 Blob。 目标 Blob 可以是现有块 Blob,也可以是复制操作创建的新 Blob。

从块 Blob 复制时,将复制所有已提交的块及其块 ID。 未提交的块不会复制。 在复制操作结束时,目标 Blob 将具有与源相同的已提交块计数。

ETag当操作开始和操作完成后,块 Blob 的值将更改Copy Blob From URL

复制 Blob 属性和元数据

复制块 Blob 时,以下系统属性将复制到具有相同值的目标 Blob:

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-Length

  • Cache-Control

  • Content-MD5

  • Content-Disposition

源 Blob 的已提交块列表也会复制到目标 Blob。 不会复制任何未提交的块。

目标 Blob 的大小始终与源 Blob 相同,因此目标 Blob 的 Content-Length 标头值与源 Blob 的标头值匹配。

x-ms-tags如果标头为目标 Blob 提供标记,则必须对其进行查询字符串编码。 标记键和值必须符合 “设置 Blob 标记 ”操作中指定的命名和长度要求。

标头 x-ms-tags 最多可以包含 2 千位标记。 如果需要更多标记,请使用 Set Blob Tags 该操作。

x-ms-tags如果标头不提供标记,则不会从源 Blob 复制标记。

复制租用的 Blob

Copy Blob From URL 操作仅从源 Blob 读取,因此源 Blob 的租约状态无关紧要。

计费

操作的目标帐户 Copy Blob From URL 由一个事务收取启动操作的费用。 目标帐户还会针对对复制操作源的每个请求产生一个事务。

源帐户还会产生事务成本。 此外,如果源帐户和目标帐户位于不同区域 (,例如美国北部和美国南部) ,则用于传输请求的带宽会作为出口向源存储帐户收费。 同一区域中帐户间的传出免费。

将源 Blob 复制到同一帐户中具有不同名称的目标 Blob 时,需为新 Blob 使用其他存储资源。 然后,复制操作会针对存储帐户对这些额外资源的容量使用情况产生费用。

另请参阅

授权请求Azure 存储
状态和错误代码
Blob 存储错误代码
了解快照如何累算费用