API调用方式

对归档存储 API的接口调用是通过向归档存储 API的服务端地址发送HTTP请求，并按照接口说明在请求中加入相应请求参数来完成的；根据请求的处理情况，系统会返回相应的处理结果。

通信结构



服务地址


归档存储 API的服务接入地址为：
公网：[ RegionName ].oas.aliyuncs.com
内网：[ RegionName ].oas-internal.aliyuncs.com
其中，[ RegionName ]取值为: cn-hangzhou、cn-qingdao、cn-beijing、cn-hongkong等。

通信协议


按照HTTP/1.1协议进行通信。

字符编码


请求及返回结果都使用UTF-8字符编码进行编码。

通信请求



请求方法


HTTP RESTful方法发送请求，这种方式下请求的资源由URI指定。

请求消息与格式


每个请求消息都必须包含请求行（Request-Line）和公共请求头部（Common Request Headers），部分操作需要提供额外的请求头部（Request Headers）和请求体（Request Body）。格式如下： Request-Line
Common Request Headers
[ Request Headers ]
[ Request Body ]

请求行指定要执行的操作，格式参照 HTTP/1.1 协议 Request-Line。如： PUT /vaults/[ VaultName ] HTTP/1.1

表示创建名称为 VaultName 的 Vault。
请求行中的 URI 指定需要访问的资源，各接口指定资源的方式是将接口示例中的字段替换成相应的资源标识即可。如 4.4.4 Job 任务状态查询的请求行： GET /vaults/[ VaultId ]/jobs/[ JobId ] HTTP/1.1

[ VaultId ] 和 [ JobId ] 需要替换成实际相应的 Vault ID 和 Job ID。
请求行中的URI还可以附带请求参数（Request Parameters），请求参数按照“参数名称=参数值”的格式以“?”符号与URI分隔并紧跟在URI后面，多个请求参数以“&”符号连接。例如4.1.3 获取Vault列表，limit和marker是该操作可以附加的请求参数，组成的请求行可能如下所示： 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初始化Job任务，请求需要提供Type等其他信息来指定Job的类型等。请求体的格式按照JSON的格式封装。本文档中的请求体示例为了便于用户查看，做了格式化处理，实际是没有换行、缩进等处理。

通信返回



返回消息与格式


调用 API 服务后返回数据采用统一格式，包括状态行（Status-Line）、公共返回头部（Common Response Headers），有些操作会提供额外的返回头部（ResponseHeaders）和返回体（Response Body）。格式如下： Status-Line
Common Response Headers
[ Response Headers ]
[ Response Body ]

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

成功结果


JSON示例： {
    "ArchiveId":"[ ArchiveId ]",
    /* 其他信息*/
}


错误结果


调用接口出错后，HTTP请求会返回一个4xx或5xx的HTTP状态码，且不会提供返回头部，但是在返回体中会提供具体的错误代码及错误信息，调用方也可以根据附表<错误代码表>来定位错误原因。在调用方找不到错误原因，可以联系阿里云客服，并提供公共返回头部的x-oas-request-id和公共请求头部Host字段，以便我们尽快帮您解决问题。
JSON示例： {
    "code": "UnsupportedOperation",
    "message": "The specified action is not supported.",
    "type": "client"
}


公共头部参数



公共请求头部


公共请求头部是指每个接口都需要使用到的头部参数。

名称	是否必须	描述
Authorization	是	请看签名形成机制
Content-Length	否（文件上传时必须）	请求体的字节长度（不包括请求头）
Date	否	这个头部参数在创建签名时使用，它是按照HTTP1.1协议Date头部的格式，如 Tue, 25 Mar 2014 12:00:00 GMT。
Host	否	指定要发送到的服务端地址如，RegionName.oas.aliyuncs.com。
x-oas-version	是	阿里云归档存储 API版本，如2014-01-01。

示例： Host: cn-hangzhou.oas.aliyuncs.com
Date: Tue, 25 Mar 2014 12:00:00 GMT
x-oas-archive-description: MyArchive
Authorization: SignatureValue
x-oas-version: 2014-01-01


