此页面有用吗?
您对此内容的反馈非常重要。 请告诉我们您的想法。
更多反馈?
1500 个剩余字符
导出 (0) 打印
全部展开

放置页 (REST API)

更新时间: 2015年4月

Put Page operation writes a range of pages to a page blob.

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

 

  PUT 方法请求 URI HTTP 版本

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page

HTTP/1.1

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

 

  PUT 方法请求 URI HTTP 版本

http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=page

HTTP/1.1

有关详细信息,请参阅Using the Azure Storage Emulator for Development and Testing

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

 

Parameter 说明

timeout

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

下表介绍必需的和可选的请求标头。

 

请求标头 说明

Authorization

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

Datex-ms-date

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

x-ms-version

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

Range

Range or x-ms-range is required.

指定要写为页的字节范围。必须指定范围的上限和下限。此标头由 HTTP/1.1 协议规范定义。

对于页更新操作,页范围的大小可高达 4 MB。对于页清除操作,页范围可高达 Blob 的实际大小值。

假定页必须与 512 字节的边界对齐,则起始偏移量必须为 512 的模数,而结束偏移量必须为 512 – 1 的模数。有效字节范围的示例包括 0-511、512-1023 等。

Blob 服务仅接受 Range 标头的单字节范围,并且必须使用以下格式指定字节范围:bytes=startByte-endByte

如果指定了 Rangex-ms-range,服务将使用 x-ms-range 值。有关更多信息,请参见为 Blob 服务操作指定范围标头

x-ms-range

Range or x-ms-range is required.

指定要写为页的字节范围。必须指定范围的上限和下限。此标头由 HTTP/1.1 协议规范定义。

对于页更新操作,页范围的大小可高达 4 MB。对于页清除操作,页范围可高达 Blob 的实际大小值。

假定页必须与 512 字节的边界对齐,则起始偏移量必须为 512 的模数,而结束偏移量必须为 512 – 1 的模数。有效字节范围的示例包括 0-511、512-1023 等。

Blob 服务仅接受 x-ms-range 标头的单字节范围,并且必须使用以下格式指定字节范围:bytes=startByte-endByte

如果指定了 Rangex-ms-range,服务将使用 x-ms-range 值。有关更多信息,请参见为 Blob 服务操作指定范围标头

Content-Length

必需。指定在请求正文中传送的字节数。当 x-ms-page-write 标头设置为 clear 时,此标头的值必须设置为零。

Content-MD5

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

Content-MD5 标头设置为 x-ms-page-write 时,不允许使用 clear 标头。如果该标头包含在请求中,BLOB 服务将返回状态代码 400(错误请求)。

x-ms-page-write: {update | clear}

必需。可以指定以下选项之一:

  • Update:将请求正文指定的字节写入指定的范围。RangeContent-Length 标头必须匹配才能执行更新。

  • Clear:清除指定的范围并释放该范围的存储中所使用的空间。要清除范围,请将 Content-Length 标头设置为零,并将Range 标头设置为一个指示要清除范围的值,该值可达最大 Blob 大小。

x-ms-lease-id:<ID>

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

x-ms-if-sequence-number-le: <num>

可选。如果 Blob 的序列号小于或等于指定值,请求将继续;否则,请求将失败并出现 SequenceNumberConditionNotMet 错误(HTTP 状态代码 412 – 前置条件失败)。

x-ms-if-sequence-number-lt: <num>

可选。如果 Blob 的序列号小于指定值,请求将继续;否则,请求将失败并出现 SequenceNumberConditionNotMet 错误(HTTP 状态代码 412 – 前置条件失败)。

x-ms-if-sequence-number-eq: <num>

可选。如果 Blob 的序列号等于指定值,请求将继续;否则,请求将失败并出现 SequenceNumberConditionNotMet 错误(HTTP 状态代码 412 – 前置条件失败)。

If-Modified-Since

可选。一个 DateTime 值。指定仅当 Blob 自指定日期/时间以来修改过时,此条件头才写入页。如果 Blob 未修改过,BLOB 服务将返回状态代码 412(前置条件失败)。

If-Unmodified-Since

可选。一个 DateTime 值。指定仅当 Blob 自指定日期/时间以来未修改过时,此条件头才写入页。如果 Blob 修改过,BLOB 服务将返回状态代码 412(前置条件失败)。

If-Match

可选。ETag 值。指定仅当 Blob 的 ETag 值与指定值匹配时,此条件头的 ETag 值才写入页。如果值不匹配,BLOB 服务将返回状态代码 412(前提条件失败)。

If-None-Match

可选。ETag 值。

指定仅当 Blob 的 ETag 值与指定值不匹配时,此条件头的 ETag 值才写入页。如果值相同,BLOB 服务将返回状态代码 412(不满足前提条件)。

x-ms-client-request-id

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

此操作还支持仅当满足指定条件时才使用条件头执行操作。有关详细信息,请参阅为 Blob 服务操作指定条件标头

请求正文包含页内容。


Request Syntax:
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1

Request Headers:
x-ms-page-write: update
x-ms-date: Fri, 16 Sep 2011 22:15:50 GMT
x-ms-version: 2011-08-18
x-ms-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536


Request Syntax:
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1

Request Headers:
Range: bytes=1024-2048
x-ms-page-write: clear
x-ms-date: Sun, 25 Sep 2011 23:37:35 GMT
x-ms-version: 2011-08-18
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=

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

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

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

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

 

语法 说明

ETag

