Overview
This API is used to initiate tenant restore from a global view. It restores an offline tenant parsed by the Resolve Global Backup Information API to a target cluster currently managed by OCP, without requiring the source cluster to be managed by OCP.
Compared with the existing "Initiate tenant/database/table restore" API (POST /api/v2/ob/clusters/{id}/backup/restore), this API does not require specifying the source cluster ID in its request path, making it suitable for global offline restore scenarios such as cross-OCP restores.
The API model includes both ONLINE and OFFLINE branches. In global offline restore scenarios, backupTenantStatus is fixed as OFFLINE, and restoreOfflineTenantRequiredParam must be specified.
API details
Constraints
- The caller must pass the authentication for the OCP application service.
- The caller must have the Update permission on the target cluster and the Read permission on the selected resolution host.
Request path
POST /api/v2/backup/restore
Request parameters
Data structure of RestoreTenantParam
Parameter |
Type |
Required |
Example value |
Description |
|---|---|---|---|---|
| backupTenantStatus | String | Yes | OFFLINE | Backup tenant status. Valid values:ONLINEorOFFLINE; The global offline restore parameter is fixed atOFFLINE. |
| restoreOnlineTenantRequiredParam | Object | No | - | Online tenant recovery parameters. Omitted for global offline recovery. |
| restoreOfflineTenantRequiredParam | Object | Condition Required | - | backupTenantStatusisOFFLINERequired. |
Data structure of RestoreOfflineTenantRequiredParam
Parameter |
Type |
Required |
Example value |
Description |
|---|---|---|---|---|
| backupMode | String | Yes | PHYSICAL_BACKUP | Backup mode. Valid values:PHYSICAL_BACKUPorLOGICAL_BACKUP, you should use the value from the resolution result. |
| backupClusterName | String | Yes | prod_cluster | Backup source cluster name, obtained from the resolution result.clusterName. |
| backupObClusterId | Long | Physical Backup Required | 1001 | The cluster ID of the source cluster in OceanBase Database, which is obtained from the parsed result.obClusterId. |
| backupTenantName | String | Yes | tenant_a | Backup source tenant name, obtained from the resolution result.tenantName. |
| backupObTenantId | Long | No | 1002 | The tenant ID of the backup source tenant in OceanBase Database, obtained from the parsed result.obTenantId. Recommended. |
| restoreClusterId | Long | Yes | 2001 | The cluster ID of the target cluster in the current OCP. Note that this field is not the same as the source cluster's cluster ID.obClusterId. |
| obBackupStorageBaseInfo | Object | Yes | - | The data backup storage information should be consistent with the storage information used by the parsing API. For the data structure, see Data structure of ObBackupStorageBaseInfo in Parse global backup information. |
| hostIdList | LongArray | Required for global restore | [3001] | The list of host IDs parsed from the data backup should match the hosts used by the parsing API. |
| logStorageMode | String | No | SAME_AS_DATA | Log backup storage mode. The meaning and parsing API are the same as those of the corresponding parameter in the analysis API.INDEPENDENTApplicable only toPHYSICAL_BACKUP. It is recommended to pass it explicitly. |
| logBackupStorageBaseInfo | Object | Condition Required | - | logStorageModeisINDEPENDENTRequired. |
| logHostIdList | LongArray | No | [3002] | List of host IDs for independent log backup parsing. When omitted or set to an empty array, the system ID is used by default.hostIdList. |
| restoreEndTime | DateTime | Yes | 2026-09-09T09:30:00+08:00 | The restore time must fall within the actual recoverable interval of the parsing result. |
| restoreTenantInfoParam | Object | Yes | - | Target tenant definition. For details, see Data structure of RestoreTenantInfoParam. |
| storageId | Long | No | 10 | The ID of the backup storage configuration already existing in OCP. The application service should still pass in the complete storage information when making the call. |
| addSource | Boolean | No | false | Whether to use the specified loaded restore source. The default value for global offline restore isfalse. |
Data structure of RestoreTenantInfoParam
Parameter |
Type |
Required |
Example value |
Description |
|---|---|---|---|---|
| id | Long | No | - | Target tenant ID. Omitted for full-tenant offline restore. |
| name | String | Yes | tenant_a_restore | The name of the target tenant must be unique and cannot duplicate any name of an existing tenant in the target cluster. It must start with a letter, can only contain letters, digits, and underscores, and be 2 to 64 characters long. |
| primaryZone | String | No | zone1 | The primary zone of the target tenant. |
| zones | Array | Yes | - | The zone and resource pool configuration for the target tenant. At least one of these parameters must be specified. |
| ├─ name | String | Yes | zone1 | The name of the zone. |
| ├─ replicaType | String | Yes | FULL | Replica type. Valid values:FULL、LOGONLY、READONLYandCOLUMNSTORE. |
| ├─ resourcePool | Object | Yes | - | Resource pool configuration. |
| ├─ resourcePool.unitSpecName | String | Yes | S1 | The name of the unit configuration already existing in the target cluster. |
| ├─ resourcePool.unitCount | Long | Yes | 1 | Number of units. |
| restoreMethod | String | No | full | The recovery method. Valid values:fullorquickDefault value:full;quickThe OceanBase version must be V4.3.3 or later. |
| enableDynamicPartition | Boolean | No | true | Whether to enable dynamic partitioning. Default value:true; This capability requires OceanBase Database V4.3.5.2 or later. |
Parsing results and restore parameter mapping
/backup/infoResponse parameters |
/backup/restoreRequest Fields |
Description |
|---|---|---|
contents[].clusterName |
backupClusterName |
The name of the source cluster. |
contents[].obClusterId |
backupObClusterId |
The ID of the source OceanBase cluster. This parameter is required for physical backup and restore. |
contents[].tenantBackupInfos[].tenantName |
backupTenantName |
Source tenant name. |
contents[].tenantBackupInfos[].obTenantId |
backupObTenantId |
The tenant ID of the source tenant in OceanBase Database. |
...obRecoverableSectionItems[].backupMode |
backupMode |
SelectRECOVERABLEThe backup mode corresponding to the node. |
...realRecoverableTimeInterval |
restoreEndTime |
InstartTimeandendTimeto select the recovery time. |
Parse the request forobBackupStorageBaseInfo |
fields with the same name | The same data backup storage information is used for both calls. |
Parse the request forhostIdList |
fields with the same name | The current OCP host that can access the backup storage is used for both calls. |
| Parse log storage fields in the request | fields with the same name | Maintain consistent configurations when using standalone log storage. |
Notice
Do not confuse the clusterId in the parsing result with restoreClusterId. The clusterId for cross-OCP offline backup is usually empty; restoreClusterId should be filled with the ID of the target cluster in the current OCP.
Response parameters
Basic Data Structures
Parameter |
Type |
Description |
|---|---|---|
| data | Object | The result of the restore task submission. For more information, see Data structure of BackupCommonResponse. |
| successful | Boolean | Whether the request is successful. |
| timestamp | DateTime | The timestamp when the server completed the request. |
| duration | Long | The time taken by the server to process the request, in milliseconds. |
| status | Integer | Status codes that comply with the HTTP Status specification. |
| traceId | String | The trace ID of the request, used for troubleshooting. |
| server | String | The address of the OCP node that responded to the request. |
Data structure of BackupCommonResponse
Parameter |
Type |
Description |
|---|---|---|
| obBackupTaskType | String | Task type. This parameter is returned when the API returns a successful result.RESTORE. |
| backupObjectOpsResultList | Array | Operation result list. |
| ├─ obBackupObjectList | Array | List of operation objects, which may be empty. |
| ├─ beSuccessful | Boolean | Whether the operation was submitted successfully. |
| ├─ taskIdList | LongArray | List of restore task IDs. |
| ├─ errorCode | Object | Backup and restore error codes, which may be empty upon success. |
| ├─ hint | String | Success message, which may be empty upon success. |
Examples
Request example
The following example restores tenant tenant_a to the current OCP target cluster using the OSS physical backup parsed by calling the Parse global backup information API:
POST /api/v2/backup/restore
{
"backupTenantStatus": "OFFLINE",
"restoreOfflineTenantRequiredParam": {
"backupMode": "PHYSICAL_BACKUP",
"backupClusterName": "prod_cluster",
"backupObClusterId": 1001,
"backupTenantName": "tenant_a",
"backupObTenantId": 1002,
"restoreClusterId": 2001,
"obBackupStorageBaseInfo": {
"backupStorageType": "BACKUP_STORAGE_OSS",
"storageUrl": "example-bucket/obbackup",
"ossAccessKey": {
"endpoint": "oss-cn-hangzhou.aliyuncs.com",
"accessKeyId": "${ACCESS_KEY_ID}",
"accessKeySecret": "${ACCESS_KEY_SECRET}"
}
},
"hostIdList": [3001],
"logStorageMode": "SAME_AS_DATA",
"restoreEndTime": "2026-09-09T09:30:00+08:00",
"restoreTenantInfoParam": {
"name": "tenant_a_restore",
"primaryZone": "zone1",
"zones": [
{
"name": "zone1",
"replicaType": "FULL",
"resourcePool": {
"unitSpecName": "S1",
"unitCount": 1
}
}
],
"restoreMethod": "full",
"enableDynamicPartition": true
},
"addSource": false
}
}
Response example
{
"data": {
"obBackupTaskType": "RESTORE",
"backupObjectOpsResultList": [
{
"beSuccessful": true,
"taskIdList": [4001]
}
]
},
"duration": 51,
"server": "10.0.0.10",
"status": 200,
"successful": true,
"timestamp": "2026-09-09T10:05:00.051+08:00",
"traceId": "5962f337662d4043"
}
Considerations
- The storage information and resolution host in the two interfaces must be consistent. Otherwise, the verification before restoration may not be able to reproduce the resolution result.
successful=trueand HTTP 200 only indicate that the API was processed successfully. The final result of the restore operation also depends on the status of the tasks corresponding totaskIdList.- Interpret the meanings of data backup points, log backup intervals, and the
RECOVERABLEinterval returned by the API differently. When initiating a restore operation, use theRECOVERABLE.realRecoverableTimeIntervalinstead of selecting a time based on a single data backup point. - The network connectivity, permissions, and region configurations for object storage are determined by the caller's environment. The API itself does not establish cross-environment networks or authorizations on behalf of the caller.