导出 (0) 打印
全部展开
此主题尚未评级 - 评价此主题

放置 Blob (REST API)

更新时间: 2014年1月

Put Blob 操作创建一个新的块 Blob 或页 Blob,或者更新现有块 Blob 的内容。

更新现有块 Blob 会覆盖该 Blob 的所有现有元数据。不支持使用Put Blob 进行部分更新;新 Blob 的内容会覆盖现有 Blob 的内容。要对块 Blob 的内容执行部分更新,请使用放置块列表 (REST API)操作。

请注意,调用Put Blob 创建页 Blob 只会初始化该 Blob。要向页 Blob 添加内容,请调用放置页 (REST API)操作。

可以按如下方式构建Put Blob请求。建议使用 HTTPS。将 myaccount 替换为您的存储帐户名称:

 

  PUT 方法请求 URI HTTP 版本

https://myaccount.blob.core.windows.net/mycontainer/myblob

HTTP/1.1

模拟的存储服务 URI

在针对模拟的存储服务发出请求时,请将模拟器主机名和 BLOB 服务端口指定为 127.0.0.1:10000,后跟模拟的存储帐户名称:

 

  PUT 方法请求 URI HTTP 版本

http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob

HTTP/1.1

请注意,存储仿真程序只支持大小不超过 2 GB 的 Blob。

有关详细信息,请参阅 About Development Storage存储仿真程序与 Windows Azure 存储服务之间的差异

URI 参数

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

 

参数 说明

timeout

可选。timeout 参数以秒表示。有关详细信息,请参阅为 BLOB 服务操作设置超时

请求标头(块 Blob 和页 Blob)

下表说明了块 Blob 和页 Blob 上的操作的必需和可选请求标头。

 

请求标头 说明

Authorization

必需。指定身份验证方案、帐户名和签名。有关详细信息,请参阅Windows Azure 存储服务身份验证

Datex-ms-date

必需。为请求指定协调世界时 (UTC)。有关详细信息,请参阅Windows Azure 存储服务身份验证

x-ms-version

对于所有验证的请求是必需的。指定用于此请求的操作的版本。有关详细信息,请参阅Windows Azure 中 BLOB 服务、队列服务和表服务的版本管理

Content-Length

必需。请求的长度。

对于页 Blob,此标头的值必须设置为零,因为放置 Blob (REST API) 只用来初始化页 Blob。页 Blob 的大小在 x-ms-blob-content-length 标头中指定。所有内容都必须通过调用放置页 (REST API)写入页 Blob。

Content-Type

可选。Blob 的 MIME 内容类型。默认类型为 application/octet-stream

Content-Encoding

可选。指定对 Blob 应用了哪种内容编码。此值是在对 Blob 资源执行获取 Blob (REST API) 操作时返回的。返回时客户端可以使用此值解码 Blob 内容。

Content-Language

可选。指定此资源使用的自然语言。

Content-MD5

可选。Blob 内容的 MD5 哈希值。此哈希值用于验证传输期间 Blob 的完整性。指定此标头时,存储服务会对已到达的哈希值与所发送的哈希值进行比较。如果这两个哈希值不匹配,操作会失败,并显示错误代码 400(错误请求)。

在版本 2012-02-12 和更新版本中省略此值时,BLOB 服务会生成一个 MD5 哈希值。

获取 Blob (REST API)获取 Blob 属性 (REST API)列出 Blob (REST API) 返回的结果包含 MD5 哈希值。

Cache-Control

可选。BLOB 服务存储此值,但并不使用或修改它。

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-blob-type:<BlockBlob | PageBlob>

必需。指定要创建的 Blob 类型:块 Blob 或页 Blob。

x-ms-meta-name:value

可选。作为元数据、与 Blob 关联的名称-值对。

请注意,从 2009-09-19 版开始,元数据名称必须遵循 C# 标识符的命名规则。

x-ms-lease-id:<ID>

如果 Blob 具有活动租约,则是必需的。要在具有活动租约的 Blob 上执行此操作,请为此标头指定有效的租约 ID。

x-ms-blob-content-disposition

可选。设置 Blob 的 Content-Disposition 标头。适用于版本 2013-08-15 和更高版本。

