阿里云-归档存储-API手册-D

1、归档存储API使用手册移动推送/OpenAPI文档移动推送/OpenAPI文档 PAGE 55 PAGE 55API使用手册欢迎使用阿里云归档存储。归档存储作为阿里云数据存储服务体系的一部分，提供了极低成本的数据存储服务。适合各种离线数据，包括但不局限于数字媒体、企业归档资料、科学实验数据、个人备份等。用户可以将数 据进行几个月、几年甚至几十年的长时间存储。同时不需要任何基础设施的投入，即可拥有无限扩容、可选择 地域的低成本数据归档方案，也免去了后续数据的管理维护成本。 需要注意的是，存放于归档存储的数据大部分时间会处于休眠状态，而对数据的唤醒操作需要消耗一些时间和资源，因此如果您对数据长期稳

2、定存储 的需求较高，而对数据的访问和读取速度要求较低的话，归档存储会是一个理想的选择。 用户可以使用本文档介绍的API对归档存储进行相关操作。在使用这些接口前，请确保已充分了解归档存储产品说明、使用协议和收 费方式。若要了解更多相关信息，请访问阿里云归档存储官方网站 HYPERLINK /product/oas /product/oas。基本概念阿里云归档存储的数据模型，由Vault（目录）和Archive（文档）组成。Archive在归档存储中，用户操作的基本数据单元是Archive，它需要包含在Vault（1.1.2）中。Archive可以是任意类 型的数据。上传Archive（4.2.1

3、）时，文档大小限制在6GB；如果文档大小超出6GB，请使用Multipart Upload（1.1.4）方式。Archive包含ArchiveID、Description和Data等Data信息，其中ArchiveID是，Description是用户对该Archive的描 述，Data是ArchiveArchive目前仅支持通过API进行操作。VaultArchive的目录，也是计费、权限控制等功能的管理单位。Vault名称在每 个用户的每个Region（1.1.3）下唯一，每个用户在每个Region最多可以创建10个Vault，Vault不支持嵌套。 每个Vault里可以包含任意数量的Arc

4、hive。Vault可以通过阿里云管理控制台、API两种方式进行创建、删除等 操作。Vault的命名规范：只能包含小写字母、数字、下划线（_）、短横线（-）；必须以小写字母或者数字开头和结尾；3-63Region专有网络 VPC/API使用手册专有网络 VPC/API使用手册Region是归档存储集群的标识。各Region间的操作相互独立。当前可用Region列表参见2.1.1。MultipartUploadMultipart Upload是把单个文档分段上传的方式，每段称之为Part（1.1.5），目的是为了便于用户上传较大的文档。使用Multipart Upload最大可以上传10000*

5、4GB的文档。不仅如此，多段上传还支持独立、任意顺序、甚至并行上传这些段。如果某段上传失败，只需要重新上传该段即可。我们建议用户在上传大于100MB的文档 时使用这种方式。 该上传操作是异步方式，用户需要首先新建Multipart Upload任务，指定每次需要上传的Part字节长度，该长度值必须能够被1MB整除，且介于32MB到4096MB之间。任务启动成功后，归档存储会 为该任务分配唯一的Upload ID，用户需要使用该ID作为标识完成后续Part的上传与合并。需要注意的是该任务自创建起24小时后，会自动失效。Part启动MultipartUpload任务成功以后，单独上传的某个范围内的

6、文档数据称为Part。用户上传时需要指定Part在文档中所属的范围。当所有Part都上传成功以后，用户还需要主动发起一次Part合并请求（4.3.6），才 能将上传的数据完整地提交到归档存储，否则任务创建超出24小时以后，用户在该任务中上传的数据将会丢失。Job归档存储的Vault/Archive的内容提取为异步操作，用户需要首先提交指定类型的Job完成对数据的唤醒，然 后通过查询Job状态来确认Job是否完成。在正常情况下，任务会在4小时内完成。Job完成以后，就可以获取 Job Output。 Job类型可以是inventory-retrieval或archive-retrieval。前者

7、获取到的Job Output是Job指定Vault的Archive列表信息，后者则是Job指定Archive的数据内容。注意inventory-retrieval类型Job获取到的Archive列表信息是由系统每天定期扫描生成的信息，不是实时数据。这两种Job类型为方便阿里云用户在归档存储产品与OSS产品 之间实现数据归档、提档功能，并帮助用户实现无中转方式的跨产品数据传输。pull-from-oss类型的Job用于 将用户在OSS产品上的Object归档到归档存储产品。 push-to-oss类型的Job用于将用户在归档存储产品上的Archive，提档到OSS产品。 这两种类型的Job依赖用

