6.2 MySQL 路由器 REST API 参考

MySQL路由器8.0 / 第 6 章 MySQL Router REST API / 6.2 MySQL 路由器 REST API 参考

6.2 MySQL 路由器 REST API 参考

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

表 6.1 MySQL 路由器 REST API 端点

端点	描述	插入	方法
/元数据	获取元数据实例名称	rest_metadata_cache	得到
/元数据/{元数据名称}/配置	获取元数据配置详细信息	rest_metadata_cache	得到
/元数据/{元数据名称}/状态	检查元数据状态	rest_metadata_cache	得到
/路由器/状态	检查路由器状态	休息路由器	得到
/路线	获取路线列表	休息路由	得到
/routes/{routeName}/blockedHosts	获取被阻止的 IP 列表	休息路由	得到
/路线/{路线名称}/配置	获取路由配置详情	休息路由	得到
/routes/{routeName}/connections	获取路线连接	休息路由	得到
/路线/{路线名称}/目的地	获取路线目的地	休息路由	得到
/路线/{路线名称}/健康	检查路线健康状况	休息路由	得到
/路线/{路线名称}/状态	检查路线状态	休息路由	得到
/连接池/{名称}/配置	检查连接池配置	休息连接池	得到
/连接池/{名称}/状态	检查连接池状态	休息连接池	得到
招摇.json	获取包含可用路径和信息的 swagger 文件	休息API	得到

元数据

得到 /metadata

获取元数据缓存实例的列表

可用的响应

200

描述：元数据缓存实例列表

响应模式

项目

大批

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

示例 200 响应数据：

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

得到 /metadata/{metadataName}/config

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

可用的响应

200

描述：元数据缓存配置

响应模式

集群名称

细绳

可选，复制组的名称

时间刷新InMs

整数

TTL 编号

groupReplicationId

细绳

可选的

节点

大批

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

404

描述：找不到缓存

路径参数

元数据名称（必填）

细绳

集群名称

示例 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
    }
  ]
}

得到 /metadata/{metadataName}/status

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

可用的响应

200

描述：元数据缓存的状态

响应模式

最后刷新主机名

细绳

最后刷新端口

整数

时间上次刷新失败

细绳

上次刷新成功时间

细绳

刷新成功

整数

刷新失败

整数

404

描述：找不到缓存

路径参数

元数据名称（必填）

细绳

集群名称

示例 200 响应数据：

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

路由器

得到 /router/status

获取路由器状态

可用的响应

200

描述：路由器状态

响应内容类型： application/json

响应模式

主机名

细绳

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

进程号

整数

应用程序的进程ID

产品版

细绳

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

时间开始

细绳

应用程序启动的日期时间字符串，例如“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"
}

路线

得到 /routes

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

可用的响应

200

描述：支持的路由列表

响应模式

项目

大批

路线清单

示例 200 响应数据：

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

得到 /routes/{routeName}/config

获取路由配置

可用的响应

200

描述：路由配置

响应模式

绑定地址

细绳

地址正在监听的路由

绑定端口

整数

路由器侦听的 TCP 端口

clientConnectTimeoutInMs

整数

传入连接的连接超时

目标连接超时 InMs

整数

传出连接的连接超时

最大活动连接数

整数

最大活动连接数

最大连接错误

整数

客户端被阻塞前的最大相邻连接错误数

协议

细绳

协议，“经典”或“x”

插座

细绳

监听套接字或命名管道

路由策略

细绳

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

模式

细绳

使用的模式；例如由路由器的模式配置选项定义的“读写”或“只读”

404

描述：找不到路由

路径参数

路线名称（必填）

细绳

路线名称

示例 200 响应数据：

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

得到 /routes/{routeName}/status

获取路由状态

可用的响应

200

描述：路由状态

响应模式

主动连接

整数

路由上的活动连接数

总连接数

整数

路由处理的连接数

被封锁的主机

整数

被阻止的主机数

404

描述：找不到路由

示例 200 响应数据：

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

路径参数

路线名称（必填）

细绳

路线名称

得到 /routes/{routeName}/health

获取路线的健康状况

可用的响应

200

描述：路由的健康状况

响应模式

活着

布尔值

404

描述：找不到路由

路径参数

路线名称（必填）

细绳

路线名称

示例 200 响应数据：

{
  "isAlive": true
}

得到 /routes/{routeName}/destinations

获取路线的目的地

可用的响应

200

描述：路线的目的地

响应模式

项目

大批

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

404

描述：找不到路由

路径参数

路线名称（必填）

细绳

路线名称

示例 200 响应数据：

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

得到 /routes/{routeName}/connections

获取路线的连接

可用的响应

200

描述：路线的连接

响应模式

项目

大批

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

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

404

描述：找不到路由

路径参数

路线名称（必填）

细绳

路线名称

示例 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"
    }
  ]
}

得到 /routes/{routeName}/blockedHosts

获取路由的阻止主机列表

可用的响应

200

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

响应模式

项目

大批

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

404

描述：找不到路由

路径参数

路线名称（必填）

细绳

路线名称

示例 200 响应数据：

{
  "items": []
}

连接池

得到 /connection_pool/{name}/config

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

按照配置选项idleTimeout的定义显示。idle_timeout这是连接池中的连接关闭前的超时秒数（整数）。

得到 /connection_pool/{name}/status

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

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

该rest_connection_pool功能是在 MySQL Router 8.0.29 中添加的。

招摇.json

得到 /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"
        },
        "mode": {
          "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"
    }
  }
}