公共返回头部


用户发送的每次接口调用请求，无论成功与否，系统都会返回一些固定的头部参数，其中最重要的是x-oas-request-id，它对各个请求都是唯一存在的。

名称	描述
Content-Length	返回体的字节长度（不包括返回头部，无返回体时无此头部）
Date	这个头部参数在 归档存储 响应时生成，它是按照HTTP1.1协议Date头部的格式，如Tue, 25 Mar 2014 12:00:00 GMT。
x-oas-request-id	由阿里云归档存储生成唯一请求标识符，以便定位问题。

示例： x-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 Upload上传方式，都必须包含上传数据的校验码。归档存储收到数据以后，会计算校验码，并与用户提供的校验码进行比对。如果不一致，会返回错误，该请求失败。同样用户在下载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值所有小写字母转换为大写字母的结果。如某个数据的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-oas-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校验码为26093833F5438BD1F2F34C731A0F90DE，它便是这个单文档的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校验值，省去tree-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-134217727 字节，用tree-hash算法得到该段的x-oas-tree-etag校验码为：
9D739013ABAE399B173B3C3415BDC69A
第三个段上传Archive的134217728-149903359字节，用tree-hash算法得到该段的x-oas-tree-etag校验码为：
F9C22EBEA613C03AF231187B85BD3D30
合并时的x-oas-tree-etag校验码计算：

1. 
   按字节顺序排列已上传Part的x-oas-tree-etag校验码，作为tree-etag树的叶子节点：
   F60F379B33C234F69FA4F79254650F65
   9D739013ABAE399B173B3C3415BDC69A
   F9C22EBEA613C03AF231187B85BD3D30
2. 
   按照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算法对返回数据计算出的校验码。用户可以使用该校验码确认所接收到的数据与归档存储的数据是否一致。

tree-hash算法


x-oas-tree-etag是通过对数据进行tree-hash算法计算得出的校验值，它的具体操作步骤如下：

1. 
   对数据的每个1MB块，计算它的md5值，并转换为大写。只有数据的最后一个块可以小于1MB。例如，上传或者下载6.5MB的数据，则需要计算该数据的前6个1MB块的md5值，及最后的0.5MB数据md5。这7个md5值转大写后，就构成了tree-hash算法的叶子节点。
2. 
   构建父节点。
   a. 依次连接两个连续子节点的值形成一个字符串，对这个字符串作md5计算，并且转大写。这个值就是两个子节点的父节点。
   b. 最后如果只剩一个子节点，则它的父节点就是自身。
3. 
   重复步骤2，直到得到一个根节点为止。这个根节点就是待上传或者下载数据的x-oas-tree-etag值。

举例如下图所示：

1. 
   假设有份数据6.5MB，分别计算它的前6个1MB块的md5值，及最后一个0.5MB的md5值，按顺序依次为：
   1ca30cd59f0b566f9ef3a8208679585e
   e07910a06a086c83ba41827aa00b26ed
   76f556302c49d8f6503a7e60b2ed1d7d
   7a3b8c43b0791ba6ce01f5696fd36f13
   65487827c964185d8929fa30bf11df18
   2c7282bbca9abc9d446e02b8adee9563
   46a5e231e4581f5defd12e8688da6377
   转大写后的结果为：
   H节点值1CA30CD59F0B566F9EF3A8208679585E
   I节点值E07910A06A086C83BA41827AA00B26ED
   J节点值76F556302C49D8F6503A7E60B2ED1D7D
   K节点值7A3B8C43B0791BA6CE01F5696FD36F13
   L节点值65487827C964185D8929FA30BF11DF18
   M节点值2C7282BBCA9ABC9D446E02B8ADEE9563
   N节点值46A5E231E4581F5DEFD12E8688DA6377
2. 
   构建父节点。
   a. 首先计算节点D的值，连接H和I的值形成一个字符串“1CA30CD59F0B566F9EF3A8208679585EE07910A06A086C83BA41827AA00B26ED”，对该字符串做md5计算得到 85786098ca1ffde6e267fa131de97bce， 将这个结果转大写就可以得到H, I的父节点D的值：85786098CA1FFDE6E267FA131DE97BCE。