8、户对归档存储产品授予用户OSS访问权限。AccessKeyID、AccessKeySecret归档存储会对每个访问的请求进行身份验证，请求中需要包含签名（Signature）信息。归档存储通过使用AccessKeyID和AccessKeySecret进行对称加密的方法来验证请求的发送者身份。AccessKeyID和Access Key Secret由阿里云官方颁发给访问者（可以通过阿里云官方网站申请和管理），其中Access Key ID用于标识访问者的身份；Access Key Secret是用于加密签名字符串和服务器端验证签名字符串的密钥，请严格保密，请勿泄露给第三方。ContentEta

9、g、TreeEtag归档存储会对上传的单文档或者文档分段，进行ContentEtag和TreeEtag两种方式的数据校验。ContentEtag是对数据进行md5sum校验的数值，TreeEtag是对数据按照tree-hash算法校验的数值（tree-hash算法参考：归档存储 API调用方式-2.5.2 x-oas-tree-etag校验码）。功能简介Vault操作归档存储目前支持Vault创建（4.1.1）、删除（4.1.2）、单个Vault信息查询（4.1.3）以及Vault列表查询（4.1.4），需要注意的是：如果Vault中包含有Archive，删除操作会失败；Vault列表查询不支

10、持跨Region操作，同一请求只能获取单个Region下用户的Vault列表；用户获取Vault统计信息时，该信息不是实时更新。返回消息中Last Inventory（最后统计时间）的标识，反映了该信息的最后统计时间，信息更新来自归档存储系统定期扫描统计或者由用户主动发起的inventory-retrieval类型Job；Vault创建操作会返回Vault ID，其他的Vault操作都需要使用该ID来完成。Archive操作Archive操作包括上传（4.2.1）和删除（4.2.2）。Archive上传成功以后，归档存储会返回唯一的Archive ID，删除操作需要使用该Archive ID。

11、MultipartUpload操作Multipart Upload操作包括任务初始化（4.3.1）、删除（4.3.3）、任务列表查询（4.3.2）。初始化操作成功以后会启动一个多段上传的任务并返回Upload ID，后续的Part上传（4.3.4）、已上传完成的Part列表查询（4.3.5）以及Part合并操作（4.3.6）都需要指定该Upload ID。用户可以通过Multipart Upload删除操作（4.3.3）主动取消相应Archive的多段上传；多个Multipart Upload任务可以通过任务列表查询（4.3.2）来获取任务信息。任务的删除和任务列表查询同样也需要使用初始化成功

12、返回的Upload ID进行。Job操作Job操作包括Job初始化（4.4.1）、Job Output下载、Job列表查询以及Job状态查询。Job初始化成功以后会创建指定类型的Job，开始数据准备并返回Job ID。准备的过程中，用户可以使用Job状态查询（4.4.4）来查看Job的状态，待Job完成后使用Job Output下载（4.4.2）来获取所需的数据。正在进行的或近期完成的Job操作可以通过Job列表查询（4.4.3）来查看。后三个Job操作都需要指定初始化Job成功后返回的Job ID。对归档存储 API的接口调用是通过向归档存储 API的服务端地址发送HTTP请求，并按照接口说

13、明在请求中加入相应请求参数来完成的；根据请求的处理情况，系统会返回相应的处理结果。操作审计/API参考手册操作审计/API参考手册通信结构服务地址归档存储 API的服务接入地址为：公网： RegionName .内网： RegionName .其中， RegionName 取值为: cn-hangzhou、cn-qingdao、cn-beijing、cn-hongkong等。通信协议按照HTTP/1.1协议进行通信。字符编码请求及返回结果都使用UTF-8字符编码进行编码。通信请求请求方法HTTP RESTful方法发送请求，这种方式下请求的资源由URI指定。请求消息与格式Request-Lin

14、eCommon Request Headers Request Headers Request Body Request-LineCommon Request Headers Request Headers Request Body 请求行指定要执行的操作，格式参照 HTTP/1.1 协议 Request-Line。如：PUT /vaults/ VaultName HTTP/1.1PUT /vaults/ VaultName HTTP/1.1表示创建名称为 VaultName 的 Vault。请求行中的 URI 指定需要访问的资源，各接口指定资源的方式是将接口示例中的字段替换成相应的资源标识即

