MySQL :: MySQL Router 8.4 :: 6.2 MySQL Router REST API 参考

版本 8.4

9.0
8.0

MySQL Router 8.4 / MySQL Router REST API / MySQL Router REST API 参考

6.2 MySQL Router REST API 参考

假设已知 basePath 前缀。basePath 包含 API 版本，例如“/api/20190715”。例如，如果端点是“/metadata”，则 URL 类似于“https://localhost:8443/api/20190715/metadata”。有关相关信息，请参见第 6.1 节，“简单的 MySQL Router REST API 指南”。

表 6.1 MySQL Router REST API 端点

端点	说明	插件	方法
/metadata	获取元数据实例名称	rest_metadata_cache	GET
/metadata/{metadataName}/config	获取元数据配置详细信息	rest_metadata_cache	GET
/metadata/{metadataName}/status	检查元数据状态	rest_metadata_cache	GET
/router/status	检查路由器状态	rest_router	GET
/routes	获取路由列表	rest_routing	GET
/routes/{routeName}/blockedHosts	获取被阻止的 IP 列表	rest_routing	GET
/routes/{routeName}/config	获取路由配置详细信息	rest_routing	GET
/routes/{routeName}/connections	获取路由连接	rest_routing	GET
/routes/{routeName}/destinations	获取路由目标	rest_routing	GET
/routes/{routeName}/health	检查路由运行状况	rest_routing	GET
/routes/{routeName}/status	检查路由状态	rest_routing	GET
/connection_pool/{name}/config	检查 connection_pool 配置	rest_connection_pool	GET
/connection_pool/{name}/status	检查 connection_pool 状态	rest_connection_pool	GET
swagger.json	获取包含可用路径和信息的 swagger 文件	rest_api	GET

元数据

GET /metadata

获取元数据缓存实例列表

可用响应

200

说明：元数据缓存实例列表

响应架构

项目

数组

包含“name”字段；元数据实例的名称

示例 200 响应数据

{
  "items": [
    {
      "name": "myCluster"
    }
  ]
}

GET /metadata/{metadataName}/config

获取集群副本集的元数据缓存配置

可用响应

200

说明：元数据缓存的配置

响应架构

clusterName

字符串

可选，复制组的名称

timeRefreshInMs

整数

TTL 号码

groupReplicationId

字符串

可选

节点

数组

数组；项目包括主机名（字符串）和端口（整数）属性

404

说明：找不到缓存

路径参数

metadataName（必需）

字符串

集群名称

示例 200 响应数据

{
  "clusterName": "myCluster",
  "timeRefreshInMs": 500,
  "groupReplicationId": "e57e9c11-abfe-11ea-b747-0800278566cb",
  "nodes": [
    {
      "hostname": "127.0.0.1",
      "port": 3310
    },
    {
      "hostname": "127.0.0.1",
      "port": 3320
    },
    {
      "hostname": "127.0.0.1",
      "port": 3330
    }
  ]
}

GET /metadata/{metadataName}/status

获取集群副本集的元数据缓存状态

可用响应

200

说明：元数据缓存的状态

响应架构

lastRefreshHostname

字符串

lastRefreshPort

整数

timeLastRefreshFailed

字符串

timeLastRefreshSucceeded

字符串

refreshSucceeded

整数

refreshFailed

整数

404

说明：找不到缓存

路径参数

metadataName（必需）

字符串

集群的名称

示例 200 响应数据

{
  "refreshFailed": 0,
  "refreshSucceeded": 798,
  "timeLastRefreshSucceeded": "2020-06-11T21:17:37.270303Z",
  "lastRefreshHostname": "127.0.0.1",
  "lastRefreshPort": 3310
}

路由器

GET /router/status

获取路由器的状态

可用响应

200

说明：路由器状态

响应内容类型：application/json

响应架构

hostname

字符串

应用程序运行所在的主机名称；如果未配置主机，则它可能为空

processId

整数

应用程序的进程 ID

productEdition

字符串

产品版本，例如“MySQL Community - GPL”

timeStarted

字符串

应用程序启动的日期时间字符串，例如“2020-06-11T22:08:30.978640Z”

版本

字符串

应用程序版本，例如“8.0.22”

示例 200 响应数据

{
  "processId": 6435,
  "productEdition": "MySQL Community - GPL",
  "timeStarted": "2020-06-11T21:10:49.420619Z",
  "version": "8.0.20",
  "hostname": "boat"
}