Blob 的 ETag。如果请求版本为 2011-08-18 和更高版本,ETag 值将用引号引起来。ETag 可用于通过为 If-MatchIf-None-Match 请求标头指定值来执行Put Page条件操作。

Last-Modified

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

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

Content-MD5

返回此标头是为了客户端可以检查消息内容完整性。此标头的值由 BLOB 服务计算;它不一定是请求标头中事先指定的同一值。

x-ms-blob-sequence-number

页 Blob 的当前序列号。

x-ms-request-id

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

x-ms-version

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

Date

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

无。

Response Status:
HTTP/1.1 201 Created

Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
Date: Sun, 25 Sep 2011 22:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Sun, 25 Sep 2011 12:13:31 GMT
x-ms-version: 2011-08-18
x-ms-blob-sequence-number: 0
Content-Length: 0
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

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

Put Page operation writes a range of pages to a page blob.只能对现有页 Blob 调用此操作。不能调用该操作来创建新的页 Blob,也不能对块 Blob 调用该操作。使用当前不存在的 Blob 名称调用Put Page时,将返回 BlobNotFound 错误(HTTP 状态代码 404 – 未找到)。

要创建新的页 Blob,请调用放置 Blob 并指定要创建为页 Blob 的 Blob 类型。页 Blob 的大小可高达 1 TB。

如果 Blob 具有活动租约,则客户端必须为请求指定有效租约 ID 才能写入页。

页更新操作

使用 Update 选项调用Put Page时,将对指定的页 Blob 执行就地写入。更新将覆盖指定页中的所有内容。

Important重要提示
如果Put Page期间服务器超时或连接关闭,页可能已更新,也可能尚未更新。因此,应继续重试更新,直到收到指示成功的响应。

使用Put Page为更新操作提交的每个页范围的大小可高达 4 MB。页的起始和结束范围必须与 512 字节的边界对齐。如果尝试加载超过 4MB 的页范围,服务将返回状态代码 413(请求实体过大)。

页清除操作

使用 Clear 选项调用Put Page时,将释放指定页所使用的存储空间。已清除的页将不再作为页 Blob 的一部分进行跟踪。

已清除的页不再产生针对存储帐户的计费,因为其存储资源已释放。唯一的例外是页 Blob 的现有快照;如果快照中的页不再作为源 Blob 的一部分存在,这些页将产生计费。

管理并发问题

Blob 服务按顺序处理对重叠页的并发写入:该服务所处理的最后一页确定 Blob 的内容。因此,为了确保 Blob 内容的完整性,客户端应使用以下方法之一处理对重叠页的写入:

  • 可以检查对Put Page的每个成功调用的 Last-Modified 响应标头的值。从 BLOB 服务返回的响应顺序不一定与服务执行的顺序一致。但 Last-Modified 的值始终指示服务处理请求的顺序。

  • 可以使用乐观并发机制根据 Blob 的 ETag 或上次修改时间有条件地执行更新。如果并发写入数相对较低,此方法十分适用。使用条件请求标头 If-MatchIf-None-MatchIf-Modified-SinceIf-Unmodified-Since 可实现此用途。

  • 可以调用租用 Blob,以针对其他写入将 Blob 锁定一分钟,或者更长的时间(如果续订租约)。

  • 可以使用 Blob 的序列号确保重试没有响应的请求不会导致并发更新。此方法可能最适合于需要高吞吐量执行页写入的客户端。这一点将在下一节详细说明。

使用页 Blob 序列号重试请求

当对Put Page的调用超时或未返回响应时,无法确定请求是否成功。因此,需要重试请求,但由于 Azure 存储服务的分布式特性,可能会在重试的请求成功后处理原始请求。延迟的原始请求可能覆盖其他更新并产生意外结果。以下序列说明这是如何发生的:

  1. 将值“X”写入页 0 的Put Page请求超时或未返回响应。

  2. 将值“X”写入页 0 的重试请求成功。

  3. 将值“Y”写入页 0 的请求成功。

  4. 原始请求成功,从而将值“X”写入页 0。

  5. 读取页 0 时返回值“X”,此时客户端需要值“Y”。

当原始请求未返回介于 100-499 之间的状态代码或 503(服务器忙)状态代码时,将发生这种冲突。如果返回其中的某一状态代码,则可以确定请求是成功还是失败。但如果该服务返回超出此范围的状态代码,则无法知道原始请求的状态。

要避免这种冲突,可以使用页 Blob 的序列号确保重试请求时,原始请求不会随之成功。为此,应在重试原始请求之前递增序列号。这样,可以使用条件序列号标头确保原始请求在其序列号与预期序列号不匹配时失败。以下序列说明这种方法:

  1. 客户端使用放置 Blob 创建页 Blob 并将其序列号设置为 0。

  2. 将值“X”写入页 0 且 if-sequence-number-lt 标头设置为 1Put Page请求超时或未返回响应。

  3. 客户端调用 Blob 属性以将序列号更新为 1。

  4. 将值“X”写入页 0 且 if-sequence-number-lt 设置为 2 的重试请求成功。

  5. 将值“Y”写入页 0 且 if-sequence-number-lt 设置为 2 的请求成功。

  6. 原始请求最终将得到处理,但它将失败,因为它指定序列号必须小于 1(即 if-sequence-num-lt 标头设置为 1)的条件。错误为 SequenceNumberConditionNotMet(HTTP 状态代码 412 – 前置条件失败)。

  7. 读取页 0 时返回预期值“Y”。

显示:
© 2015 Microsoft