Overview
You can call this API to query the list of OceanBase clusters. You can filter the clusters by name, ID, or tag, and you can also perform pagination.
API details
Constraints
The caller must have an AccessKey for accessing the multi-cloud API. For information about how to obtain the AccessKey ID and AccessKey secret, see Manage AccessKeys.
Request path
GET /api/v2/instances
Request parameters
Query
| Name | Type | Required | Description | Example value |
|---|---|---|---|---|
| requestId | String | Yes | The request ID for tracing. | dc302d76-66b5-48d8-ab53-a035******** |
| X-Ob-Project-Id | String | Yes | The project ID. | hxq3ztx3377nby3v87ry**** |
| instanceName | String | No | The name of the cluster. | test-cluster |
| tenantSearchKey | String | No | The search keyword for tenants. | |
| instanceId | String | No | The ID of the cluster. | obcluster-***** |
| tagList | String | No | The list of tags of the cluster. | |
| organizationId | String | No | The ID of the organization. | |
| pageNumber | int | No | The page number. | 1 |
| pageSize | int | No | The number of entries per page. | 10 |
Body
| Name | Type | Required | Description | Example value |
|---|---|---|---|---|
| None |
Response parameters
| Name | Type | Description | Example value |
|---|---|---|---|
| data | object | The cluster information, including the dataList parameter. | |
| dataList | arr | The list of cluster information, including the following parameters. | |
| expireTime | String | The expiration time. | |
| managementMode | string | The cluster management mode. DBaaS: the normal mode. |
DBaaS |
| availableZones | array | The zones. | ["4"] |
| version | string | The OBServer version. | 4.2.3 |
| obRpmVersion | String | The detailed OBServer version. | 4.2.3.0-100000232024042317 |
| cloudProvider | string | The name of the cloud service provider.
|
QCLOUD |
| createTime | string | The time when the cluster was created, in the UTC format. | 2023-08-28T08:30:54Z |
| deployMode | string | The data replica mode of the cluster, where n indicates the number of OBServer nodes in each IDC.
|
1-1-1 |
| deployType | string | The deployment type of the cluster.
|
multiple |
| instanceClass | string | The cluster specification. The following specifications are supported:
|
4C16G |
| instanceId | string | The ID of the OceanBase Cloud instance. | ob5****** |
| instanceName | string | The name of the OceanBase cluster. | ob******** |
| instanceRole | string | The role of the OceanBase instance. | NORMAL |
| instanceType | string | The cluster type.
|
CLUSTER |
| payType | string | The billing method of the OceanBase cluster:
|
POSTPAY |
| region | string | The region. | ap-guangzhou |
| saleChannel | String | The sales channel. The default value is self-operated channel:
NoteCurrently, only the normandy channel is supported.
|
domestic |
| vpcId | String | The ID of the VPC. | vpc-xxxxx |
| status | string | The cluster status:
|
ONLINE |
| series | string | The series of the OceanBase cluster. The default value is NORMAL, indicating the standard cluster (cloud disk). It can also be normal_kv, indicating the standard cluster (key-value). | NORMAL |
| primaryInstanceId | String | The ID of the primary cluster. | |
| standbyInstanceIds | arr | The IDs of the standby clusters. | ["xxx","xxxx"] |
| cpuArchitecture | String | The CPU architecture. Valid values: X86 and ARM. | X86 |
| cpu | integer | The number of CPU cores of the cluster. | 8 |
| mem | long | The size of the memory of the cluster, in GiB. | 32 |
| diskSize | long | The storage space, in GiB. | 100 |
| diskType | string | The storage type of the cluster. | cloud_essd |
| state | string | The instance status. | ONLINE |
| usedDiskSize | long | The storage space used by the cluster, in GiB. | 1 |
| stopTime | String | The time when the cluster is stopped. | |
| resource | object | The resource information of the cluster. | |
| cpu | object | The CPU resource information of the cluster. | |
| totalCpu | long | The total number of CPU cores of the cluster. | 4.0 |
| usedCpu | long | The number of CPU cores used by the cluster. | 1.0 |
| disk | object | The storage resource information of the cluster. | |
| totalDiskSize | long | The total disk size. | 100.0 |
| usedDiskSize | long | The size of the used disk. | 1.0 |
| memory | object | The memory resource information of the cluster. | |
| totalMemory | long | The total memory size. | 16.0 |
| usedMemory | long | The size of the used memory. | 4.0 |
| tagList | arr | The list of tags of the cluster instance. | |
| tagKey | String | The key of the tag. | |
| tagValue | String | The value of the tag. | |
| success | boolean | Indicates whether the request was successful. | true/false |
| requestId | String | trace | dc302d76-66b5-48d8-ab53-a035******** (64-bit) |
Examples
Request example
curl --request GET \
--digest -u '<Your ak:sk>' \
-H 'X-Ob-Project-Id: {projectId}' \
--url 'https://api-cloud.oceanbase.com/api/v2/instances?requestId={requestId}&instanceName={instanceName}&pageNumber={pageNumber}&pageSize={pageSize}'
Note
- A project ID uniquely identifies a project. For information about how to obtain the project ID of an instance, see Manage projects.
- Make sure that the project ID corresponding to the specified instanceId is consistent with the specified project ID.
Response example
Here is a successful response example:
{
"data":{
"dataList":[
{
"availableZones":[
"4"
],
"cloudProvider":"QCLOUD",
"cpu":4,
"cpuArchitecture":"X86",
"createTime":"2024-11-12T08:12:35Z",
"deployMode":"1-1-1",
"deployType":"single",
"diskSize":0,
"diskType":"cloud_essd",
"instanceClass":"4C16G",
"instanceId":"ob68gu********",
"instanceName":"ob68gu********",
"instanceRole":"NORMAL",
"instanceType":"cluster",
"managementMode":"DBaaS",
"mem":16,
"obRpmVersion":"4.2.0.0-100000052023073123",
"payType":"POSTPAY",
"region":"ap-beijing",
"resource":{
"cpu":{
"totalCpu":4.0,
"usedCpu":0.0
},
"disk":{
"totalDiskSize":100.0,
"usedDiskSize":1.0
},
"memory":{
"totalMemory":16.0,
"usedMemory":0.0
}
},
"saleChannel":"domestic",
"series":"NORMAL",
"standbyInstanceIds":[],
"state":"STOPPED",
"status":"STOPPED",
"stopTime":"2024-11-12T08:39:43Z",
"tagList":[],
"usedDiskSize":1,
"version":"4.2.0",
"vpcId":"vpc-********"
},
{
"availableZones":[
"d",
"e"
],
"cloudProvider":"HUAWEI",
"cpu":4,
"cpuArchitecture":"X86",
"createTime":"2024-11-11T02:39:33Z",
"deployMode":"1-1-1",
"deployType":"dual",
"diskSize":0,
"diskType":"cloud_essd",
"instanceClass":"4C16G",
"instanceId":"ob68cg********",
"instanceName":"ob68cg********",
"instanceRole":"NORMAL",
"instanceType":"cluster",
"managementMode":"DBaaS",
"mem":16,
"obRpmVersion":"4.1.0.2-104030012023121217",
"payType":"POSTPAY",
"region":"cn-southwest-2",
"resource":{
"cpu":{
"totalCpu":4.0,
"usedCpu":2.0
},
"disk":{
"totalDiskSize":100.0,
"usedDiskSize":1.0
},
"memory":{
"totalMemory":16.0,
"usedMemory":8.0
}
},
"saleChannel":"domestic",
"series":"NORMAL",
"standbyInstanceIds":[],
"state":"ONLINE",
"status":"ONLINE",
"tagList":[],
"usedDiskSize":1,
"version":"4.1.0",
"vpcId":"751bc080-d862-4917-972e-48ae********"
}
],
"total":2
},
"requestId":"b819053c-8969-4373-bc6e-f3a3********",
"success":true
}
Here is a failed response example:
{
"errorCode": "Params.InstanceName.Invalid",
"errorMessage": "The cluster name is invalid.",
"requestId": "cb32942e-bdf2-4d85-a26f-6bf8********",
"success": false
}