15、可。如 4.4.4 Job 任务状态查询的请求行：GET /vaults/ VaultId /jobs/ JobId HTTP/1.1GET /vaults/ VaultId /jobs/ JobId HTTP/1.1 VaultId 和 JobId 需要替换成实际相应的 Vault ID 和 Job ID。请求行中的URI还可以附带请求参数（Request Parameters），请求参数按照参数名称=参数值的格式以GET /vaults?limit=1&marker=C83DE8B245184E28AEED6CF1CED915F2 HTTP/1.1?符号与URI分隔并紧跟在URI后面，多个

16、请求参数以&符号连接。例如4.1.3 获取Vault列表，limit和GET /vaults?limit=1&marker=C83DE8B245184E28AEED6CF1CED915F2 HTTP/1.1公共请求头部是不论操作类型，每个请求消息都需要包含的一些头部参数（详细头部参数列表见2.4.1）。请求头部是一些操作特定的头部参数，比如4.2.1上传 Archive 操作，x-oas-archive-description是该操作的请求头部，指定Archive的描述信息。公共请求头部和请求头部的格式参照 HTTP/1.1协议各Headers。请求体则是请求需要提供的额外信息，如4.4.1初

17、始化Job任务，请求需要提供Type等其他信息来指定Job的类 型等。请求体的格式按照JSON的格式封装。本文档中的请求体示例为了便于用户查看，做了格式化处理，实际 是没有换行、缩进等处理。通信返回返回消息与格式Status-LineCommon Response Headers Response Headers Response Body Status-LineCommon Response Headers Response Headers Response Body 状态行格式参照HTTP/1.1协议Status-Line，返回的HTTP状态码2xx，代表调用成功；返回4xx或5xx的HT

18、TP状 态码代表调用失败。公共返回头部是无论调用是否成功，都会返回的头部参数（详细参数列表见2.4.2）。返回头部是不同类型的操作，可能会额外返回的头部参数。如4.1.1创建Vault操作返回头部包括Location和x- oas-vault-id，分别指定新创建Vault的URI和Vault ID。公共返回头部和返回头部的格式参照HTTP/1.1协议各Headers。返回体是操作返回的额外信息。如获取Vault列表中，紧跟在头部参数后面就是返回的Vault列表信息，返回体 按照JSON的格式封装。本文档的返回体示例为了便于用户查看，做了格式化处理，实际返回结果是没有进行换邮件推送/API参考

19、手册邮件推送/API参考手册行、缩进等处理的。成功结果ArchiveId: ArchiveId ,ArchiveId: ArchiveId ,/* 其他信息*/错误结果调用接口出错后，HTTP请求会返回一个4xx或5xx的HTTP状态码，且不会提供返回头部，但是在返回体中会提 供具体的错误代码及错误信息，调用方也可以根据附表来定位错误原因。在调用方找不到错误原 因，可以联系阿里云客服，并提供公共返回头部的x-oas-request-id和公共请求头部Host字段，以便我们尽快 帮您解决问题。code: UnsupportedOperation,code: UnsupportedOperatio

20、n,message: The specified action is not supported., type: client公共头部参数公共请求头部公共请求头部是指每个接口都需要使用到的头部参数。名称是否必须描述Authorization是请看签名形成机制Content-Length否（文件上传时必须）请求体的字节长度（不包括请求头）Date否这个头部参数在创建签名时使用，它是按照HTTP1.1协议Date头部的格式，如 Tue, 25Mar 2014 12:00:00 GMT。Host否指定要发送到的服务端地址如，RegionName.oas.aliyuncs.c om。x-oas-ver

21、sion是阿里云归档存储 API版本，如EclipseEclipse/最佳实践2014-01-01。Host: Date: Tue, 25 Mar 2014 12:00:00 GMTx-oas-archive-description: MyArchive Authorization: SignatureValuex-oas-version: 2014-01-01Host: Date: Tue, 25 Mar 2014 12:00:00 GMTx-oas-archive-description: MyArchive Authorization: SignatureValuex-oas-versi

22、on: 2014-01-01公共返回头部用户发送的每次接口调用请求，无论成功与否，系统都会返回一些固定的头部参数，其中最重要的是x-oas- request-id，它对各个请求都是唯一存在的。名称描述Content-Length返回体的字节长度（不包括返回头部，无返回体时无此头部）Date这个头部参数在 归档存储 响应时生成，它是按照HTTP1.1协议Date头部的格式，如Tue, 25 Mar2014 12:00:00 GMT。x-oas-request-id由阿里云归档存储生成唯一请求标识符，以便定位问题。x-oas-request-id: RequestId Date: Tue, 25