Content-Disposition 响应标头字段传达有关如何处理响应负载的详细信息,也可用于附加更多元数据。例如,如果设置为 attachment,它指示用户代理不应显示响应,而是应显示指定了文件名而非 Blob 名称的“另存为”对话框。

来自获取 Blob (REST API)获取 Blob 属性 (REST API) 操作的响应包含 content-disposition 标头。

Origin

可选。指定从中发出请求的来源。如果存在此标头,则会在响应中产生跨域资源共享标头。有关详细信息,请参阅对 Windows Azure 存储服务的跨域资源共享 (CORS) 支持

x-ms-client-request-id

可选。提供客户端生成的、具有 1 KB 字符限制的难理解的值,当启用存储分析日志记录时在分析日志中记录该值。强烈建议使用此标头以将客户端活动与服务器收到的请求关联。有关详细信息,请参阅关于存储分析日志记录Windows Azure 日志记录:使用日志跟踪存储请求

此操作还支持使用有条件头,以在满足指定条件时写入 Blob。有关详细信息,请参阅为 Blob 服务操作指定条件标头

请求标头(仅限页 Blob)

下表说明了仅适用于页 Blob 上的操作的请求标头。

 

请求标头 说明

x-ms-blob-content-length: bytes

对于页 Blob 是必需项。此标头指定页 Blob 的最大大小(最大 1 TB)。页 Blob 大小必须对齐 512 字节边界。

如果为块 Blob 指定此标头,BLOB 服务将返回状态码 400(错误请求)。

x-ms-blob-sequence-number: <num>

可选。仅对页 Blob 设置。序列号是一个用户控制的值,可以用来跟踪请求。序列号的值必须介于 0 和 2^63 - 1 之间。默认值为 0。

请求正文

对于块 Blob,请求正文包含 Blob 的内容。

对于页 Blob,请求正文为空。

示例请求

下面的示例是一个创建块 Blob 的请求:

Request Syntax:
PUT https://myaccount.blob.core.windows.net/mycontainer/myblockblob HTTP/1.1

Request Headers:
x-ms-version: 2013-08-15
x-ms-date: Wed, 23 Oct 2013 22:33:355 GMT
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
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=
Content-Length: 11

Request Body:
hello world

此示例请求创建一个页 Blob 并为其指定最大大小 1024 字节。请注意,必须调用放置页 (REST API)向页 Blob 添加内容:

Request Syntax:
PUT https://myaccount.blob.core.windows.net/mycontainer/mypageblob HTTP/1.1

Request Headers:
x-ms-version: 2013-08-15
x-ms-date: Wed, 23 Oct 2013 22:41:55 GMT
Content-Type: text/plain; charset=UTF-8
x-ms-blob-type: PageBlob
x-ms-blob-content-length: 1024
x-ms-blob-sequence-number: 0
Authorization: SharedKey 
Origin: http://contoso.com
Vary: Origin
myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=
Content-Length: 0

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

状态代码

成功的操作将返回状态代码 201(已创建)。

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

响应标头

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

 

响应标头 说明

ETag

ETag 包含一个值,客户端可以使用该值通过 PUT 请求标头执行条件 If-Match 操作。如果请求版本为 2011-08-18 和更高版本,ETag 值将用引号引起来。

Last-Modified

上次修改 Blob 的日期/时间。日期格式遵循 RFC 1123。有关详细信息,请参阅标头中日期/时间值的表示

针对 Blob 的任何写操作(包括更新 Blob 的元数据或属性)都会更改 Blob 的上次修改时间。

Content-MD5

针对块 Blob 返回此标头,以便客户端检查消息内容完整性。返回的 Content-MD5 值是由 BLOB 服务计算的。在版本 2012-02-12 和更新版本中,即使请求不包括 Content-MD5x-ms-blob-content-md5 标头,也会返回此标头。

x-ms-request-id

此标头唯一地标识发出的请求,并且可用于解决请求问题。有关详细信息,请参阅API 操作故障排除

x-ms-version

指示用于执行请求的 BLOB 服务的版本。针对 2009-09-19 和更高版本发出的请求将返回此标头。

Date

服务生成的 UTC 日期/时间值指示启动响应的时间。

Access-Control-Allow-Origin

如果请求包含 Origin 标头并且通过匹配的规则启用了 CORS,则返回此标头。如果存在匹配项,此标头返回原始请求标头的值。

Access-Control-Expose-Headers

