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://127.0.0.1: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	檢查 Router 狀態	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

metadata

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
}

router

GET /router/status

取得路由器狀態

可用的回應

200

說明：路由器狀態

回應 Content-Type：application/json

回應結構描述

hostname

字串

執行應用程式的主機名稱；如果未設定主機，則可能為空

processId

整數

應用程式的程序 ID

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

說明：支援的路由清單

回應結構描述

項目

陣列

路由清單

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

整數

用戶端遭到封鎖前允許的相鄰連線錯誤最大數目

protocol

字串

通訊協定，可以是「classic」或「x」

socket

字串

接聽 Socket 或具名管道

routingStrategy

字串

使用的路由策略；例如「round-robin」、「round-robin-with-fallback」、「first-available」或「next-available」，如 Router 的策略組態選項所定義

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": []
}

connection_pool

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"
    }
  }
}