Overview
Queries the topology of a specified OceanBase Cloud instance, including its zone distribution and node list.
API details
Constraints
The caller must have an AccessKey for accessing APIs. For information about how to obtain the AccessKey ID and AccessKey Secret, see Manage AccessKeys.
Request path
GET /api/v2/instances/{instanceId}/topology
Request parameters
Path
Parameter |
Type |
Required |
Description |
|---|---|---|---|
| instanceId | String | Yes | ID of the instance in OceanBase Cloud. |
Query
Parameter |
Type |
Required |
Description |
|---|---|---|---|
| requestId | String | Yes | ID of the request. Used for troubleshooting. |
Response parameters
Field |
Type |
Description |
Example value |
|---|---|---|---|
| success | Boolean | Whether the operation succeeded. | true |
| errorCode | String | Error code. | INVALID_PARAMETER |
| errorMessage | String | Error message. | Invalid parameter |
| data | Object | business data (object). | N/A |
| cost | Number | Time consumed. | 1.0 |
| server | String | Server address, typically the IP address of an OBServer node. | 10.0.0.10 |
| requestId | String | Request ID. | d04eabba**** |
| totalCount | Number | Total number of records. | 100.0 |
| extra | Object | Extended information. | {} |
data object fields
Field |
Type |
Description |
Example value |
|---|---|---|---|
| instanceId | String | ID of the OceanBase cluster. | obcluster-***** |
| tenants | Array | list of tenants. | [{'tenantName': 'pay_core', 'tenantId': 't4louaeei****'}] |
| zones | Array | List of zones. | N/A |
| replicaList | Array | list of replicas. | [{'id': 'resource-123456'}] |
data.replicaList[] object fields
Field |
Type |
Description |
Example value |
|---|---|---|---|
| logicalZone | String | logical zone. | ap-beijing-3-ro-z0 |
| replicaType | String | type of the replica, such as FULL, READONLY, or LOGONLY. | FULL |
| zoneRegionName | String | name of the region to which the zone belongs. | test-name |
| zoneLogicalId | Integer | ID of the logical zone. | 1 |
| zoneId | String | ID of the zone. | cn-hangz**** |
| status | String | current status of the task or resource. | ONLINE |
| nodeNum | Integer | number of nodes. | 3 |
| readonlyInstanceId | String | ID of the read-only instance. | obcluster-*****-ro |
| replicaResource | Object | specification information of the replica resource. | N/A |
| replicaResource.cpu | Object | number or specification of the processor cores. | N/A |
| replicaResource.cpu.totalCpu | Number | total number of CPU cores. | 4.0 |
| replicaResource.cpu.usedCpu | Number | number of used CPU cores. | 4.0 |
| replicaResource.memory | Object | memory information in the resource specification. | N/A |
| replicaResource.memory.totalMemory | Number | total memory. | 16.0 |
| replicaResource.memory.usedMemory | Number | used memory. | 16.0 |
| replicaResource.memory.originalTotalMemory | Number | total memory before the change. | 16.0 |
| replicaResource.memory.unitMemory | Number | unit memory size (GB). | 8.0 |
| replicaResource.memory.hostActualMemory | Number | Actual host memory size, in GiB. | 16.0 |
| replicaResource.memory.systemMemory | Number | Memory occupied by the host system for a Flagship Edition instance, in GiB. | 16.0 |
| replicaResource.memory.originalHostActualMemory | Number | actual memory size of the host corresponding to the original specification, in GiB. | 16.0 |
| replicaResource.diskSize | Object | disk size. | N/A |
| replicaResource.diskSize.totalDiskSize | Number | total disk capacity. | 200.0 |
| replicaResource.diskSize.usedDiskSize | Number | used disk capacity. | 200.0 |
| replicaResource.diskSize.totalDataSize | Number | total data size. | 200.0 |
| replicaResource.diskSize.unitDiskSize | Number | unit disk size. | 200.0 |
| replicaResource.diskSize.availableDiskSize | Number | actual available storage size for users (unit: GB). | 200.0 |
| readOnlyReplicaType | Object | N/A. | N/A |
data.tenants[] object fields
Field |
Type |
Description |
Example value |
|---|---|---|---|
| tenantId | String | ID of the tenant. | t4louaeei**** |
| tenantName | String | name of the tenant. | xxxxxx |
| tenantMode | String | mode of the tenant, such as MySQL or Oracle. | xxxxxx |
| tenantStatus | String | status of the tenant. | xxxxxx |
| tenantDeployType | String | deployment type of the tenant. | xxxxxx |
| tenantCpu | Number | CPU specification of the tenant. | 1 |
| tenantMemory | Number | memory specification of the tenant. | 1 |
| tenantUnitNum | Integer | number of units of the tenant. | 1 |
| tenantZones | Array | zone information. | [{'repli**** |
| tenantCompatibilityMode | String | HBASE or Table for KV clusters, and TenantMode in other scenarios. | xxxxxx |
| parameterTemplate | String | parameter template passed in during creation. | oltp |
data.tenants[].tenantZones[] object fields
Field |
Type |
Description |
Example value |
|---|---|---|---|
| tenantZoneId | String | zone identifier of the tenant. | t4louaeei**** |
| tenantZoneRole | String | role assumed by the tenant replica. | cn-hangz**** |
| isPrimaryTenantZone | Boolean | Whether it is the primary zone of the tenant. | true |
| unitInfoList | Array | list of unit information. | [{'id': 'resource-123456'}] |
data.tenants[].tenantZones[].unitInfoList[] object fields
Field |
Type |
Description |
Example value |
|---|---|---|---|
| unitId | String | ID of the unit. | resource**** |
| serverIp | String | IP address of the server. | 10.0.0.10 |
| serverPort | Integer | port number of the server. | 2881 |
| replicaType | String | type of the replica, such as FULL, READONLY, or LOGONLY. | FULL |
| sn | String | serial number. | example-value |
| isPrimary | Boolean | Whether it is the primary zone or the leader replica. | true |
| cpu | Number | number or specification of the processor cores. | 4.0 |
| memory | Number | memory information in the resource specification. | 16.0 |
| dataSize | Number | data size. | 200.0 |
| logDiskSize | Number | size of the log disk. | 200.0 |
| zone | String | zone. | cn-hangzhou-i |
| logicalZone | String | logical zone. | ap-beijing-3-ro-z0 |
| tenantObId | Integer | ID of the OceanBase tenant. | 1 |
| tenantId | String | ID of the tenant. | t4louaeei**** |
| resourcePoolId | Integer | ID of the resource pool. | 1 |
| migrateFromServerIp | String | IP address of the source server for unit migration. | 10.0.0.11 |
| migrateFromServerPort | Integer | port number of the source server for unit migration. | 2881 |
| migrateFromServerSn | String | serial number of the source server for unit migration. | server-sn-001 |
| manualMigrate | Integer | Whether the unit migration is manual. | 0 |
| enableMigrateUnit | Boolean | Whether unit migration is allowed. | true |
| enableCancelMigrateUnit | Boolean | Whether canceling unit migration is allowed. | true |
| status | String | current status of the task or resource. | ONLINE |
data.zones[] object fields
Field |
Type |
Description |
Example value |
|---|---|---|---|
| zoneId | String | ID of the zone. | cn-hangz**** |
| region | String | Required for some object storage vendors, such as S3. | ap-guangzhou |
| zoneDisk | String | displayed value of the data disk capacity of the zone. | 200 |
| logicZoneId | String | ID of the logical zone. | resource**** |
| nodes | Array | list of nodes. | [{'id': 'resource-123456'}] |
data.zones[].nodes[] object fields
Field |
Type |
Description |
Example value |
|---|---|---|---|
| nodeId | String | ID of the node. | xxxxxx |
| serverIp | String | IP address of the server. | 10.0.0.10 |
| nodeCopyId | Integer | index number of the node replica in the topology. | 1 |
| nodeStatus | String | current running status of the node. | ONLINE |
| replicaType | String | type of the replica, such as FULL, READONLY, or LOGONLY. | FULL |
| nodeResource | Object | specification information of the node resource. | N/A |
| nodeResource.cpu | Object | N/A. | N/A |
| nodeResource.memory | Object | N/A. | N/A |
| nodeResource.diskSize | Object | N/A. | N/A |
Examples
Request example
curl --digest -u '<Your AccessKey ID:AccessKey Secret>' \
-X GET \
'https://api-cloud.oceanbase.com/api/v2/instances/{instanceId}/topology?requestId={requestId}'
Response example
JSON format
{
"success": true,
"errorCode": "INVALID_PARAMETER",
"errorMessage": "Invalid parameter",
"data": {
"instanceId": "obcluster-*****",
"tenants": [
{
"tenantId": "t4louaeei****",
"tenantName": "xxxxxx",
"tenantMode": "xxxxxx",
"tenantStatus": "xxxxxx",
"tenantDeployType": "xxxxxx",
"tenantCpu": 1,
"tenantMemory": 1,
"tenantUnitNum": 1,
"tenantZones": [
{
"tenantZoneId": "t4louaeei****",
"tenantZoneRole": "cn-hangz****",
"isPrimaryTenantZone": true,
"unitInfoList": [
{
"unitId": "resource****",
"serverIp": "xxx.xxx.x.xxx:xxx",
"serverPort": 2881,
"replicaType": "FULL",
"sn": "example-value",
"isPrimary": true,
"cpu": 4.0,
"memory": 16.0,
"dataSize": 200.0,
"logDiskSize": 200.0,
"zone": "cn-hangzhou-i",
"logicalZone": "ap-beijing-3-ro-z0",
"tenantObId": 1,
"tenantId": "t4louaeei****",
"resourcePoolId": 1,
"migrateFromServerIp": "xxx.xxx.x.xxx:xxx",
"migrateFromServerPort": 2881,
"migrateFromServerSn": "server-sn-001",
"manualMigrate": 0,
"enableMigrateUnit": true,
"enableCancelMigrateUnit": true,
"status": "ONLINE"
}
]
}
],
"tenantCompatibilityMode": "xxxxxx",
"parameterTemplate": "oltp"
}
],
"zones": [
{
"zoneId": "cn-hangz****",
"region": "ap-guangzhou",
"zoneDisk": "200",
"logicZoneId": "resource****",
"nodes": [
{
"nodeId": "xxxxxx",
"serverIp": "xxx.xxx.x.xxx:xxx",
"nodeCopyId": 1,
"nodeStatus": "ONLINE",
"replicaType": "FULL",
"nodeResource": {
"cpu": "xxxxxx",
"memory": "xxxxxx",
"diskSize": "xxxxxx"
}
}
]
}
],
"replicaList": [
{
"logicalZone": "ap-beijing-3-ro-z0",
"replicaType": "FULL",
"zoneRegionName": "test-name",
"zoneLogicalId": 1,
"zoneId": "cn-hangz****",
"status": "ONLINE",
"nodeNum": 3,
"readonlyInstanceId": "obcluster-*****-ro",
"replicaResource": {
"cpu": {
"totalCpu": 4.0,
"usedCpu": 4.0
},
"memory": {
"totalMemory": 16.0,
"usedMemory": 16.0,
"originalTotalMemory": 16.0,
"unitMemory": 8.0,
"hostActualMemory": 16.0,
"systemMemory": 16.0,
"originalHostActualMemory": 16.0
},
"diskSize": {
"totalDiskSize": 200.0,
"usedDiskSize": 200.0,
"totalDataSize": 200.0,
"unitDiskSize": 200.0,
"availableDiskSize": 200.0
}
},
"readOnlyReplicaType": "xxxxxx"
}
]
},
"cost": 1.0,
"server": "xxx.xxx.x.xxx:xxx",
"requestId": "d04eabba****",
"totalCount": 100.0,
"extra": "{}"
}