路由

GET /routes

获取 MySQL Router 支持的路由列表（名称）

可用响应

200

说明：支持的路由列表

响应架构

项目

数组

路由列表

示例 200 响应数据

{
  "items": [
    {
      "name": "myCluster_ro"
    },
    {
      "name": "myCluster_rw"
    },
    {
      "name": "myCluster_x_ro"
    },
    {
      "name": "myCluster_x_rw"
    }
  ]
}

GET /routes/{routeName}/config

获取路由的配置

可用响应

200

说明：路由的配置

响应架构

bindAddress

字符串

路由正在侦听的地址

bindPort

整数

路由器正在侦听的 TCP 端口

clientConnectTimeoutInMs

整数

传入连接的连接超时

destinationConnectTimeoutInMs

整数

传出连接的连接超时

maxActiveConnections

整数

最大活动连接数

maxConnectErrors

整数

在客户端被阻止之前相邻连接错误的最大数量

协议

字符串

协议，“classic”或“x”

套接字

字符串

侦听套接字或命名管道

routingStrategy

字符串

使用的路由策略；例如 Router 的策略配置选项定义的“round-robin”、“round-robin-with-fallback”、“first-available”或“next-available”

404

说明：找不到路由

路径参数

routeName（必需）

字符串

路由的名称

示例 200 响应数据

{
  "bindAddress": "0.0.0.0",
  "bindPort": 6446,
  "clientConnectTimeoutInMs": 9000,
  "destinationConnectTimeoutInMs": 15000,
  "maxActiveConnections": 512,
  "maxConnectErrors": 100,
  "protocol": "classic",
  "routingStrategy": "first-available"
}

GET /routes/{routeName}/status

获取路由的状态

可用响应

200

说明：路由的状态

响应架构

activeConnections

整数

路由上的活动连接数

totalConnections

整数

路由处理的连接数

blockedHosts

整数

被阻止的主机数

404

说明：找不到路由

示例 200 响应数据

{
  "activeConnections": 1,
  "totalConnections": 1,
  "blockedHosts": 0
}

路径参数

routeName（必需）

字符串

路由的名称

GET /routes/{routeName}/health

获取路由的运行状况

可用响应

200

说明：路由的运行状况

响应架构

isAlive

布尔值

404

说明：找不到路由

路径参数

routeName（必需）

字符串

路由的名称

示例 200 响应数据

{
  "isAlive": true
}

GET /routes/{routeName}/destinations

获取路由的目标

可用响应

200

说明：路由的目标

响应架构

项目

数组

包含“address”（字符串，目标节点的 IP 地址）和“port”（整数，目标节点的端口）

404

说明：找不到路由

路径参数

routeName（必需）

字符串

路由的名称

示例 200 响应数据

{
  "items": [
    {
      "address": "127.0.0.1",
      "port": 3320
    },
    {
      "address": "127.0.0.1",
      "port": 3330
    }
  ]
}

GET /routes/{routeName}/connections

获取路由的连接

可用响应

200

说明：路由的连接

响应架构

项目

数组

每个项目条目包含以下内容

bytesFromServer：整数，通过给定连接从服务器发送到客户端的字节数
BytesToServer：整数，通过给定连接从客户端发送到服务器的字节数
sourceAddress：字符串，连接源（客户端）的地址：端口对
destinationAddress：字符串，连接目标（服务器）的地址：端口对
timeStarted：字符串，连接初始化的时间点
timeConnectedToServer：字符串，连接成功建立的时间点
timeLastSentToServer：字符串，在给定连接上最后一次从客户端向服务器发送数据的时间点
timeLastReceivedFromServer：字符串，在给定连接上最后一次从服务器向客户端发送数据的时间点

404

说明：找不到路由

路径参数

routeName（必需）

字符串

路由的名称

示例 200 响应数据

{
  "items": [
    {
      "bytesFromServer": 2952,
      "bytesToServer": 743,
      "sourceAddress": "127.0.0.1:54098",
      "destinationAddress": "127.0.0.1:3310",
      "timeStarted": "2020-06-11T21:28:20.882204Z",
      "timeConnectedToServer": "2020-06-11T21:28:20.882513Z",
      "timeLastSentToServer": "2020-06-11T21:28:20.886969Z",
      "timeLastReceivedFromServer": "2020-06-11T21:28:20.886968Z"
    }
  ]
}

