你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
从 URL 放置 Blob
该 Put Blob From URL 操作将创建一个新的块 Blob，其中 Blob 的内容是从指定的 URL 读取的。 此 API 自版本 2020-04-08 起可用。
不支持 Put Blob From URL部分更新。 现有 blob 的内容会被新 blob 的内容覆盖。 若要使用源 URL 对块 Blob 的内容执行部分更新，请将“从 URL 放置 Blob”API 与 Put Block List结合使用。
(MiB) ，源 Blob 的大小最大长度为 5,000 mb。
请求
可以按如下所示构造 Put Blob From URL 。 建议使用 HTTPS。 将 myaccount 替换为存储帐户的名称：
| PUT 方法请求 URI | HTTP 版本 |
|---|---|
https://myaccount.blob.core.windows.net/mycontainer/myblob |
HTTP/1.1 |
模拟存储服务请求
对模拟存储服务发出请求时，将模拟器主机名和 Blob 服务端口指定为 127.0.0.1:10000，后跟模拟存储帐户名称：
| PUT 方法请求 URI | HTTP 版本 |
|---|---|
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob |
HTTP/1.1 |
存储模拟器仅支持最多 2 gb (GiB) blob 大小。
有关详细信息，请参阅使用 Azurite 模拟器进行本地 Azure 存储开发。
URI 参数
可以在请求 URI 上指定以下附加参数：
| 参数 | 说明 |
|---|---|
timeout |
可选。 timeout 参数以秒表示。 有关详细信息，请参阅 为 Blob 服务操作设置超时。 |
请求标头
下表描述了必需的和可选的请求标头：
| 请求标头 | 说明 |
|---|---|
Authorization |
必需。 指定授权方案、帐户名称和签名。 有关详细信息，请参阅授权对 Azure 存储的请求。 |
Date 或 x-ms-date |
必需。 指定请求的协调世界时 (UTC)。 有关详细信息，请参阅授权对 Azure 存储的请求。 |
x-ms-version |
对于所有已授权的请求是必需的。 指定用于此请求的操作的版本。 有关详细信息，请参阅 Azure 存储服务的版本控制。 |
Content-Length |
必需。 指定在请求正文中传送的字节数。 此标头的值必须设置为 0。 当长度不为 0 时，操作将失败，状态代码为 400 (错误请求) 。 |
x-ms-copy-source:name |
必需。 指定源 Blob 的 URL。 该值可以是最多 2 千字节的 URL， (指定 blob 的 KiB) 长度。 此值应为 URL 编码，如同它显示在请求 URI 中那样。 源 Blob 必须是公共的，或者必须通过共享访问签名获得授权。 如果源 Blob 是公共的，则无需授权即可执行该操作。 如果源 Blob 的大小大于 5000 MiB，或者如果源未返回有效 Content-Length 值，则请求将失败，状态代码为 409 (冲突) 。 下面是源对象 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-blob-type: BlockBlob |
必需。 指定要创建的 Blob 的类型，该类型必须为 BlockBlob。 如果 blob 类型不是 BlockBlob，则操作失败，状态代码为 400 (错误请求) 。 |
Content-Type |
可选。 Blob 的 MIME 内容类型。 默认类型为 application/octet-stream。 |
Content-Encoding |
可选。 指定对 Blob 应用了哪种内容编码。 对 Blob 资源执行 “获取 Blob” 操作时，此值将返回到客户端。 返回此值后，客户端可以使用该值解码 Blob 内容。 |
Content-Language |
可选。 指定此资源使用的自然语言。 |
Cache-Control |
可选。 Blob 存储存储此值，但不使用或修改此值。 |
x-ms-source-content-md5 |
可选。 URI 中 Blob 内容的 MD5 哈希。 此哈希用于在从 URI 传输数据期间验证 Blob 的完整性。 指定此标头后，存储服务会将从复制源到达的内容哈希与此标头值进行比较。 如果省略此标头，Blob 存储将生成 MD5 哈希。 如果这两个哈希值不匹配，操作会失败，并显示错误代码 400（错误请求）。 |
x-ms-content-crc64 |
可选。 Blob 内容的 CRC64 哈希。 此哈希值用于验证传输期间 Blob 的完整性。 指定此标头后，存储服务会根据发送的哈希检查到达的哈希。 如果这两个哈希值不匹配，操作会失败，并显示错误代码 400（错误请求）。 版本 02-02-2019 及更高版本中支持此标头。 如果同时存在 Content-MD5 和 x-ms-content-crc64 标头，则请求失败，) 400 (错误请求。 |
x-ms-blob-content-type |
可选。 设置 Blob 的内容类型。 |
x-ms-blob-content-encoding |
可选。 设置 Blob 的内容编码。 |
x-ms-blob-content-language |
可选。 设置 Blob 的内容语言。 |
x-ms-blob-content-md5 |
可选。 设置 Blob 的 MD5 哈希。 |
x-ms-blob-cache-control |
可选。 设置 Blob 的缓存控制。 |
x-ms-meta-name:value |
可选。 作为元数据与 Blob 关联的名称/值对。 注意：从版本 2009-09-19 开始，元数据名称必须遵守 C# 标识符的命名规则。 |
x-ms-encryption-scope |
可选。 用于加密请求内容的加密范围。 版本 2019-02-02 及更高版本中支持此标头。 |
x-ms-tags |
可选。 在 Blob 上设置指定的查询字符串编码标记。 有关详细信息，请转到 “备注 ”部分。 在版本 2019-12-12 及更高版本中受支持。 |
x-ms-copy-source-tag-option |
可选。 可能的值为 REPLACE 或 COPY (区分大小写的) 。 默认值为 REPLACE。 如果指定了 COPY，则源 Blob 中的标记将复制到目标 Blob。 源 Blob 必须是专用的，并且请求必须具有获取源 Blob 上的 Blob 标记 和在目标 Blob 上 设置 Blob 标记 的权限。 这会导致对源帐户上的 “获取 Blob 标记” 操作进行额外调用。 REPLACE 设置由 x-ms-tags 目标 Blob 上的 标头指定的标记。 如果使用 REPLACE 且未指定 x-ms-tags任何标记，则不会在目标 Blob 上设置任何标记。 指定 COPY 和 x-ms-tags 会导致 409 (冲突) 。在版本 2021-04-10 及更高版本中受支持。 |
x-ms-copy-source-blob-properties |
可选。 指定复制源 Blob 属性行为。 如果设置为 True，则源 Blob 的属性将复制到新 Blob。 默认值为 True。 |
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。 如果 ETag 值不匹配，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 值，以便仅当指定的 ETag 值与现有目标 Blob 的值匹配时 ETag 放置 Blob。 如果目标 Blob 的 ETag 与为 If-Match指定的 ETag 不匹配，Blob 存储将返回状态代码 412 (前置条件失败) 。 |
If-None-Match |
可选。 ETag 值或通配符 (*)。 指定此条件标头的 ETag 值以仅当指定的 ETag 值与目标 Blob 的 ETag 值不匹配时放置 Blob。 指定通配符 (*) ，以仅当目标 blob 不存在时才执行操作。 如果不满足指定的条件，Blob 存储将返回状态代码 412 (前置条件失败) 。 |
x-ms-lease-id:<ID> |
如果 Blob 具有活动租约，则是必需的。 要在具有活动租约的 Blob 上执行此操作，请为此标头指定有效的租约 ID。 |
x-ms-blob-content-disposition |
可选。 设置 Blob 的 Content-Disposition 标头。 适用于版本 2013-08-15 及更高版本。响应 Content-Disposition 标头字段传达有关如何处理响应有效负载的其他信息，并可用于附加其他元数据。 例如，如果 标头设置为 attachment，则表示用户代理不应显示响应。 相反，它应显示一个“另存为”对话框，其文件名不是指定的 Blob 名称。“获取 Blob”和“获取 Blob 属性”操作的响应包括 content-disposition 标头。 |
Origin |
可选。 指定从中发出请求的来源。 如果存在此标头，则会在响应中产生跨域资源共享 (CORS) 标头。 有关详细信息，请参阅 对 Azure 存储服务的 CORS 支持。 |
x-ms-client-request-id |
可选。 提供客户端生成的不透明值，其中包含 1-kib (KiB) 启用存储分析日志记录时记录在分析日志中的字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 |
x-ms-access-tier |
可选。 指示要对 Blob 设置的层。 块 Blob 层 Hot的有效值为 、 Cool、 Cold和 Archive。 注意： Cold 版本 2021-12-02 及更高版本支持层。 HotArchive版本 Cool2018-11-09 及更高版本支持 、 和 。 有关块 Blob 分层的详细信息，请参阅 热、冷和存档存储层。 |
x-ms-expiry-option |
可选。 版本 2023-08-03 及更高版本。 指定请求的到期日期选项。 有关详细信息，请参阅 ExpiryOption。 此标头对启用了分层命名空间的帐户有效。 |
x-ms-expiry-time |
可选。 版本 2023-08-03 及更高版本。 指定 Blob 设置为过期的时间。 到期日期的格式因 x-ms-expiry-option而异。 有关详细信息，请参阅 ExpiryOption。 此标头对启用了分层命名空间的帐户有效。 |
仅当满足特定条件时，此操作还支持使用条件标头写入 Blob。 有关详细信息，请参阅 为 Blob 存储操作指定条件标头。
请求标头 (客户提供的加密密钥)
可以在请求中指定以下标头，以使用客户提供的密钥加密 Blob。 使用客户提供的密钥 (和相应的标头集) 加密是可选的。
| 请求标头 | 说明 |
|---|---|
x-ms-encryption-key |
必需。 Base64 编码的 AES-256 加密密钥。 |
x-ms-encryption-key-sha256 |
必需。 加密密钥的 Base64 编码 SHA256 哈希。 |
x-ms-encryption-algorithm: AES256 |
必需。 指定要用于加密的算法。 此标头的值必须为 AES256。 |
请求正文
无。
示例请求
下面的示例是一个创建块 Blob 的请求：
Request Syntax:
PUT https://myaccount.blob.core.windows.net/mycontainer/myblockblob HTTP/1.1
Request Headers:
x-ms-version: 2020-04-08
x-ms-date: <date>
Content-Type: text/plain; charset=UTF-8
x-ms-blob-content-disposition: attachment; filename="fname.ext"
x-ms-blob-type: BlockBlob
x-ms-meta-m1: v1
x-ms-meta-m2: v2
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-expiry-option: RelativeToNow
x-ms-expiry-time: 30000
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=
Content-Length: 0
响应
响应包括 HTTP 状态代码和一组响应标头。
状态代码
此操作成功后返回状态代码 201（已创建）。
有关状态代码的详细信息，请参阅 状态和错误代码。
响应头
此操作的响应包括以下标头。 响应还可以包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范。
| 响应标头 | 说明 |
|---|---|
ETag |
ETag 包含一个值，客户端可以使用该值通过 PUT 请求标头执行条件 If-Match 操作。 ETag 值用引号括起来。 |
Last-Modified |
上次修改 blob 的日期/时间。 日期格式遵循 RFC 1123。 有关详细信息，请参阅 在标头中表示日期/时间值。 针对 Blob 的任何写操作（包括更新 Blob 的元数据或属性）都会更改 Blob 的上次修改时间。 |
Content-MD5 |
为块 Blob 返回，以便客户端可以检查消息内容的完整性。 返回 Content-MD5 的值由 Blob 存储计算。 即使请求不包含 Content-MD5 或 x-ms-blob-content-md5 标头，也会返回此标头。 |
x-ms-content-crc64 |
为块 Blob 返回，以便客户端可以检查消息内容的完整性。 返回 x-ms-content-crc64 的值由 Blob 存储计算。 始终返回此标头。 |
x-ms-request-id |
唯一标识发出的请求，你可以使用它对请求进行故障排除。 有关详细信息，请参阅 API 操作疑难解答。 |
x-ms-version |
用于执行请求的 Blob 存储版本。 |
Date |
由服务生成的 UTC 日期/时间值，指示启动响应的时间。 |
Access-Control-Allow-Origin |
如果请求包含 Origin 标头并且通过匹配的规则启用了 CORS，则返回此标头。 如果存在匹配项，此标头将返回源请求标头的值。 |
Access-Control-Expose-Headers |
如果请求包含 Origin 标头并且通过匹配的规则启用了 CORS，则返回此标头。 返回将向客户端或请求的发出方公开的响应标头的列表。 |
Access-Control-Allow-Credentials |
如果请求包含 Origin 标头，并且启用了 CORS 并启用了不允许所有源的匹配规则，则返回 。 此标头设置为 true。 |
x-ms-request-server-encrypted: true/false |
如果使用指定的算法成功加密请求的内容，则此标头的值设置为 true 。 否则，该值将设置为 false。 |
x-ms-encryption-key-sha256 |
如果请求使用客户提供的密钥进行加密，则返回 ，以便客户端可以确保使用提供的密钥成功加密请求的内容。 |
x-ms-encryption-scope |
如果请求使用了加密范围，则返回 ，以便客户端可以确保使用加密范围成功加密请求的内容。 |
x-ms-version-id: <DateTime> |
返回唯一标识 blob 的不透明 DateTime 值。 此标头的值指示 Blob 的版本，并且可以在后续请求中使用它来访问 Blob。 |
响应正文
无。
示例响应
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
x-ms-content-crc64: 77uWZTolTHU
Date: <date>
ETag: "0x8CB171BA9E94B0B"
Last-Modified: <date>
Access-Control-Allow-Origin: http://contoso.com
Access-Control-Expose-Headers: Content-MD5
Access-Control-Allow-Credentials: True
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-version-id: <DateTime>
授权
在 Azure 存储中调用任何数据访问操作时，都需要授权。 可以如下所述授权 Put Blob From URL 操作。
如果请求使用 x-ms-tags 请求标头指定标记，则调用方必须满足 “设置 Blob 标记” 操作的授权要求。
Azure 存储支持使用 Microsoft Entra ID 授权对 Blob 数据的请求。 使用 Microsoft Entra ID，可以使用 Azure 基于角色的访问控制 (Azure RBAC) 向安全主体授予权限。 安全主体可以是用户、组、应用程序服务主体或 Azure 托管标识。 安全主体由 Microsoft Entra ID 进行身份验证，以返回 OAuth 2.0 令牌。 然后可以使用令牌来授权对 Blob 服务发出请求。
若要详细了解如何使用Microsoft Entra ID授权，请参阅使用 Microsoft Entra ID 授权访问 blob。
权限
下面列出了Microsoft Entra用户、组或服务主体调用Put Blob From URL操作所需的 RBAC 操作，以及包含此操作的最低特权内置 Azure RBAC 角色：
- Azure RBAC 操作：
- Create新的块 blob：Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action
- Create新的或覆盖现有的块 Blob：Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
- 最低特权内置角色：存储 Blob 数据参与者
若要详细了解如何使用 Azure RBAC 分配角色，请参阅 分配 Azure 角色以访问 Blob 数据。
注解
自 Put Blob From URL 版本 2020-04-08 起，支持该操作。
在版本 2020-10-02 及更高版本中，复制操作的源支持 Azure Active Directory 授权。
源 Blob 可以是任何类型的，包括块 Blob、追加 Blob 或页 Blob。 但是，目标 Blob 必须是块 Blob。
Put Blob From URL 操作会始终复制整个源 blob。 不支持复制字节范围或一组块。 若要执行部分更新，请参阅 放置阻止 URL。 目标 Blob 可以是现有的块 Blob，也可以是操作创建的新 Blob。
使用块 Blob 作为源对象时，将复制所有提交的 Blob 内容。 但是，不会保留阻止列表，也不会复制未提交的块。 目标 Blob 的内容与源 Blob 的内容相同，但不会保留已提交的阻止列表。
放置 Blob 属性和元数据
从复制源创建块 Blob 时，默认从源 Blob 复制标准 Blob 属性。 如果在请求中指定了应用程序元数据，则会在不复制源 Blob 元数据的情况下进行存储。 若要显式设置任何 HTTP 内容标头，可以在请求中指定相应的标头。
Content-TypeContent-EncodingContent-LengthCache-ControlContent-Disposition
目标 Blob 的大小始终与源 Blob 的大小匹配。 请求 Content-Length (中 Put Blob From URL 标头必须为 0，因为没有请求正文) ，并且目标 blob 的内容长度属性是从源的大小推断出来的。
从 URL 放置 Blob 自定义属性
Put Blob From Url 遵循与设置与标准 HTTP 标头关联的自定义属性相同的语义 Put Blob 。 有关详细信息，请参阅 Blob 自定义属性
Blob 索引标记
如果在 标头中提供了目标 Blob 的 x-ms-tags 标记，则必须对其进行查询字符串编码。 标记键和值必须符合 中指定的 Set Blob Tags命名和长度要求。 此外， x-ms-tags 标头最多可包含 2 KiB 的标记。 如果需要更多标记，请使用 Set Blob Tags 操作。
如果 标头中 x-ms-tags 未提供标记，则不会从源 Blob 复制标记。
加密范围和客户提供的密钥
Put Blob From URL API 分别使用 x-ms-encryption-scope 和 标头支持加密范围和 x-ms-encryption-key 客户提供的密钥。
x-ms-copy-source如果标头引用的源 Blob 与请求 URI 中的目标 Blob 相同，则操作将Put Blob From URL执行 Blob 的同步就地重写。 这允许重写 Blob 以使用不同的加密密钥或加密范围。
计费
定价请求可能源自使用 Blob 存储 API 的客户端，可以直接通过 Blob 存储 REST API 或 Azure 存储客户端库。 这些请求按事务产生费用。 事务类型会影响帐户的收费方式。 例如，读取事务累算到与写入事务不同的计费类别。 下表显示了基于存储帐户类型的请求的计费类别 Put Blob From URL ：
| 操作 | 存储帐户类型 | 计费类别 |
|---|---|---|
| 将 Blob 从 URL (目标帐户1) | 高级块 blob 标准常规用途 v2 标准常规用途 v1 |
写入操作 |
| 将 Blob 从 URL (源帐户2) | 高级块 blob 标准常规用途 v2 标准常规用途 v1 |
读取操作 |
1目标帐户针对启动写入的一个事务收费。
2源帐户对源对象的每个读取请求都会产生一个事务。
此外，如果源帐户和目标帐户位于不同区域 (例如美国北部和美国南部) ，则用于传输请求的带宽将作为出口向源存储帐户收费。 同一区域中帐户间的传出免费。
最后，在同一存储帐户中创建名称不同的新 Blob 会使用其他存储资源，因此该操作会导致存储帐户对这些附加资源的容量使用量产生费用。
若要了解指定计费类别的定价，请参阅Azure Blob 存储定价。