23、Mar 2014 12:00:00 GMTx-oas-request-id: RequestId Date: Tue, 25 Mar 2014 12:00:00 GMT校验码计算归档存储的校验码头部参数有两个：x-oas-content-etag和x-oas-tree-etag，其中x-oas-content-etag是针 对上传请求的请求体用md5计算得出的校验码，x-oas-tree-etag是针对上传请求的请求体用tree-hash算法计 算得出的校验码。为了确保上传数据的一致性，归档存储要求用户在上传文档时，无论是单个文档上传方式还是Multipart 上传方式，都必须包含上传数据的校

24、验码。归档存储收到数据以后，会计算校验码，并与用户提供的校 验码进行比对。如果不一致，会返回错误，该请求失败。同样用户在下载Archive时，归档存储也会返回相应的 校验码，供用户校验下载数据是否完整。本节2.5.1、2.5.2用来描述x-oas-content-etag和x-oas-tree-etag两种校验码的设置，2.5.3描述计算x-oas- tree-etag使用到的tree-hash算法，2.5.4描述下载数据时x-oas-tree-etag校验码的使用规则。x-oas-content-etag校验码x-oas-content-etag是通过计算待上传数据的MD5，并将该MD5值所

25、有小写字母转换为大写字母的结果。如 某个数据的MD5值是c011021548ef1855dd4dd15b8df79463，那么用户上传时的x-oas-content-etag校验 码为C011021548EF1855DD4DD15B8DF79463。有两个接口需要在请求头部中加入x-oas-content-etag请求头部，请分别参见4.2.1上传Archive接口与4.3.4Part上传接口。x-oas-tree-etag校验码x-oas-tree-etag是通过对上传或接收数据进行tree-hash算法（请参见2.5.3 tree-hash算法说明）计算出的校验码。有四个接口会使用到x-o

26、as-tree-etag参数，其中上传Archive（参见4.2.1）属于单文件上传接口，Part上传(参 见4.3.4)、Part合并(参见4.3.6)两个接口属于Multipart Upload上传接口，Job Output下载接口（4.4.2）属于下载类接口。下面分别描述单文档上传接口，Multipart Upload上传接口，Job Output下载三个场景对x-oas-tree-etag的用法。单文档上传方式用户在调用单文档上传接口之前需要对上传的文档进行tree-hash算法计算tree-etag校验码。如某个文档的tree-etag校验码为26093833F5438BD1F2F3

27、4C731A0F90DE，它便是这个单文档的x-oas-tree-etag。Multipart Upload上传方式Multipart Upload方式在Part 上传与Part 合并时都需要提供x-oas-tree-etag头部参数。Part上传时x-oas-tree-etag的计算方法是取该Part对应数据范围，做tree-hash算法计算得到的值。在所有Part上传完成后，用户需要发起Part合并请求，此时用户提交请求的x-oas-tree-etag头部可以通过对整 个上传数据做 tree-hash 算法计算得出，也可以复用已上传Part的x-oas-tree-etag校验值，省去tre

28、e-hash算法(参见2.5.3)中计算每个1MB数据的tree-etag值的步骤，直接把每个Part的x-oas-tree-etag值作为叶子节点，再按照tree-hash算法的步骤2、步骤3，最终得到整个Archive的tree-hash算法根值。示例：假设一个149903360字节的文件，用户以67108864为Part 大小上传，如下图所示：第一个段上传Archive的0-67108863字节，用tree-hash算法得到该段的x-oas-tree-etag校验码为： F60F379B33C234F69FA4F79254650F65第二个段上传Archive的67108864-1342

29、17727 字节，用tree-hash算法得到该段的x-oas-tree-etag校验码为：9D739013ABAE399B173B3C3415BDC69A第三个段上传Archive的134217728-149903359字节，用tree-hash算法得到该段的x-oas-tree-etag校验码为：F9C22EBEA613C03AF231187B85BD3D30合并时的x-oas-tree-etag校验码计算：按字节顺序排列已上传Part的x-oas-tree-etag校验码，作为tree-etag树的叶子节点： F60F379B33C234F69FA4F79254650F65 9D7390

