你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
从 URL 放置 Blob
Put Blob From URL 操作创建一个新的块 blob，其中从指定的 URL 读取 Blob 的内容。 此 API 自版本 2020-04-08 起提供。
Put Blob From URL不支持部分更新。 现有 Blob 的内容将用新 Blob 的内容覆盖。 若要使用源 URL 对块 blob 的内容执行部分更新，请使用 Put Block From URL API 与 Put Block List。
源 Blob 的大小最大长度为 5,000 字节（MiB）。
请求
可以按如下所示构造 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 gibibytes （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。 该值的 URL 长度可能高达 2 千字节（KiB），用于指定 Blob。 该值应采用 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 存储的请求。 注意：Microsoft Entra 仅支持持有者方案。 注意：如果源对象是可公开访问的，或者源对象位于存储帐户中，并且使用的是传入 x-ms-copy-source:name的 SAS 令牌，则不需要此标头。版本 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 设置由目标 blob 上 x-ms-tags 标头指定的标记。 如果使用 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 存储将返回状态代码 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 的 ETag 与为 If-Match指定的 ETag 不匹配，Blob 存储将返回状态代码 412（前置条件失败）。 |
If-None-Match |
自选。 ETag 值或通配符 \. 仅当指定的 ETag 值与目标 Blob 的 ETag 值不匹配时，才为此条件标头指定 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） 标头。 有关详细信息，请参阅 CORS 对 Azure 存储服务的支持。 |
x-ms-client-request-id |
自选。 提供客户端生成的不透明值，其中包含启用存储分析日志记录时在分析日志中记录的 1-kibibyte （KiB） 字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 |
x-ms-access-tier |
自选。 指示在 Blob 上设置的层。 块 blob 层的有效值为 Hot、Cool、Cold和 Archive。
注意：版本 2021-12-02 及更高版本支持 Cold 层。 版本 2018-11-09 及更高版本支持 Hot、Cool和 Archive。 有关块 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 包含一个值，客户端可以使用该值通过 If-Match 请求标头执行条件 PUT 操作。 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 标记 操作的授权要求。
重要
Microsoft建议将 Microsoft Entra ID 与托管标识配合使用来授权对 Azure 存储的请求。 与共享密钥授权相比，Microsoft Entra ID 提供更高的安全性和易用性。
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 操作：
- 最低特权内置角色：存储 Blob 数据参与者
若要详细了解如何使用 Azure RBAC 分配角色，请参阅 分配 Azure 角色以访问 blob 数据。
言论
自版本 2020-04-08 起，支持 Put Blob From URL 操作。
在版本 2020-10-02 及更高版本中，复制操作的源支持Microsoft Entra 授权。
源 Blob 可以是任何类型的，包括块 blob、追加 Blob 或页 Blob。 但是，目标 Blob 必须是块 Blob。
Put Blob From URL 操作始终复制整个源 blob。 不支持复制一系列字节或一组块。 若要执行部分更新，请参阅 从 URL 放置块。 目标 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 遵循与 Put Blob 相同的语义来设置与标准 HTTP 标头关联的自定义属性。 有关详细信息，请参阅 Blob 自定义属性
如果在 x-ms-tags 标头中提供了目标 blob 的标记，则必须对其进行查询字符串编码。 标记键和值必须符合 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 标头引用与请求 URI 中目标 Blob 相同的源 blob，Put Blob From URL 操作将执行 blob 的同步就地重写。 这样，重写 blob 即可使用不同的加密密钥或加密范围。
计费
定价请求可能源自使用 Blob 存储 API 的客户端，可以直接通过 Blob 存储 REST API 或 Azure 存储客户端库。 这些请求按事务产生费用。 事务类型会影响帐户的计费方式。 例如，读取事务累算到与写入事务不同的计费类别。 下表显示了基于存储帐户类型的 Put Blob From URL 请求的计费类别：
| 操作 | 存储帐户类型 | 计费类别 |
|---|---|---|
| 将 Blob 从 URL 放置（目标帐户1） | 高级块 blob 标准常规用途 v2 标准常规用途 v1 |
写入操作 |
| 从 URL 放置 Blob （源帐户2） | 高级块 blob 标准常规用途 v2 标准常规用途 v1 |
读取操作 |
1目标帐户针对一个事务收取启动写入费用。
2源帐户对源对象的每个读取请求都会产生一个事务。
此外，如果源帐户和目标帐户位于不同的区域（例如美国北部和美国南部），则用于传输请求的带宽将作为出口向源存储帐户收费。 同一区域中的帐户之间的出口是免费的。
最后，在同一存储帐户中创建具有不同名称的新 Blob 会使用其他存储资源，因此该操作会针对存储帐户对这些附加资源的容量使用情况产生费用。
若要了解指定计费类别的定价，请参阅 Azure Blob 存储定价。