依此类推，两两连接，得到 J, K的父节点E的值：B15B5E7BDDB12E28B1AF9711591B260B，
L, M的父节点F的值：6CE4D37E18F3642B1E9D1CF2D2532D86。
最后剩下的单个节点N， 父节点G和N相同：46A5E231E4581F5DEFD12E8688DA6377。

b. 将D、E、F、G 作为子节点，重复操作 a，计算相应的父节点： D, E的父节点B的值：6C9924508699E38F6F898ECCE4F64F9B，
F, G的父节点C的值：687DC906A777E986DD792FD469A3CC65。

c. 将B, C作为子节点，按照 a 的方法，算出最终根节点A的值：26093833F5438BD1F2F34C731A0F90DE
通过步骤2，最终计算得到tree-hash树根节点的值26093833F5438BD1F2F34C731A0F90DE，这个值就是待上传或者下载数据的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树对齐的定义如下：

1. 
   兆字节对齐，是指Range [startPos, EndPos]是以兆（1024*1024）字节对齐，其中startPos可被1MB整除；EndPos加1可被1MB整除，或者等于Archive的大小。
2. 
   tree-hash树对齐，是指在范围[startPos, EndPos] 用tree-hash算法计算出来的根节点，会存在于整个Archive的tree-etag树中。

Tree-hash树对齐说明


假设整个Archive大小为n字节，0 <= A < B <= n-1, 如果[A, B]要tree-hash树对齐，首要条件是A与B+1都能够被(1024*1024) 整除。设P, Q分别为A与B+1整除1MB后的值，即[A, B]可以用[P*1024*1024, Q*1024*1024-1]表示。为便于阅读，以下用[P, Q)来表示[P, Q-1]。
[A, B]满足tree-hash树对齐，需要[P, Q)符合以下特征：

1. 
   如果P = 0， 则 Q = 2[backcolor=transparent]k或n，其中 k 是大于0的正整数，且满足 0 < k <= log[backcolor=transparent]2(n);
2. 
   如果P为奇数，则只有Q = P+1时，[P, Q) 能够满足tree-hash树对齐；
3. 
   如果P为偶数，k定义为以P开始的能够tree-hash树对齐的范围个数，其中k的计算方式为：假设T=P，将T做循环位右移运算，直到T模2不等于0，或者T等于0。对于每个i，如果(0 <= i <= k)且P + 2[backcolor=transparent]i < n，则[P, P+2[backcolor=transparent]i)是以tree-hash树对齐的范围。

为简化用户使用tree-hash树对齐，建议用户将数据以2 [backcolor=transparent]N MB为range大小进行Job创建或者下载（N为大于0的整数）。如下图所示：

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

以下图举例说明：

1. 
   当用户提交对整个Archive的Job，在下载整个Job时，遵守了tree-hash树对齐，则归档存储会在响应头部的x-oas-tree-etag参数中返回整个Archive的tree-etag值。
2. 
   如果用户提交整个Archive的Job，但只下载Data-1.1的数据，则归档存储不会返回tree-etag值。
3. 
   如果用户提交整Archive的Job，但只下载Data-2.1的数据，下载请求的响应头部中归档存储会返回tree-etag树的F节点的值。
4. 
   如果用户提交针对Data-1的Job，且下载整个Job遵守了tree-hash树对齐，下载请求的响应头部中归档存储会返回tree-hash树中的B节点值。
5. 
   如果用户提交针对Data-1的Job，且只下载Data-1.1范围的数据，则归档存储不会返回x-oas-tree-etag参数。
6. 
   如果用户提交针对Data-2的Job，且下载Data-2.2范围的数据，则归档存储会在响应头部参数x-oas-tree-etag中返回tree-hash树中N节点的值。
7. 
   如果用户提交Data-1.1范围数据的Job，则针对该Job的任何下载范围，归档存储都不会返回x-oas-tree-etag参数。