30、13ABAE399B173B3C3415BDC69A F9C22EBEA613C03AF231187B85BD3D30按照tree-hash算法步骤2、步骤3计算出整个Archive的x-oas-tree-etag校验码： 93C106A8937AC115BD21A63FE9114B1。Job Output下载当用户调用Job Output下载接口时，如果用户遵守tree-hash树对齐规则（具体规则请参见2.5.4 下载数据时x- oas-tree-etag校验码的使用），归档存储会在返回头部中设置一个x-oas-tree-etag参数，该参数是归档存储 用tree-hash算法对返回数据计

31、算出的校验码。用户可以使用该校验码确认所接收到的数据与归档存储的数据是 否一致。tree-hash算法x-oas-tree-etag是通过对数据进行tree-hash算法计算得出的校验值，它的具体操作步骤如下：对数据的每个1MB块，计算它的md5值，并转换为大写。只有数据的最后一个块可以小于1MB。例 如，上传或者下载6.5MB的数据，则需要计算该数据的前6个1MB块的md5值，及最后的0.5MB数据md5。这7个md5值转大写后，就构成了tree-hash算法的叶子节点。构建父节点。依次连接两个连续子节点的值形成一个字符串，对这个字符串作md5计算，并且转大写。这个值 就是两个子节点的父节点

32、。最后如果只剩一个子节点，则它的父节点就是自身。重复步骤2，直到得到一个根节点为止。这个根节点就是待上传或者下载数据的x-oas-tree-etag值。 举例如下图所示：假设有份数据6.5MB，分别计算它的前6个1MB块的md5值，及最后一个0.5MB的md5值，按顺序 依次为：1ca30cd59f0b566f9ef3a8208679585e e07910a06a086c83ba41827aa00b26ed 76f556302c49d8f6503a7e60b2ed1d7d 7a3b8c43b0791ba6ce01f5696fd36f13 65487827c964185d8929fa30bf11

33、df182c7282bbca9abc9d446e02b8adee9563 46a5e231e4581f5defd12e8688da6377 转大写后的结果为：H节点值1CA30CD59F0B566F9EF3A8208679585E I节点值E07910A06A086C83BA41827AA00B26ED J节点值76F556302C49D8F6503A7E60B2ED1D7D K节点值7A3B8C43B0791BA6CE01F5696FD36F13 L节点值65487827C964185D8929FA30BF11DF18 N节点值46A5E231E4581F5DEFD12E8688DA6377

34、构建父节点。H, I的父节点D的值：85786098CA1FFDE6E267FA131DE97BCE。首先计算节点D的值，连接H和I的值形成一个字符串85786098ca1ffde6e267fa131de97bceH, I的父节点D的值：85786098CA1FFDE6E267FA131DE97BCE。依此类推，两两连接，得到J,J, K的父节点E的值：B15B5E7BDDB12E28B1AF9711591B260B， L, M的父节点F的值：6CE4D37E18F3642B1E9D1CF2D2532D86。最后剩下的单个节点N， 父节点G和N相同：46A5E231E4581F5DEFD12E

35、8688DA6377。D, E的父节点B的值：6C9924508699E38F6F898ECCE4F64F9B，F, G的父节点C的值：687DC906A777E986DD792FD469A3CC65。将D、E、F、GD, E的父节点B的值：6C9924508699E38F6F898ECCE4F64F9B，F, G的父节点C的值：687DC906A777E986DD792FD469A3CC65。将B,CaA的值：26093833F5438BD1F2F34C731A0F90DE加密服务/使用手册加密服务/使用手册通过步骤2，最终计算得到tree-hash树根节点的值26093833F5438BD

36、1F2F34C731A0F90DE，这 个值就是待上传或者下载数据的x-oas-tree-etag值。下载时x-oas-tree-etag校验码的使用当用户创建Job取回Archive时，可以选择要取回的Archive范围。同样，当用户下载这个job时，也可以选择要 下载的Job范围。用户在下载Job能否得到归档存储服务端返回x-oas-tree-etag校验码，取决于两个范围（用 户创建Job指定的Archive范围与下载Job时指定的Job范围）是否遵守了兆字节对齐、tree-hash树对齐。所谓 兆字节对齐与tree-hash树对齐的定义如下：兆字节对齐，是指Range startPos

37、, EndPos是以兆（1024*1024）字节对齐，其中startPos可被1MB整除；EndPos加1可被1MB整除，或者等于Archive的大小。tree-hash树对齐，是指在范围startPos, EndPos 用tree-hash算法计算出来的根节点，会存在于整个Archive的tree-etag树中。Tree-hash树对齐说明假设整个Archive大小为n字节，0ABn-1A, B要tree-hash树对齐，首要条件是A与B+1都能够被(1024*1024)P, Q分别为A与B+1整除1MB后的值，即AB可以用P*1024*1024,Q*1024*1024-1表示。为便于阅读，

