# 恢复归档存储或深度归档存储对象-RestoreObject
#### 功能介绍
如果要获取归档存储或深度归档存储对象的内容，需要先将对象恢复，然后再执行下载数据的操作。对象恢复后，会产生一个标准存储类型的对象副本，也就是说会同时存在标准存储类型的对象副本和归档存储或深度归档存储类型的对象，在恢复对象的保存时间到期后标准存储类型的对象副本会自动删除。
了解更多恢复归档存储或深度归档存储对象相关信息，请参见[恢复归档或深度归档存储对象](https://support.huaweicloud.com/usermanual-obs/obs_03_0320.html)。
#### 多版本
默认情况下，恢复的是最新版本的对象。如果最新版本的对象是删除标记，则返回404。如果要恢复指定版本的对象，请求可携带versionId消息参数。
#### 接口约束
- 归档和深度归档对象恢复的**有效期时长上限为30天**。
- 归档存储或深度归档存储的对象**正在恢复**的过程中，不支持修改恢复方式，不允许暂停或删除恢复任务。
- 对象的恢复状态为**恢复中** 时，对象不能再次恢复，接口会报错409，请对象**恢复完成后**再进行恢复操作。
- **恢复中**的对象不能加入批量恢复文件中。
#### 授权信息
您必须是对象拥有者或拥有恢复对象的权限，才能调用本接口，建议使用IAM或桶策略进行授权。了解更多OBS授权方式请参见[OBS不同权限控制方式的区别](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)。
- 如果使用**IAM授权** ，那么请在"角色与策略授权"、"身份策略授权"两种IAM授权方式中选择一种，并配置相应权限：
- 如果使用**角色与策略授权** （旧版IAM，即IAM v3接口），需具备**obs:object:RestoreObject** 权限，授权操作请参见[创建IAM自定义策略](https://support.huaweicloud.com/usermanual-iam/iam_01_0605.html)。
- 如果使用**身份策略授权** （新版IAM，即IAM v5接口），如下表所示，需具备**obs:object:restoreObject** 权限，授权操作请参见[创建IAM自定义身份策略](https://support.huaweicloud.com/usermanual-iam5/iam_01_0917.html)。
| 授权项 Action | 访问级别 Access Level | 资源类型（\*为必须） Resource Type (\*: required) | [条件键](https://support.huaweicloud.com/api-obs/obs_04_0112.html#ZH-CN_TOPIC_0000002375307974__condition_table) Condition Key | [别名](https://support.huaweicloud.com/iam5_faq/iam_01_1103.html) Alias | 依赖的授权项 Dependencies |
|:---|:---|:---|:---|:---|:---|
| obs:object:restoreObject | Write | object \* | [g:EnterpriseProjectId](https://support.huaweicloud.com/usermanual-iam5/iam_01_0934.html#section2) | - | - |
| obs:object:restoreObject | Write | - | - obs:EpochTime - obs:SourceIp - obs:TlsVersion - obs:CustomDomain | - | - |
- 如果使用**桶策略** 进行授权，需具备**obs:object:RestoreObject** 权限，具体操作请参见[自定义创建桶策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0123.html)。
#### URI
POST /{*object_key*}
#### 调用方法
请参见[如何调用API](https://support.huaweicloud.com/api-obs/obs_04_0006.html)。调用前需要先[计算API签名](https://support.huaweicloud.com/api-obs/obs_04_0009.html)，并将签名添加到请求中。
您还可以使用[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/OBS/doc?api=RestoreObject)在线调试接口。
#### 请求消息样式
```
POST /ObjectName?restore&versionId=VersionID HTTP/1.1
Host: bucketname.obs.cn-north-4.myhuaweicloud.com
Date: date
Authorization: authorization string
Content-MD5: MD5
NumberOfDays
RetrievalOption
```
#### URI参数（URI Parameters）
| **参数名称** | **参数类型** | **是否必选** | **描述** |
|:---|:---|:---|:---|
| versionId | String | 否 | **参数解释：** 待恢复归档存储或深度归档存储对象的版本号。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无，如果不设置则默认指定最新版本的对象。 |
#### 请求头参数（Request headers）
该请求使用公共请求头，具体参见[表3](https://support.huaweicloud.com/api-obs/obs_04_0007.html#ZH-CN_TOPIC_0136436606__table25197309)。
#### 请求体参数（Request body）
表1请求体参数
| **元素名称** | **元素类型** | **是否必选** | **描述** |
|:---|:---|:---|:---|
| RestoreRequest | Container | 是 | **参数解释：** 恢复信息的容器。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 |
| Days | Integer | 是 | **参数解释：** 恢复对象后，会生成一个对象的标准存储副本，此参数指定恢复有效期，即标准存储副本的保存时间。 **约束限制：** 保存时间是从对象发起取回后的第一个 北京时间 08: 00 开始计算的。 以保存时间为一天为例，取回发起时间在 27号 08: 00 到 28号 08: 00 之间的取回，实际过期时间都是29号的 08: 00。 **取值范围：** \[1, 30\]，单位：天。 **默认取值：** 无 |
| RestoreJob | Container | 否 | **参数解释：** 恢复选项的容器。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 |
| Tier | String | 否 | **参数解释：** 恢复选项，用户可根据需求选择恢复选项，不同的恢复选项恢复耗时不同。 说明： 对于深度归档对象，大批量恢复建议使用标准恢复，且对象最终恢复时间受对象大小以及取回数据量的影响。 **取值范围：** - Expedited：表示快速恢复对象，归档存储恢复耗时1\~5 min，深度归档存储恢复约耗时3\~5 h。 - Standard：表示标准恢复对象，归档存储恢复耗时3\~5 h，深度归档存储恢复约耗时5\~12 h。 **默认取值：** Standard |
#### 响应消息样式
```
HTTP/1.1 status_code
Date: date
```
#### 响应头 (Response Headers)
该请求的响应消息使用公共响应头，具体请参考[表1](https://support.huaweicloud.com/api-obs/obs_04_0013.html#ZH-CN_TOPIC_0173612084__d0e686)。
#### 响应体 (Response Body)
该请求的响应消息中不带有响应元素。
#### 错误响应消息
表2对象存储访问服务错误码列表
| **错误码** | **描述** | **HTTP状态码** |
|:---|:---|:---|
| RestoreAlreadyInProgress | **参数解释：** 对象正在恢复，请求冲突。 ErrorMessage: Object restore is already in progress | 409 Conflict |
| ObjectHasAlreadyRestored | **参数解释：** 已经恢复的对象，禁止缩短恢复保存时间。 ErrorMessage:After restoring an archived object, you cannot shorten the restoration period of the archived object | 409 Conflict |
| MalformedXML | **参数解释：** Days字段不合法（不为整数）。 ErrorMessage: The XML you provided was not well-formed or did not validate against our published schema | 400 Bad Request |
| InvalidArgument | **参数解释：** Days字段取值超出范围（1\<=days\<=30)。 ErrorMessage: restoration days should be at least 1 and at most 30 | 400 Bad Request |
| MalformedXML | **参数解释：** Tier字段不合法。 ErrorMessage: The XML you provided was not well-formed or did not validate against our published schema | 400 Bad Request |
| InvalidObjectState | **参数解释：** 恢复的对象不是归档存储或深度归档存储对象。 ErrorMessage: Restore is not allowed, as object's storage class is not COLD or DEEP_ARCHIVE | 403 Forbidden |
#### 请求示例
```
POST /object?restore HTTP/1.1
Host: examplebucket.obs.cn-north-4.myhuaweicloud.com
Accept: */*
Date: Wed, 01 Jul 2015 04:39:46 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:kaEwOixnSVuS6If3Q0Lnd6kxm5A=
Content-Length: 183
2
Expedited
```
#### 响应示例
```
HTTP/1.1 202 Accepted
Server: OBS
x-obs-request-id: A2F500000163F374CCBB2063F834C6C4
x-obs-id-2: 32AAAUgAIAABAAAQAAEAABAAAQAAEAABCSLbWIs23RR95NVpkbWlJdlm8Dq+wQBw
Date: Wed, 01 Jul 2015 04:39:46 GMT
Content-Length: 0
```
#### 使用SDK调用接口
建议您使用OBS SDK调用接口。SDK对API进行了封装以简化您的开发工作，直接调用SDK接口函数即可访问OBS，无需手动计算签名。
| [Java](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0708.html) | [Python](https://support.huaweicloud.com/sdk-python-devg-obs/obs_22_0924.html) | [C](https://support.huaweicloud.com/sdk-c-devg-obs/obs_20_0503.html) | [Go](https://support.huaweicloud.com/sdk-go-devg-obs/obs_33_0517.html) | [BrowserJS](https://support.huaweicloud.com/sdk-browserjs-devg-obs/obs_24_0610.html) | [.NET](https://support.huaweicloud.com/sdk-dotnet-devg-obs/obs_25_0509.html) | [Android](https://support.huaweicloud.com/sdk-android-devg-obs/obs_26_0508.html) | [iOS](https://support.huaweicloud.com/sdk-ios-devg-obs/obs_27_0507.html) | [PHP](https://support.huaweicloud.com/sdk-php-devg-obs/obs_28_0509.html) | [Node.js](https://support.huaweicloud.com/sdk-nodejs-devg-obs/obs_29_0509.html) |
|---|---|---|---|---|---|---|---|---|---|
#### 相关文档
- 使用obsutil恢复对象，请参见[恢复归档存储深度归档存储对象](https://support.huaweicloud.com/utiltg-obs/obs_11_0016.html)。
- 使用OBS Browser+恢复对象，请参见[恢复文件或文件夹](https://support.huaweicloud.com/browsertg-obs/obs_03_1068.html)。
- 了解更多恢复归档存储或深度归档存储对象相关信息，请参见[恢复归档或深度归档存储对象](https://support.huaweicloud.com/usermanual-obs/obs_03_0320.html)。
- API操作涉及的计费项参见[计费项](https://support.huaweicloud.com/price-obs/obs_42_0002.html)。