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 | The ID of the instance in OceanBase Cloud. |
Query
Parameter |
Type |
Required |
Description |
|---|---|---|---|
| requestId | String | Yes | The ID of the request. Used for troubleshooting. |
Response parameters
Name |
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 | The 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
Name |
Type |
Description |
Example value |
|---|---|---|---|
| instanceId | String | The ID of the OceanBase cluster. | obcluster-***** |
| tenants | Array | The list of tenants. | [{'tenantName': 'pay_core', 'tenantId': 't4louaeei****'}] |
| zones | Array | List of zones. | N/A |
| replicaList | Array | The list of replicas. | [{'id': 'resource-123456'}] |
data.replicaList[] object fields
Name |
Type |
Description |
Example value |
|---|---|---|---|
| logicalZone | String | The logical zone. | ap-beijing-3-ro-z0 |
| replicaType | String | The type of the replica, such as FULL, READONLY, or LOGONLY. | FULL |
| zoneRegionName | String | The name of the region to which the zone belongs. | test-name |
| zoneLogicalId | Integer | The ID of the logical zone. | 1 |
| zoneId | String | The ID of the zone. | cn-hangz**** |
| status | String | The current status of the task or resource. | ONLINE |
| nodeNum | Integer | The number of nodes. | 3 |
| readonlyInstanceId | String | The ID of the read-only instance. | obcluster-*****-ro |
| replicaResource | Object | The specification information of the replica resource. | N/A |
| replicaResource.cpu | Object | The number or specification of the processor cores. | N/A |
| replicaResource.cpu.totalCpu | Number | The total number of CPU cores. | 4.0 |
| replicaResource.cpu.usedCpu | Number | The number of used CPU cores. | 4.0 |
| replicaResource.memory | Object | The memory information in the resource specification. | N/A |
| replicaResource.memory.totalMemory | Number | The total memory. | 16.0 |
| replicaResource.memory.usedMemory | Number | The used memory. | 16.0 |
| replicaResource.memory.originalTotalMemory | Number | The total memory before the change. | 16.0 |
| replicaResource.memory.unitMemory | Number | The 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 | The actual memory size of the host corresponding to the original specification, in GiB. | 16.0 |
| replicaResource.diskSize | Object | The disk size. | N/A |
| replicaResource.diskSize.totalDiskSize | Number | The total disk capacity. | 200.0 |
| replicaResource.diskSize.usedDiskSize | Number | The used disk capacity. | 200.0 |
| replicaResource.diskSize.totalDataSize | Number | The total data size. | 200.0 |
| replicaResource.diskSize.unitDiskSize | Number | The unit disk size. | 200.0 |
| replicaResource.diskSize.availableDiskSize | Number | The actual available storage size for users (unit: GB). | 200.0 |
| readOnlyReplicaType | Object | N/A | N/A |
data.tenants[] object fields
Name |
Type |
Description |
Example value |
|---|---|---|---|
| tenantId | String | The ID of the tenant. | t4louaeei**** |
| tenantName | String | The name of the tenant. | xxxxxx |
| tenantMode | String | The mode of the tenant, such as MySQL or Oracle. | xxxxxx |
| tenantStatus | String | The status of the tenant. | xxxxxx |
| tenantDeployType | String | The deployment type of the tenant. | xxxxxx |
| tenantCpu | Number | The CPU specification of the tenant. | 1 |
| tenantMemory | Number | The memory specification of the tenant. | 1 |
| tenantUnitNum | Integer | The number of units of the tenant. | 1 |
| tenantZones | Array | The zone information. | [{'repli**** |
| tenantCompatibilityMode | String | HBASE or Table for KV clusters, and TenantMode in other scenarios. | xxxxxx |
| parameterTemplate | String | The parameter template passed in during creation. | oltp |
data.tenants[].tenantZones[] object fields
Name |
Type |
Description |
Example value |
|---|---|---|---|
| tenantZoneId | String | The zone identifier of the tenant. | t4louaeei**** |
| tenantZoneRole | String | The role assumed by the tenant replica. | cn-hangz**** |
| isPrimaryTenantZone | Boolean | Whether it is the primary zone of the tenant. | true |
| unitInfoList | Array | The list of unit information. | [{'id': 'resource-123456'}] |
data.tenants[].tenantZones[].unitInfoList[] object fields
Name |
Type |
Description |
Example value |
|---|---|---|---|
| unitId | String | The ID of the unit. | resource**** |
| serverIp | String | The IP address of the server. | 10.0.0.10 |
| serverPort | Integer | The port number of the server. | 2881 |
| replicaType | String | The type of the replica, such as FULL, READONLY, or LOGONLY. | FULL |
| sn | String | The serial number. | example-value |
| isPrimary | Boolean | Whether it is the primary zone or the leader replica. | true |
| cpu | Number | The number or specification of the processor cores. | 4.0 |
| memory | Number | The memory information in the resource specification. | 16.0 |
| dataSize | Number | The data size. | 200.0 |
| logDiskSize | Number | The size of the log disk. | 200.0 |
| zone | String | The zone. | cn-hangzhou-i |
| logicalZone | String | The logical zone. | ap-beijing-3-ro-z0 |
| tenantObId | Integer | The ID of the OceanBase tenant. | 1 |
| tenantId | String | The ID of the tenant. | t4louaeei**** |
| resourcePoolId | Integer | The ID of the resource pool. | 1 |
| migrateFromServerIp | String | The IP address of the source server for unit migration. | 10.0.0.11 |
| migrateFromServerPort | Integer | The port number of the source server for unit migration. | 2881 |
| migrateFromServerSn | String | The 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 | The current status of the task or resource. | ONLINE |
data.zones[] object fields
Name |
Type |
Description |
Example value |
|---|---|---|---|
| zoneId | String | The ID of the zone. | cn-hangz**** |
| region | String | Required for some object storage vendors, such as S3. | ap-guangzhou |
| zoneDisk | String | The displayed value of the data disk capacity of the zone. | 200 |
| logicZoneId | String | The ID of the logical zone. | resource**** |
| nodes | Array | The list of nodes. | [{'id': 'resource-123456'}] |
data.zones[].nodes[] object fields
Name |
Type |
Description |
Example value |
|---|---|---|---|
| nodeId | String | The ID of the node. | xxxxxx |
| serverIp | String | The IP address of the server. | 10.0.0.10 |
| nodeCopyId | Integer | The index number of the node replica in the topology. | 1 |
| nodeStatus | String | The current running status of the node. | ONLINE |
| replicaType | String | The type of the replica, such as FULL, READONLY, or LOGONLY. | FULL |
| nodeResource | Object | The 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 ak:sk>' \
-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": "{}"
}