38、以下用P, Q)来表示P, Q-1。A, B满足tree-hash树对齐，需要P, Q)符合以下特征：如果P0Q2k或n，k00klog2(n); 如果P为奇数，则只有QP+1时，PQtree-hash树对齐；如果P为偶数，k定义为以P开始的能够tree-hash树对齐的范围个数，其中k的计算方式为：假设T=P，将T做循环位右移运算，直到T模2不等于0，或者T等于0。对于每个i，如果(0 = i = k)且P+ 2i n，则P, P+2i)是以tree-hash树对齐的范围。为简化用户使用tree-hash树对齐，建议用户将数据以2N MB为range大小进行Job创建或者下载（N为大于0的整

39、数）。如下图所示：以下案例描述了在下载档案数据时，会在哪些情况下收到x-oas-tree-etag头部：补丁管理/补丁列表补丁管理/补丁列表如果在创建 Job请求中未指定要取回的范围，并且在Job下载请求中下载整个档案。如果在创建 Job请求中未指定要取回的范围，并且在Job下载请求中下载整个档案。如果在创建Job请求中未指定要取回的范围，并且在Job下载请求中指定要下载的范围以tree-hash树对齐。 如果在创建Job请求中指定要取回的范围以tree-hash树对齐，并且在Job下载请求中下载整个Job。如果在创建Job请求中指定要取回的范围以tree-hash树对齐，并且在Job下载请求

40、中指定要下载的范围以tree-hash树对齐。以下图举例说明：当用户提交对整个Archive的Job，在下载整个Job时，遵守了tree-hash树对齐，则归档存储会在响 应头部的x-oas-tree-etag参数中返回整个Archive的tree-etag值。如果用户提交整个Archive的Job，但只下载Data-1.1的数据，则归档存储不会返回tree-etag值。如果用户提交整Archive的Job，但只下载Data-2.1的数据，下载请求的响应头部中归档存储会返回tree-etag树的F节点的值。如果用户提交针对Data-1的Job，且下载整个Job遵守了tree-hash树对齐，下

41、载请求的响应头部中 归档存储会返回tree-hash树中的B节点值。如果用户提交针对Data-1的Job，且只下载Data-1.1范围的数据，则归档存储不会返回x-oas-tree- etag参数。如果用户提交针对Data-2的Job，且下载Data-2.2范围的数据，则归档存储会在响应头部参数x-oas- tree-etag中返回tree-hash树中N节点的值。如果用户提交Data-1.1范围数据的Job，则针对该Job的任何下载范围，归档存储都不会返回x-oas- tree-etag参数。用户签名验证（Authentication）归档存储通过使用AccessKeyID/AccessKe

42、ySecret对称加密的方法来验证某个请求的发送者身份。是用户用于加密签名字符串和归档存储用来验证签名字符串的 密钥，请勿将其泄露给第三方。每个AccessKey对（AccessKeyID和AccessKeySecret）有两种状态，分别为active和inactive。active表明用户可以用此AccessKey对签名验证请求inactive表明用户暂停此AccessKey对签名验证的功能当用户向归档存储发送请求时，需要首先将发送的请求按照归档存储指定的格式生成签名字符串；然后使用AccessKeyID找到对应 的AccessKeySecret，以同样的方法提取签名字符串和验证码，如果计算