GET /routes/{routeName}/blockedHosts

获取路由的阻止主机列表

可用响应

200

说明：路由的阻止主机列表

响应架构

项目

数组

当前被路由核心阻止的 IP 地址

404

说明：找不到路由

路径参数

routeName（必需）

字符串

路由的名称

示例 200 响应数据

{
  "items": []
}

连接池

GET /connection_pool/{name}/config

显示 max_idle_server_connection 配置选项定义的 maxIdleServerConnections。这是连接池中空闲服务器连接的最大数量（整数）。

显示 idle_timeout 配置选项定义的 idleTimeout。这是连接池中的连接关闭之前的超时时间（以秒为单位）。

GET /connection_pool/{name}/status

将 reusedConnections 显示为自应用程序启动以来重用服务器连接的客户端连接计数（整数）。

将 idleServerConnections 显示为当前连接池中空闲服务器连接的计数（整数）。

swagger.json

GET /swagger.json

获取本地 REST API 实例的 swagger (OpenAPI) 文件。访问该文件不需要身份验证；任何有权访问 REST API 的人都可以生成和查看它。OpenAPI 内容取决于活动的 REST API 插件。

示例 200 响应数据

{
  "swagger": "2.0",
  "info": {
    "title": "MySQL Router",
    "description": "API of MySQL Router",
    "version": "20190715"
  },
  "basePath": "/api/20190715",
  "tags": [
    {
      "name": "connectionpool",
      "description": "Connection Pool"
    },
    {
      "name": "cluster",
      "description": "InnoDB Cluster"
    },
    {
      "name": "app",
      "description": "Application"
    },
    {
      "name": "routes",
      "description": "Routes"
    }
  ],
  "paths": {
    "/connection_pool/{connectionPoolName}/status": {
      "get": {
        "tags": [
          "connectionpool"
        ],
        "description": "Get status of a route",
        "responses": {
          "200": {
            "description": "status of a route",
            "schema": {
              "$ref": "#/definitions/ConnectionPoolStatus"
            }
          },
          "404": {
            "description": "route not found"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/parameters/connectionPoolNameParam"
        }
      ]
    },
    "/connection_pool/{connectionPoolName}/config": {
      "get": {
        "tags": [
          "connectionpool"
        ],
        "description": "Get config of a route",
        "responses": {
          "200": {
            "description": "config of a route",
            "schema": {
              "$ref": "#/definitions/ConnectionPoolConfig"
            }
          },
          "404": {
            "description": "route not found"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/parameters/connectionPoolNameParam"
        }
      ]
    },
    "/connection_pool": {
      "get": {
        "tags": [
          "connectionpool"
        ],
        "description": "Get list of the connection pools",
        "responses": {
          "200": {
            "description": "list of the connection pools",
            "schema": {
              "$ref": "#/definitions/ConnectionPoolList"
            }
          }
        }
      }
    },
    "/metadata/{metadataName}/config": {
      "get": {
        "tags": [
          "cluster"
        ],
        "description": "Get config of the metadata cache of a replicaset of a cluster",
        "responses": {
          "200": {
            "description": "config of metadata cache",
            "schema": {
              "$ref": "#/definitions/MetadataConfig"
            }
          },
          "404": {
            "description": "cache not found"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/parameters/metadataNameParam"
        }
      ]
    },
    "/metadata/{metadataName}/status": {
      "get": {
        "tags": [
          "cluster"
        ],
        "description": "Get status of the metadata cache of a replicaset of a cluster",
        "responses": {
          "200": {
            "description": "status of metadata cache",
            "schema": {
              "$ref": "#/definitions/MetadataStatus"
            }
          },
          "404": {
            "description": "cache not found"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/parameters/metadataNameParam"
        }
      ]
    },
    "/metadata": {
      "get": {
        "tags": [
          "cluster"
        ],
        "description": "Get list of the metadata cache instances",
        "responses": {
          "200": {
            "description": "list of the metadata cache instances",
            "schema": {
              "$ref": "#/definitions/MetadataList"
            }
          }
        }
      }
    },
    "/router/status": {
      "get": {
        "tags": [
          "app"
        ],
        "description": "Get status of the application",
        "responses": {
          "200": {
            "description": "status of application",
            "schema": {
              "$ref": "#/definitions/RouterStatus"
            }
          }
        }
      }
    },
    "/routing/status": {
      "get": {
        "tags": [
          "routing"
        ],
        "description": "Get status of the routing plugin",
        "responses": {
          "200": {
            "description": "status of the routing plugin",
            "schema": {
              "$ref": "#/definitions/RoutingGlobalStatus"
            }
          }
        }
      }
    },
    "/routes/{routeName}/config": {
      "get": {
        "tags": [
          "routes"
        ],
        "description": "Get config of a route",
        "responses": {
          "200": {
            "description": "config of a route",
            "schema": {
              "$ref": "#/definitions/RouteConfig"
            }
          },
          "404": {
            "description": "route not found"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/parameters/routeNameParam"
        }
      ]
    },
    "/routes/{routeName}/status": {
      "get": {
        "tags": [
          "routes"
        ],
        "description": "Get status of a route",
        "responses": {
          "200": {
            "description": "status of a route",
            "schema": {
              "$ref": "#/definitions/RouteStatus"
            }
          },
          "404": {
            "description": "route not found"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/parameters/routeNameParam"
        }
      ]
    },
    "/routes/{routeName}/health": {
      "get": {
        "tags": [
          "routes"
        ],
        "description": "Get health of a route",
        "responses": {
          "200": {
            "description": "health of a route",
            "schema": {
              "$ref": "#/definitions/RouteHealth"
            }
          },
          "404": {
            "description": "route not found"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/parameters/routeNameParam"
        }
      ]
    },
    "/routes/{routeName}/destinations": {
      "get": {
        "tags": [
          "routes"
        ],
        "description": "Get destinations of a route",
        "responses": {
          "200": {
            "description": "destinations of a route",
            "schema": {
              "$ref": "#/definitions/RouteDestinationList"
            }
          },
          "404": {
            "description": "route not found"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/parameters/routeNameParam"
        }
      ]
    },
    "/routes/{routeName}/connections": {
      "get": {
        "tags": [
          "routes"
        ],
        "description": "Get connections of a route",
        "responses": {
          "200": {
            "description": "connections of a route",
            "schema": {
              "$ref": "#/definitions/RouteConnectionsList"
            }
          },
          "404": {
            "description": "route not found"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/parameters/routeNameParam"
        }
      ]
    },
    "/routes/{routeName}/blockedHosts": {
      "get": {
        "tags": [
          "routes"
        ],
        "description": "Get blocked host list for a route",
        "responses": {
          "200": {
            "description": "blocked host list for a route",
            "schema": {
              "$ref": "#/definitions/RouteBlockedHostList"
            }
          },
          "404": {
            "description": "route not found"
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/parameters/routeNameParam"
        }
      ]
    },
    "/routes": {
      "get": {
        "tags": [
          "routes"
        ],
        "description": "Get list of the routes",
        "responses": {
          "200": {
            "description": "list of the routes",
            "schema": {
              "$ref": "#/definitions/RouteList"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "ConnectionPoolStatus": {
      "type": "object",
      "properties": {
        "reusedServerConnections": {
          "type": "integer"
        },
        "idleServerConnections": {
          "type": "integer"
        }
      }
    },
    "ConnectionPoolConfig": {
      "type": "object",
      "properties": {
        "idleTimeoutInMs": {
          "type": "integer"
        },
        "maxIdleServerConnections": {
          "type": "integer"
        }
      }
    },
    "ConnectionPoolSummary": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    },
    "ConnectionPoolList": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ConnectionPoolSummary"
          }
        }
      }
    },
    "MetadataStatus": {
      "type": "object",
      "properties": {
        "lastRefreshHostname": {
          "type": "string"
        },
        "lastRefreshPort": {
          "type": "integer"
        },
        "timeLastRefreshFailed": {
          "type": "string",
          "format": "data-time"
        },
        "timeLastRefreshSucceeded": {
          "type": "string",
          "format": "data-time"
        },
        "refreshSucceeded": {
          "type": "integer"
        },
        "refreshFailed": {
          "type": "integer"
        }
      }
    },
    "MetadataConfig": {
      "type": "object",
      "properties": {
        "clusterName": {
          "type": "string"
        },
        "timeRefreshInMs": {
          "type": "integer"
        },
        "groupReplicationId": {
          "type": "string"
        },
        "nodes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "hostname": {
                "type": "string"
              },
              "port": {
                "type": "integer"
              }
            }
          }
        }
      }
    },
    "MetadataSummary": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    },
    "MetadataList": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/MetadataSummary"
          }
        }
      }
    },
    "ClusterNodeSummary": {
      "type": "object",
      "properties": {
        "groupUuid": {
          "type": "string"
        },
        "serverUuid": {
          "type": "string"
        }
      }
    },
    "ClusterNodeList": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ClusterNodeSummary"
          }
        }
      }
    },
    "ClusterSummary": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    },
    "ClusterList": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ClusterSummary"
          }
        }
      }
    },
    "RouterStatus": {
      "type": "object",
      "properties": {
        "timeStarted": {
          "type": "string",
          "format": "data-time"
        },
        "processId": {
          "type": "integer"
        },
        "version": {
          "type": "string"
        },
        "hostname": {
          "type": "string"
        },
        "productEdition": {
          "type": "string"
        }
      }
    },
    "RoutingGlobalStatus": {
      "totalMaxConnections": "number of total connections allowed",
      "currentMaxConnections": "number of current total connections"
    },
    "RouteHealth": {
      "type": "object",
      "properties": {
        "isAlive": {
          "type": "boolean"
        }
      }
    },
    "RouteStatus": {
      "type": "object",
      "properties": {
        "activeConnections": {
          "type": "integer"
        },
        "totalConnections": {
          "type": "integer"
        },
        "blockedHosts": {
          "type": "integer"
        }
      }
    },
    "RouteConfig": {
      "type": "object",
      "properties": {
        "bindAddress": {
          "type": "string"
        },
        "bindPort": {
          "type": "integer"
        },
        "clientConnectTimeoutInMs": {
          "type": "integer"
        },
        "destinationConnectTimeoutInMs": {
          "type": "integer"
        },
        "maxActiveConnections": {
          "type": "integer"
        },
        "maxConnectErrors": {
          "type": "integer"
        },
        "protocol": {
          "type": "string"
        },
        "socket": {
          "type": "string"
        },
        "routingStrategy": {
          "type": "string"
        },
      }
    },
    "RouteSummary": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    },
    "RouteList": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/RouteSummary"
          }
        }
      }
    },
    "RouteDestinationSummary": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    },
    "RouteDestinationList": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/RouteDestinationSummary"
          }
        }
      }
    },
    "RouteBlockedHostSummary": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    },
    "RouteBlockedHostList": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/RouteBlockedHostSummary"
          }
        }
      }
    },
    "RouteConnectionsSummary": {
      "type": "object",
      "properties": {
        "timeStarted": {
          "type": "string",
          "format": "date-time",
          "description": "timepoint when connection to server was initiated"
        },
        "timeConnectedToServer": {
          "type": "string",
          "format": "date-time",
          "description": "timepoint when connection to server succeeded"
        },
        "timeLastSentToServer": {
          "type": "string",
          "format": "date-time",
          "description": "timepoint when there was last data sent from client to server"
        },
        "timeLastReceivedFromServer": {
          "type": "string",
          "format": "date-time",
          "description": "timepoint when there was last data sent from server to client"
        },
        "bytesFromServer": {
          "type": "integer",
          "description": "bytes sent to destination"
        },
        "bytesToServer": {
          "type": "integer",
          "description": "bytes received from destination"
        },
        "destinationAddress": {
          "type": "string",
          "description": "address of the destination of the connection"
        },
        "sourceAddress": {
          "type": "string",
          "description": "address of the source of the connection"
        }
      }
    },
    "RouteConnectionsList": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/RouteConnectionsSummary"
          }
        }
      }
    }
  },
  "parameters": {
    "connectionPoolNameParam": {
      "name": "connectionPoolName",
      "in": "path",
      "description": "name of a connection pool",
      "required": true,
      "type": "string"
    },
    "metadataNameParam": {
      "name": "metadataName",
      "in": "path",
      "description": "name of cluster",
      "required": true,
      "type": "string"
    },
    "clusterNameParam": {
      "name": "clusterName",
      "in": "path",
      "description": "name of cluster",
      "required": true,
      "type": "string"
    },
    "routeNameParam": {
      "name": "routeName",
      "in": "path",
      "description": "name of a route",
      "required": true,
      "type": "string"
    }
  }
}