如果请求包含 Origin 标头并且通过匹配的规则启用了 CORS,则返回此标头。返回将向客户端或请求的发出方公开的响应标头的列表。

Access-Control-Allow-Credentials

如果请求包含 Origin 标头并且通过不允许全部来源的匹配规则启用了 CORS,则返回此标头。此标头将设置为 True。

响应正文

无。

示例响应

Response Status:
HTTP/1.1 201 Created

Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
Date: Wed, 23 Oct 2013 22:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Wed, 23 Oct 2013 22:30:15 GMT
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

此操作可由帐户所有者调用执行,也可由有权向此 Blob 或其容器写入数据并具有共享访问签名的任何客户端执行。

创建 Blob 时,必须指定它是块 Blob 还是页 Blob。Blob 创建后,除非删除或重新创建,否则不能修改 Blob 类型。

要创建新的页 Blob,首先应调用Put Blob 初始化 Blob 并指定其最大大小(最大 1 TB)。创建页 Blob 时,不要在请求正文中包含内容。Blob 创建后,调用放置页 (REST API)向 Blob 添加内容或进行修改。

块 Blob 的最大上载大小为 64 MB。如果 Blob 大于 64 MB,则必须将它作为一组块上载。有关详细信息,请参阅Put Block (REST API)放置块列表 (REST API)操作。如果将 Blob 作为一组块上载,则无需调用Put Blob

如果尝试上载大于 64 MB 的块 Blob 或大于 1 TB 的页 Blob,服务将返回状态代码 413(请求实体过大)。BLOB 服务还会在响应中返回有关错误的详细信息,包括以字节数计的最大允许 Blob 大小。

如果调用Put Blob 覆盖具有相同名称的现有 Blob,将保留与原始 Blob 关联的所有快照。要删除关联快照,请先调用删除 Blob (REST API),然后调用Put Blob 重新创建 Blob。

Blob 具有自定义属性(通过头设置),可以用来存储与标准 HTTP 标头关联的值。随后可以调用获取 Blob 属性 (REST API)读取这些值,或者也可以调用设置 Blob 属性 (REST API)修改它们。下表中列出了自定义属性头及相应的标准 HTTP 标头:

 

HTTP 标头 自定义 Blob 属性头

Content-Type

x-ms-blob-content-type

Content-Encoding

x-ms-blob-content-encoding

Content-Language

x-ms-blob-content-language

Content-MD5

x-ms-blob-content-md5

Cache-Control

x-ms-blob-cache-control

保持这些属性值和 Blob 的语义如下:

  • 如果客户端指定自定义属性头,如由 x-ms-blob 前缀指示,则此值随 Blob 存储。

  • 如果客户端指定标准 HTTP 标头,但未指定自定义属性头,则此值存储在与 Blob 关联的相应自定义属性中,由对Get Blob Properties的调用返回。例如,如果客户端对请求设置 Content-Type 标头,则该值存储在 Blob 的 x-ms-blob-content-type 属性中。

  • 如果客户端对同一请求既设置标准 HTTP 标头又设置相应的属性头,PUT 请求将使用为标准 HTTP 标头提供的值,为自定义属性头指定的值会与 Blob 一起保持并由随后的 GET 请求返回。

如果 Blob 具有活动租约,则客户端必须在请求中指定有效租约 ID 才能覆盖 Blob。如果客户端不指定租约 ID,或指定无效的租约 ID,则 BLOB 服务将返回状态码 412(不满足前提条件)。如果客户端指定了一个租约 ID,但 Blob 没有活动租约,则 BLOB 服务也将返回状态码 412(不满足前提条件)。如果客户端对 Blob 指定的租约 ID 尚不存在,Blob 服务将对针对版本 2013-08-15 和更高版本提交的请求返回状态代码 412(不满足前提条件);对于以前的版本,Blob 服务将返回状态代码 201(已创建)。

如果Put Blob 操作覆盖了具有活动租约的现有 Blob,更新的 Blob 将保留租约,直至过期或释放。

对于每 MB,允许Put Blob 操作在 10 分钟内完成。如果操作的每 MB 平均时间超过 10 分钟,操作就会超时。

本文是否对您有所帮助?
(1500 个剩余字符)
感谢您的反馈
显示:
© 2014 Microsoft. 版权所有。