43、出来的验证码和提供的一样即认为该 请求是有效的；否则，归档存储将拒绝处理这次请求，并返回HTTP403错误。用户签名计算方法用户需要在HTTP请求中增加Authorization（授权）的HTTP头部字段来包含Signature（签名）信息，表明这 个消息已被授权。Authorization: OAS + Access Key Id + : + Signature Signature = base64(hmac-sha1(VERB + n+ DATE + n+ CanonicalizedOASHeaders+ CanonicalizedResource)AuthorizationAuthori

44、zation: OAS + Access Key Id + : + Signature Signature = base64(hmac-sha1(VERB + n+ DATE + n+ CanonicalizedOASHeaders+ CanonicalizedResource)VERB 表 示 HTTP 方 法 ， 如 GET/POST DATE表示此次操作的时间，必须为HTTP/1.1中支持的GMT格式表示所有前缀为x-oas-的HTTPHeader CanonicalizedResource表示用户想要访问的归档存储资源，即URI其中，DATE和CanonicalizedResource

45、不能为空；如果请求中的DATE时间和归档存储的服务器时间差正负 15分钟以上，归档存储将拒绝该请求，并返回HTTP403错误。构建CanonicalizedOASHeaders的方法所有以x-oas-为前缀的HTTP Header被称为CanonicalizedOASHeaders，它的构建方法如下：将所有以x-oas-为前缀的HTTP请求头的名字转换成小写字母。如X-OASPart-Size: 67108864转换成x-oas-part-size: 67108864。将上一步得到的所有HTTP请求头按照字典序进行升序排列。删除请求头和内容之间分隔符两端出现的任何空格。如x-oas-part-

46、size: 67108864转换成x-oas- part-size:67108864。将所有的头和内容用n分隔符分隔拼成最后的CanonicalizedOASHeader。构建CanonicalizedResource的方法用户发送请求中想访问的归档存储目标资源被称为CanonicalizedResource。它的构建方法如下： 将CanonicalizedResource置成空字符串（）。放入要访问的归档存储资源，如：/vaults/ VaultId 。如果请求的资源包括子资源（sub-resource），将所有的子资源按照字典序，从小到大排列，以 字符串尾添加?和子资源字符串。如： /va

47、ults/ VaultId /multipart-uploads。如果请求含参数，将参数及值按照字典序，从小到大排列，以&为分隔符，添加到CanonicalizedResource中。如： /vaults/ VaultId/multipartuploads?limit=1&marker=30DF64484BD34B4C44BB261A02DF89BA。 参数值为空的时候，请不要传递此参数。如marker为空串（）时，参数列表中不要包含该参数。用户签名示例Access Key ID：ckdwpp7o2l2rhxf3d5j7dzzmGET /vaults/ VaultId /multipart-u

48、ploads HTTP/1.1 Date: Wed, 16 Apr 2014 05:51:14 GMTAccess Key Secret：gUWY5b687iv0d+LJLHRJW1PzhZY= 待签名内容如下：GET /vaults/ VaultId /multipart-uploads HTTP/1.1 Date: Wed, 16 Apr 2014 05:51:14 GMTHost: Host: import base64 import hmac import shah = hmac.new(gUWY5b687iv0d+LJLHRJW1PzhZY=,GETnWed,16Apr201405:

49、51:14GMTn/vaults/30DF64484BD34B4C44BB261A02DF89BA/multipart- uploads,sha) base64.encodestring(h.digest().strip()GET /vaults/30DF64484BD34B4C44BB261A02DF89BA/multipart-uploads HTTP/1.1 Host: GET /vaults/30DF64484BD34B4C44BB261A02DF89BA/multipart-uploads HTTP/1.1 Host: Date: Wed, 16 Apr 2014 05:51:14

50、GMTAuthorization: OAS ckdwpp7o2l2rhxf3d5j7dzzm:dZpCvvKgxiFw6wvMHHj5g3W6STM=在计算签名的时候请遵循如下规则：用来签名的字符串必须为UTF-8格式。含有中文字符的签名字符串必须先进行UTF-8编码，再与Access Key Secret计算最终签名。签名的方法用RFC 2104中定义的HMAC-SHA1方法，其中Key为Access Key Secret。在所有非HTTP标准定义的Header中，只有以x-oas-开头的Header，需要加入签名字符串；其他 非HTTP标准Header将被归档存储忽略。以x-oas-开头的

51、Header在签名验证前需要符合以下规范：Header的名字需要变成小写。Header按字典序自小到大排序。分割HeaderName和Value的冒号前后不能有空格。每个Header之后都有一个换行符n。如果没有符合要求的Header，CanonicalizedOASHeaders应置为空。异常说明传入的Access Key ID不存在或inactive，返回 403 Forbidden。错误码：InvalidAccessKeyId。MongoDBMongoDB/使用手册Authorization字段值格式不对，返回 400 Bad Request。错误码：InvalidArgument。没有

52、传入Date或者格式不正确，返回 403 Forbidden错误。错误码：AccessDenied。传入的Date必须在归档存储的服务器当前时间前后15分钟以内，否则返回 403 Forbidden，错误码：RequestTimeTooSkewed。Vault操作创建Vault（PUT）描述此操作能够用指定名称创建一个新的 Vault，该名称在同一账户的同一Region下是唯一的。同一个账号在同一Region下最多只能拥有10个Vault。当用户提交创建Vault请求且创建成功时，会返回该Vault对应的Vault ID。创建 Vault 需要遵守如下规范：只能包含小写字母、数字、下划线（_）

53、、短横线（-）。必须以小写字母或者数字开头和结尾。3-63发送 HTTP PUT 请求，就可以完成 Vault 的创建。请求参数无请求头部无，其他公共请求头部参见2.4.1请求体无返回头部名称描述Location该Vault对应的URIx-oas-vault-id该Vault的ID弹性伸缩/计量计费弹性伸缩/计量计费其他公共返回头部参见2.4.2返回体无示例PUT /vaults/VaultName HTTP/1.1 Host: Date: Tue, 25 Mar 2014 12:00:00 GMTx-oas-version: 2014-01-01 PUT /vaults/VaultName

54、HTTP/1.1 Host: Date: Tue, 25 Mar 2014 12:00:00 GMTx-oas-version: 2014-01-01 Authorization: SignatureValue返回示例HTTP/1.1 201 CreatedHTTP/1.1 201 Createdx-oas-request-id: RequestIdDate: Tue, 25 Mar 2014 12:00:00 GMTLocation: /vaults/VaultId x-oas-vault-id: VaultId删除Vault（DELETE）描述此操作是为删除一个空的Vault。空的Vaul

55、t是指：VaultArchive 自最近一次检索结果生成的时间至今，该 Vault 没有新的文档写入请求参数无请求头部无，其他公共请求头部参见2.4.1请求体无返回头部无，其他公共返回头部参见2.4.2返回体无示例DELETE /vaults/VaultId HTTP/1.1 Host: Date: Tue, 25 Mar 2014 12:00:00 GMTx-oas-version: 2014-01-01 DELETE /vaults/VaultId HTTP/1.1 Host: Date: Tue, 25 Mar 2014 12:00:00 GMTx-oas-version: 2014-0

56、1-01 Authorization: SignatureValue返回示例HTTP/1.1 204 No ContentHTTP/1.1 204 No Contentx-oas-request-id: RequestIdDate: Tue, 25 Mar 2014 12:00:00 GMT获取Vault信息（GET）描述此操作返回的Vault信息包括：VaultName，Vault创建时间，Archive数，Archive总大小等。归档存储每天定 时扫描生成一次Vault索引缓存。如果用户添加或者删除一个Archive之后，立即发起获取Vault信息的请求，则 该请求的响应很可能不会反映这次

57、改变。请求参数无请求头部无，其他公共请求头部参见2.4.1请求体无返回头部视频直播/使用手册视频直播/使用手册无，其他公共返回头部参见2.4.2返回体CreationDateVault 的创建时间LastInventoryDate归档存储对该Vault最近的一次索引缓存时间NumberOfArchives最近一次检索时Vault的Archive数SizeInBytes最近一次检索时Vault的Archive大小总和Vault的IDVaultNameVault的名称示例GET /vaults/VaultId HTTP/1.1Host: Date: Tue, 25 Mar 2014 12:02:0

58、0 GMTGET /vaults/VaultId HTTP/1.1Host: Date: Tue, 25 Mar 2014 12:02:00 GMTx-oas-version: 2014-01-01 Authorization: SignatureValue返回示例HTTP/1.1 200 OKHTTP/1.1 200 OKx-oas-request-id: RequestIdDate: Tue, 25 Mar 2012 12:02:00 GMTContent-Type: application/json Content-Length: 260CreationDate: Tue, 25 Mar

59、 2014 12:00:00 GMT,LastInventoryDate: Tue, 25 Mar 2014 12:00:00 GMT,NumberOfArchives: 192,SizeInBytes: 78088912,VaultId: 79D2D8F33B7C287037286185863B6823,VaultName: myvaultVaultName: myvault获取Vault列表（GET）描述此操作会列出该用户拥有的全部Vault信息。默认情况下，此操作返回的列表中最多会有10个Vault，列表按Vault ID升序排列。用户应始终检查返回体中的Marker为（空串），则表示列

60、表已 全部获取完成。用户还可以通过设置limit参数来限制每次请求返回的Vault数量，但是limit不能超过10，如果 超过10，按10处理。请求参数无请求头部无，其他公共请求头部参见2.4.1请求体无返回头部无，其他公共返回头部参见2.4.2返回体Marker下一次列表请求的起始标记，空串（）表示无后续的列表VaultList CreationDateVault的创建时间LastInventoryDate归档存储对该Vault最近的一次检索缓存时间NumberOfArchives最近一次检索时Vault的Archive数SizeInBytes最近一次检索时Vault的Archive大小总和