6.2 MySQL Router REST API Reference — MySQL Router 8.4

6.2 Справочник REST API MySQL Router

Предполагается знание префикса basePath. basePath содержит версию API, например, "/api/20190715". Например, если конечная точка — "/metadata", то URL похож на "https://localhost:8443/api/20190715/metadata". См. Раздел 6.1, «Руководство по REST API MySQL Router» для дополнительной информации.

Таблица 6.1 Конечные точки REST API MySQL Router

Таблица 6.1 Конечные точки REST API MySQL Router
Конечная точка	Описание	Плагин	Метод
/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	Проверить конфигурацию пула соединений	rest_connection_pool	GET
/connection_pool/{name}/status	Проверить состояние пула соединений	rest_connection_pool	GET
swagger.json	Получить файл swagger, содержащий доступные пути и информацию	rest_api	GET

metadata

GET /metadata

Получить список экземпляров кэша метаданных

Доступные ответы

200

Описание: Список экземпляров кэша метаданных

Схема ответа

items

массив

Содержит поля 'name'; имя экземпляра метаданных

Пример ответа 200:

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

GET /metadata/{metadataName}/config

Получить конфигурацию кэша метаданных для реплики кластера

Доступные ответы

200

Описание: Конфигурация кэша метаданных

Схема ответа

clusterName

строка

Необязательно, имя группы репликации

timeRefreshInMs

целое число

Значение TTL

groupReplicationId

строка

Необязательно

nodes

массив

Массив; элементы содержат свойства hostname (строка) и port (целое число)

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

целое число

Идентификатор процесса приложения

productEdition

строка

Версия продукта, например, "MySQL Community - GPL"

timeStarted

строка

Дата и время запуска приложения, например, "2020-06-11T22:08:30.978640Z"

version

строка

Версия приложения, например, "8.0.22"

Пример ответа 200:

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

routes

GET /routes

Получить список (имена) маршрутов, поддерживаемых MySQL Router

Доступные ответы

200

Описание: Список поддерживаемых маршрутов

Схема ответа

items

array

Список маршрутов

Пример данных ответа 200:

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

GET /routes/{routeName}/config

Получить конфигурацию маршрута

Доступные ответы

200

Описание: Конфигурация маршрута

Схема ответа

bindAddress

string

Адрес, на котором прослушивает маршрут

bindPort

integer

TCP-порт, на котором прослушивает маршрутизатор

clientConnectTimeoutInMs

integer

Тайм-аут соединения для входящих соединений

destinationConnectTimeoutInMs

integer

Тайм-аут соединения для исходящих соединений

maxActiveConnections

integer

Максимальное число активных соединений

maxConnectErrors

integer

Максимальное число последовательных ошибок соединения, прежде чем клиент будет заблокирован

protocol

string

Протокол, либо 'classic', либо 'x'

socket

string

Слушающий сокет или именованный канал

routingStrategy

string

Используемая стратегия маршрутизации; например, "round-robin", "round-robin-with-fallback", "first-available" или "next-available", как определено в параметре конфигурации стратегии маршрутизатора

404

Описание: Маршрут не найден

Параметры пути

routeName (required)

string

Имя маршрута

Пример данных ответа 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

integer

Число активных соединений на маршруте

totalConnections

integer

Число соединений, обработанных маршрутом

blockedHosts

integer

Число заблокированных хостов

404

Описание: Маршрут не найден

Пример данных ответа 200:

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

Параметры пути

routeName (required)

string

Имя маршрута

GET /routes/{routeName}/health

Получить состояние работоспособности маршрута

Доступные ответы

200

Описание: Состояние работоспособности маршрута

Схема ответа

isAlive: boolean

404

Описание: Маршрут не найден

Параметры пути

routeName (required)

string

Имя маршрута

Пример данных ответа 200:

{
  "isAlive": true
}

GET /routes/{routeName}/destinations

Получить пункты назначения маршрута

Доступные ответы

200

Описание: Пункты назначения маршрута

Схема ответа

items

array

Содержит 'address' (строка, IP-адрес узла назначения) и 'port' (целое число, порт узла назначения)

404

Описание: Маршрут не найден

Параметры пути

routeName (required)

string

Имя маршрута

Пример данных ответа 200:

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

GET /routes/{routeName}/connections

Получить соединения маршрута

Доступные ответы

200

Описание: Соединения маршрута

Схема ответа

items

array

Каждая запись items содержит следующее:

bytesFromServer: целое число, количество байт, отправленных от сервера клиенту по данному соединению
BytesToServer: целое число, количество байт, отправленных от клиента на сервер по данному соединению
sourceAddress: строка, пара адрес:порт источника соединения (клиент)
destinationAddress: строка, пара адрес:порт пункта назначения соединения (сервер)
timeStarted: строка, момент времени инициализации соединения
timeConnectedToServer: строка, момент времени успешного установления соединения
timeLastSentToServer: строка, момент времени последней отправки данных от клиента на сервер по данному соединению
timeLastReceivedFromServer: строка, момент времени последней отправки данных от сервера клиенту по данному соединению

404

Описание: Маршрут не найден

Параметры пути

routeName (required)

string

Имя маршрута

Пример данных ответа 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

Описание: Список заблокированных хостов для маршрута

Схема ответа

items

array

IP-адреса, которые в настоящее время заблокированы ядром маршрутизации

404

Описание: Маршрут не найден

Параметры пути

routeName (required)

string

Имя маршрута

Пример данных ответа 200:

{
  "items": []
}

connection_pool

GET /connection_pool/{name}/config

Показывает maxIdleServerConnections, как определено параметром конфигурации max_idle_server_connection. Это максимальное число (целое число) бездействующих соединений сервера в пуле соединений.

Показывает idleTimeout, как определено параметром конфигурации idle_timeout. Это тайм-аут в секундах (целое число), прежде чем соединения в пуле соединений будут закрыты.

GET /connection_pool/{name}/status

Показывает reusedConnections как количество (целое число) клиентских соединений, которые повторно использовали соединение сервера с момента запуска приложения.

Показывает idleServerConnections как количество (целое число) бездействующих соединений сервера, которые в настоящее время находятся в пуле соединений.

swagger.json

GET /swagger.json

Получить файл swagger (OpenAPI) для локального экземпляра REST API. Доступ к файлу не требует аутентификации; любой пользователь, имеющий доступ к 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"
    }
  }
}