本书介绍如何安装和配置 MySQL REST 服务 (MRS)，以及如何通过 REST 调用访问数据。

章节概述

• MRS 简介
• MRS 部署架构
• MRS 配置
• 添加 REST 服务
• 将模式和对象添加到 REST 服务
• MRS 示例
  • MRS 笔记示例

另请参阅

• MySQL REST 服务 - SQL 参考 - 本书讨论 MySQL REST 服务 SQL 扩展。
• MySQL REST 服务 - 核心 REST API - 本书提供了使用 MySQL REST 服务查询和对表和视图执行其他操作的示例，前提是您已对其启用 REST。
• MySQL REST 服务 - SDK 参考 - 本书介绍如何使用 MRS 软件开发工具包并讨论客户端 API。

1 MySQL REST 服务简介

欢迎使用 MySQL REST 服务 (MRS)。它提供了一种快速有效的方式，通过 HTTPS REST 接口为客户端应用程序提供数据服务。

要开始动手操作，请参阅 MRS 笔记示例，并按照其中的 构建和部署 说明进行操作。

本节概述了 MySQL REST 服务及其功能。

关于 MySQL REST 服务

MySQL REST 服务 (MRS) 提供对选定 MySQL 模式对象的 HTTPS REST 访问。它以 Oracle REST 数据服务 (ORDS) 为模型，并支持其子集。

有关更多信息，请参阅 ORDS

MRS 包含以下组件

• MySQL 解决方案（如 MySQL Heatwave、MySQL InnoDB 集群、独立 MySQL 服务器等）
  • 提供包含 MRS 配置的元数据模式 mysql_rest_service_metadata
  • 提供应用程序数据
• MySQL 路由器
  • 一个或多个 MySQL 路由器实例，用于在默认端口 8443 上提供 HTTPS REST 接口
• MySQL Shell / VS Code 的 MySQL Shell
  • 支持通过嵌入在 VS Code 中的图形用户界面 (GUI) 管理 MRS
  • MRS 插件，用于在终端和使用脚本配置和管理 MRS 设置

关于 REST API

表述性状态转移 (REST) 是一种用于分布式超媒体系统（如万维网）的软件架构风格。当 API 符合 REST 的原则时，它被称为 RESTful API。尽管本文档不会详细介绍 REST，但 REST API 具有以下特点

• 数据被建模为一组资源。资源通过 URI 标识。
• 一组较小的统一操作用于操作资源（例如，PUT、POST、GET、DELETE）。
• 资源可以具有多种表示形式（例如，博客可以具有 HTML 表示形式和 RSS 表示形式）。
• 服务是无状态的，因为客户端可能会访问相关资源，因此应在返回的表示中标识这些资源，通常是通过提供超文本链接。

功能概述

2 部署架构

MySQL REST 服务 (MRS) 可以根据各个项目的具体需求以多种方式部署。

开发部署

最小的开发环境包括一个在同一台机器上运行的 MySQL 服务器实例和一个 MySQL 路由器实例。

建议的开发部署包括一个至少包含三个 MySQL 服务器实例和两个 MySQL 路由器实例的 InnoDB 集群。

对于基于云的开发，应使用启用了高可用性功能的 MySQL 数据库服务实例以及两个具有 MySQL 路由器部署的计算实例。

生产部署

在生产环境中，应使用包含三个或更多 MySQL 路由器实例的 InnoDB 集群设置。建议使用负载均衡器将 MySQL 路由器实例的 HTTPS 端口公开到公用互联网。

对于生产环境中的基于云的开发，应使用启用了高可用性功能的 MySQL 数据库服务实例以及三个或更多具有 MySQL 路由器部署的计算实例。建议使用负载均衡器将 MySQL 路由器的 HTTPS 端口公开到公用互联网。

3 配置 MySQL REST 服务

要配置 MySQL REST 服务 (MRS)，请执行以下步骤

1. 部署 MySQL 解决方案。
2. 配置 MRS 元数据数据库模式。
3. 引导 并运行一个或多个 MySQL 路由器实例以支持 MRS。

执行完这些步骤后，MySQL REST 服务将完全配置完毕。

然后，可以在 MySQL 路由器引导过程中配置的 HTTP/S 端点访问这些端点。

部署 MySQL 解决方案

支持以下 MySQL 解决方案

• MySQL HeatWave
• MySQL InnoDB 集群
• MySQL InnoDB 集群集
• MySQL InnoDB 副本集
• MySQL 运算符

出于开发目的，还支持独立的 MySQL 服务器实例。请避免在生产部署中使用独立设置，因为它不提供任何形式的高可用性 (HA)。

• 独立 MySQL 服务器

请参阅相应的文档，了解如何部署和配置不同的 MySQL 解决方案。

3.1 配置 MRS 元数据模式

MySQL REST 服务将其配置存储在 mysql_rest_service_metadata 数据库模式中。要部署元数据模式，请执行本节中描述的任务之一。

注意：用于连接到 MySQL 解决方案的 MySQL 用户必须具有 MySQL 权限才能创建数据库模式和角色。

3.1.1 使用 VS Code 的 MySQL Shell 配置 MRS

1. 启动 VS Code，安装 VS Code 的 MySQL Shell 扩展，然后将数据库连接添加到 MySQL 设置。

2. 在 DATABASE CONNECTIONS 视图中右键单击连接，然后选择 Configure Instance for MySQL REST Service Support。

MRS 元数据模式现已配置。

3.1.2 使用 MySQL Shell 配置 MRS

打开终端，启动 MySQL Shell，然后连接到 MySQL 设置。

mysqlsh dba@localhost

通过执行 mrs.configure() 使用 MRS 插件配置元数据模式。

MySQL> localhost:33060+> JS> mrs.configure()
MySQL Rest Data Service configuration.

Checking MRS metadata schema and version...
Creating MRS metadata schema...
The MRS metadata is well configured, no changes performed.

MRS 元数据模式现已配置。

3.2 使用 MRS 支持引导和运行 MySQL 路由器

MySQL 路由器是任何 MySQL 解决方案的重要组成部分，因此通常在与 MySQL 服务器实例相同的步骤中部署。有关更多详细信息，请参阅 MySQL 路由器文档。

需要配置 MySQL 路由器实例以支持 MRS。这通常是通过使用 mysqlrouter_bootstrap 命令来完成的，该命令会查询用户帐户以获取必要的信息。

3.2.1 使用 VS Code 的 MySQL Shell 引导和运行 MySQL 路由器

在使用本地开发设置时，通常在本地开发机器上安装 MySQL 路由器实例。

在这种情况下，可以按以下步骤使用 VS Code 的 MySQL Shell 来简化引导过程并启动 MySQL 路由器实例

1. 在本地开发机器上下载并安装 MySQL 路由器包
   • 如果未使用 macOS 上的 DMG 或 Windows 上的 MSI 包来安装 MySQL 路由器，请确保包含 MySQL 路由器二进制文件的目录位于系统 PATH 中。
2. 在 VS Code 的 MySQL Shell 中，展开 DATABASE CONNECTIONS 视图中的 DB 连接，右键单击 MySQL REST 服务 树项，然后选择 Start Local MySQL Router Instance。
   • 如果 MySQL 路由器尚未配置，则引导操作将在集成的 VS Code 终端中运行，然后启动 MySQL 路由器。
   • 然后可以在 VS Code 终端中检查 MySQL 路由器调试输出。
3. 要关闭 MySQL 路由器，请将焦点设置到显示调试输出的 VS Code 终端，然后按 Ctrl + C.

注意：前面的任务仅适用于不使用 MySQL SSH 隧道或 MDS 隧道功能的经典 MySQL 连接。

引导和启动 MySQL 路由器后，MRS 可在 https://localhost:8443/<service-name> 处访问。

然后，您可以继续 添加 REST 服务。

3.2.2 从命令行引导 MySQL 路由器

在部署新的 MySQL 路由器实例时，建议使用 mysqlrouter_bootstrap 命令来引导和配置路由器，包括 MRS 配置。对于重新配置现有的 MySQL 路由器实例以支持 MRS，这一点也是如此。

mysqlrouter_bootstrap dba@127.0.0.1:3306 --mrs --directory ~/.mysqlrouter

按照命令行上的交互步骤来配置路由器。

手动创建用于访问 MySQL 路由器的 MySQL 用户帐户

当使用mysqlrouter_bootstrap命令为 MRS 配置 MySQL Router 时，本节中描述的用户帐户可以自动创建。

如果您想手动管理所需的 MySQL 帐户，则需要执行以下步骤

1. 创建 MySQL 用户帐户（或帐户）
   • 如果只指定一个帐户，MySQL Router 将使用它来访问 MRS 元数据模式和应用程序模式数据。此帐户必须具有mysql_rest_service_meta_provider和mysql_rest_service_data_provider角色。
   • 如果使用两个帐户，MySQL Router 将使用一个帐户访问 MRS 元数据模式，另一个帐户访问应用程序模式数据。将mysql_rest_service_meta_provider角色分配给一个用户，将mysql_rest_service_data_provider角色分配给另一个用户。
2. 使用以下选项，使用创建的 MySQL 帐户引导 MySQL Routers 实例
   • --mrs-mysql-metadata-account由路由器用于访问 MRS 元数据模式
   • --mrs-mysql-data-account由路由器用于访问应用程序模式

作为 MRS 元数据模式创建的一部分，已为 MySQL Router 访问 MySQL 创建了两个 SQL 角色

• “mysql_rest_service_meta_provider”角色授予对所需的 MRS 元数据模式表的访问权限。
• “mysql_rest_service_data_provider”角色授予对应用程序数据库模式中提供的模式对象的访问权限。

要创建 MySQL 帐户，请使用 MySQL Shell 或 MySQL Shell for VS Code 连接到 MySQL 设置，并执行以下 SQL 语句

CREATE USER 'mysqlrouter_mrs_<router_name>'@'<router_host>' IDENTIFIED BY 'password';
GRANT 'mysql_rest_service_meta_provider', 'mysql_rest_service_data_provider' TO 'mysqlrouter_mrs_<router_name>'@'<router_host>';

然后，在调用mysqlrouter_bootstrap命令时可以使用为帐户指定的用户名。

将 MRS 配置添加到现有 MySQL Router 配置

如果您的 MySQL Router 实例已经配置，则可以在以后添加 MRS 配置。

要获取现有配置文件的路径，请执行mysqlrouter --help以显示路由器配置文件的确切位置。

以下是一个连接到单个开发服务器的示例。

[DEFAULT]
logging_folder = /var/log/mysqlrouter
runtime_folder = /var/run/mysqlrouter
config_folder = /etc/mysqlrouter

[logger]
level = DEBUG

[routing:mrs_rw]
bind_address=0.0.0.0
bind_port=6446
destinations=10.0.1.135:3306
routing_strategy=round-robin
protocol=classic

要在路由器上启用 MRS 支持，需要使用[http_server]部分和[rest_mrs]部分扩展配置文件。

建议使用mysqlrouter_bootstrap命令为 MRS 配置路由器。

mysqlrouter_bootstrap dba@127.0.0.1:13000 --mrs --directory /export/mysql/src/mysql-trunk/boot

这些参数可用于设置 MRS 配置选项。

以下示例演示了连接到单个开发服务器并使用 HTTP 提供 REST 服务。

[http_server]
port=8443
ssl=1
ssl_cert=/Users/myUser/.mysqlsh/plugin_data/gui_plugin/web_certs/server.crt
ssl_key=/Users/myUser/.mysqlsh/plugin_data/gui_plugin/web_certs/server.key

[mysql_rest_service]
mysql_read_only_route=bootstrap_ro
mysql_read_write_route=bootstrap_rw
mysql_user=mysql_router_mrs16_250ho3u15n
mysql_user_data_access=
router_id=16

4 添加 REST 服务和数据库对象

MRS 支持设置大量单独的 REST 服务。

每个 REST 服务都有自己的 URL 路径、主机名、支持的协议、身份验证选项和其他设置设置。服务可以公开选定的数据库模式和对象列表。

可以对每个应用程序执行单独的设置，建议为每个应用程序设置单独的 REST 服务。

添加 REST 服务的前提条件

在设置新的 REST 服务之前，请确保满足以下前提条件

• 必须在目标 MySQL 解决方案上配置 MySQL REST 服务。请参阅本手册的配置部分。
• 用于连接到目标 MySQL 解决方案的 MySQL 帐户需要被授予mysql_rest_service_admin MySQL 角色或具有更高权限的权限集。

要授予mysql_rest_service_admin MySQL 角色，请执行以下 SQL 语句。

GRANT 'mysql_rest_service_admin' TO 'user_account'@'%';

-- Please ensure to include all roles in the next statement
-- that should become active when the user connects
ALTER USER 'user_account'@'%' DEFAULT ROLE 'mysql_rest_service_admin';

4.1 设置新的 REST 服务

可以通过以下几种方式添加新的 REST 服务

• MySQL Shell for VS Code 提供了一个 GUI 对话框来创建 REST 服务。
• MySQL Shell 提供了 MRS 插件，可用于在终端中以交互方式或使用脚本创建 REST 服务。
• 在为 MySQL Shell 编写脚本或插件时，可以使用 MRS 插件在 Python 或 JavaScript 中编写创建脚本。

4.1.1 使用 MySQL Shell for VS Code 添加 REST 服务

在目标 MySQL 实例上配置 MySQL REST 服务后，数据库连接视图（展开时）中的 DB 连接将显示一个新的树项MySQL REST Service。

1. 右键单击树项MySQL REST Service，然后从列表中选择Add REST Service...，以显示 MySQL REST 服务对话框。

2. 为所需参数指定值，然后单击OK以添加新的 REST 服务。

4.1.2 使用 MySQL Shell 添加 REST 服务

对于 MySQL Shell，mrs插件用于使用 MySQL REST 服务。mrs.add.service()函数添加新的 REST 服务。

在没有参数的情况下启动时，交互式向导会提示您输入所需参数。例如

MySQL > localhost:33060+ > Py > mrs.add.service()
Please enter the context path for this service [/mrs]: /myservice
Please enter the host name for this service (e.g. None or localhost) [None]:
   1 HTTP
   2 HTTPS

Please select the protocol(s) the service should support [HTTP,HTTPS]: 2
Comments:
   1 Default Service Options for Development
   2 No options
   3 Custom options

Please select how to initialize the options [Default Service Options for Development]:

Service /myservice created successfully.

执行以下命令以获取有关mrs.add.service()函数的详细帮助信息。

\? mrs.add.service

4.1.3 REST 服务定义

4.1.3.1 关于 MRS AutoREST

AutoREST 是一种快速简便的方法，可将数据库模式表、视图和过程公开为 REST 资源。

4.1.3.2 REST API

表述性状态转移 (REST) 是一种用于分布式超媒体系统（如万维网）的软件架构风格。当 API 符合 REST 的原则时，它被称为 RESTful API。尽管本文档不会详细介绍 REST，但 REST API 具有以下特点

• 数据被建模为一组资源。资源通过 URI 标识。

• 一组较小的统一操作用于操作资源（例如，PUT、POST、GET、DELETE）。

• 资源可以具有多种表示形式（例如，博客可以具有 HTML 表示形式和 RSS 表示形式）。

• 服务是无状态的，并且由于客户端很可能想要访问相关资源，因此应在返回的表示中标识这些资源，通常是通过提供超文本链接。

4.1.3.3 RESTful 服务术语

本节介绍了本手册中使用的一些常见术语

• RESTful 服务：符合 RESTful 架构风格原则的 HTTP Web 服务。

• 资源模块：用于对相关资源模板进行分组的组织单元。

• 资源模板：能够为一组 URI（通用资源标识符）提供服务的单个 RESTful 服务。URI 集合由资源模板的 URI 模式定义

• URI 模式：资源模板的模式。可以是路由模式或 URI 模板，但建议使用路由模式。

• 路由模式：一种模式，侧重于将 URI 的路径部分分解为其组成部分。例如，模式为 /:object/:id? 将匹配 /emp/101（匹配对具有 ID 为 101 的 emp 资源中的项目的请求），并且还将匹配 /emp/（匹配对 emp 资源的请求，因为 :id 参数使用 ? 修饰符进行注释，这表示 id 参数是可选的）。

• HTTP 操作：HTTP（超文本传输协议）定义了可以在资源上执行的标准方法：GET（检索资源内容）、POST（存储新的资源）、PUT（更新现有资源）和 DELETE（删除资源）。

4.2 将数据库模式添加到 REST 服务

对于每个 MySQL 数据库模式，可以创建相应的 REST 模式并将其添加到 REST 服务。可以通过为 MySQL 数据库模式创建多个 REST 模式，将相同的 MySQL 数据库模式添加到不同的 REST 服务。

可以使用 MySQL Shell for VS Code 或命令行上的 MySQL Shell 创建 REST 模式。

注意：将数据库模式添加为 REST 模式并不等同于通过 RESTful Web 服务公开模式中的所有表和视图。它只是意味着让 MySQL REST 服务知道模式存在，并且它可能具有零个或多个要通过 HTTP/S 公开的资源。

添加数据库模式和对象的前提条件

在添加 REST 模式和对象之前，请确保满足以下前提条件

• 必须首先添加 REST 服务（请参阅添加 REST 服务）。
• 用于连接到目标 MySQL 解决方案的 MySQL 帐户需要被授予mysql_rest_service_schema_admin MySQL 角色或具有更高权限的权限集。

要授予mysql_rest_service_schema_admin MySQL 角色，请执行以下 SQL 语句。

GRANT 'mysql_rest_service_schema_admin' TO 'user_account'@'%';

-- Please ensure to include all roles in the next statement
-- that should become active when the user connects
ALTER USER 'user_account'@'%' DEFAULT ROLE 'mysql_rest_service_schema_admin';

4.2.1 通过 MRS DDL 添加模式

在活动的 MySQL Shell 连接上执行CREATE REST SCHEMA DDL 语句，在 FROM 子句中引用相应的 MySQL 数据库模式。有关更多详细信息，请参阅 MRS SQL 参考。

示例

以下示例将sakila数据库模式的 REST 模式添加到 REST 服务/myService。

CREATE OR REPLACE REST SCHEMA /sakila ON SERVICE /myService
    FROM `sakila`
    COMMENTS "The sakila schema";

4.2.2 使用 MySQL Shell for VS Code UI 添加模式

要将数据库模式添加到 REST 服务

1. 在数据库连接视图中右键单击模式，然后选择Add Schema to REST Service。这将打开一个对话框，您可以在其中设置所有 REST 模式参数。

2. 单击OK以添加模式。

4.2.3 使用 MySQL Shell 脚本添加 REST 模式

要将数据库模式添加到 REST 服务，请调用mrs.add.schema()函数。

在没有参数的情况下启动时，交互式向导会提示您输入所需参数。

 MySQL > localhost:33060+ > JS > mrs.add.schema()
   1 information_schema
   2 performance_schema
   3 sys
   4 sakila
   5 test
   6 forum
   7 ortho
   8 mrs_notes

Please enter the name or index of a schema: 4
Please enter the request path for this schema [/sakila]: /sakila
Should the schema require authentication [y/N]:
How many items should be listed per page [Schema Default]:
Comments:
Options:

Service with path /sakila created successfully.

执行以下命令以获取有关mrs.add.schema()函数的详细帮助信息。

\? mrs.add.schema

4.3 添加模式表、视图或过程

将数据库模式对象（表、视图或过程）添加到 MySQL REST 服务 (MRS) 使它们可以通过 RESTful Web 服务访问。在将数据库模式对象添加为 REST 对象之前，必须将包含这些对象的数据库模式添加为 REST 模式。

下图显示了 REST 模式及其 REST 对象。

将 MySQL 数据库模式添加为 REST 模式后，就可以添加其对象。数据库模式表和视图将添加为REST 对偶视图，存储过程将添加为 REST 过程。

注意：REST 对偶视图使应用程序开发人员能够在实施应用程序时采用面向文档的方法。请参阅本文档的JSON 对偶视图部分，了解使用 REST 对偶视图的优势。

可以使用 MySQL Shell for VS Code 或命令行上的 MySQL Shell 添加 MySQL 数据库模式对象。

4.3.1 通过 MRS DDL 添加模式对象

在活动的 MySQL Shell 连接上执行CREATE REST DUALITY VIEW DDL 语句，将数据库模式表或视图添加为 REST 对象。有关更多详细信息，请参阅MRS SQL 参考。

要添加存储过程，可以使用CREATE REST PROCEDURE DDL 语句。

示例

以下示例将sakila.city数据库模式表的 REST 对偶视图添加进来。

CREATE REST DUALITY VIEW /city
ON SERVICE /myService SCHEMA /sakila
FROM `sakila`.`city` AS MyServiceSakilaCity {
    cityId: city_id @SORTABLE,
    city: city,
    countryId: country_id,
    lastUpdate: last_update
};

下一个示例将sakila.film_in_stock数据库模式存储过程的 REST 过程添加进来。

CREATE OR REPLACE REST PROCEDURE /filmInStock
FROM `sakila`.`film_in_stock` AS MyServiceSakilaFilmInStock
PARAMETERS {
    pFilmId: p_film_id @IN,
    pStoreId: p_store_id @IN,
    pFilmCount: p_film_count @OUT
}
RESULT MyServiceSakilaFilmInStock {
    inventoryId: inventory_id @DATATYPE("int")
};

4.3.2 使用 MySQL Shell for VS Code UI 添加模式对象

要将数据库模式对象添加到 REST 模式

1. 在数据库连接视图中右键单击数据库对象，然后选择Add Database Object to REST Service。这将打开MySQL REST 对象对话框。

2. 相应地调整所有 REST 对象设置。

3. 按OK以添加数据库模式对象。

4.3.3 使用 MySQL Shell 添加数据库对象

要将数据库模式添加到 REST 服务，请调用mrs.add.dbObject()函数。

在没有参数的情况下启动时，交互式向导会提示您输入所需参数。

MySQL > localhost:33060+ > JS > mrs.add.dbObject()
   1 mrs_notes
   2 sakila

Please enter the name or index of a schema: 2
   1 TABLE
   2 VIEW
   3 PROCEDURE

Please enter the name or index of a database object type [TABLE]:
   1 actor
   2 address
   3 category
   4 city
   5 country
   6 customer
   7 film
   8 film_actor
   9 film_category
  10 film_text
  11 inventory
  12 language
  13 payment
  14 rental
  15 staff
  16 store

Please enter the name or index of an database object: 4
Please enter the request path for this object [/city]:
   1 CREATE
   2 READ
   3 UPDATE
   4 DELETE

Please select the CRUD operations that should be supported, '*' for all [READ]:
   1 FEED
   2 ITEM
   3 MEDIA

Please select the CRUD operation format [FEED]:
Should the db_object require authentication [y/N]:
Should row ownership be required when querying the object [y/N]:
How many items should be listed per page [Schema Default]:
Comments:

Object added successfully.

执行以下命令以获取有关mrs.add.dbObject()函数的详细帮助信息。

\? mrs.add.dbObject

5 以交互方式使用 REST 服务

MySQL Shell for VS Code 提供了用于设计 REST 服务的实时交互式工作流。

它允许开发人员使用 MRS SDK TypeScript 客户端 API 直接在 DB Notebook 中立即测试他们新创建或修改的 REST 对偶视图和 REST 过程。

交互式工作流程的前提条件

• MySQL Router 实例需要 引导并运行 MRS 支持。在使用本地开发设置时，也可以 直接在 VS Code 中完成。

5.1 切换到 TypeScript 模式

在 MySQL Shell for VS Code 中打开数据库连接后，将显示 DB Notebook。如果 DB Notebook 处于 SQL 模式，请使用 \ts 将其切换到 TypeScript 模式。

5.2 选择 REST 服务

为了在 DB Notebook 上使用 REST 服务，需要将其设置为 current REST 服务。这类似于执行 SQL USE db_name 语句来设置 current 数据库模式。

要获取有关当前 REST 服务的信息，请使用全局 mrs 对象并执行 mrs.getStatus() 函数。它将打印有关 MRS 状态的信息。当前 REST 服务的属性 isCurrent 设置为 true。

示例

ts> mrs.getStatus();
{
    "configured": true,
    "info": "2 REST services available.",
    "services": [
        {
            "serviceName": "myService",
            "url": "https://localhost:8443/myService",
            "isCurrent": true
        },
        {
            "serviceName": "myPublicService",
            "url": "https://localhost:8443/myPublicService",
            "isCurrent": false
        }
    ]
}

一旦设置了当前 REST 服务，MRS TypeScript 客户端 API 将自动为该服务动态生成，并提供给 DB Notebook 上的 TypeScript 代码块。

当前 REST 服务对象可以通过全局变量直接访问，该全局变量使用与 mrs.getStatus() 函数在 serviceName 属性中列出的名称相同。serviceName 直接从 REST 服务的 url context root 路径派生，将其转换为 camel case 并删除所有斜杠 /。例如，url context root 为 /myService 的 REST 服务将可作为 myService 访问。

示例

ts> myService.url;
https://localhost:8443/myService

当前 REST 服务可以通过 DB Notebook 上的 TypeScript 或 VS Code UI 设置。

5.2.1 使用 Typescript 设置当前 REST 服务

全局 mrs 对象自动保存所有可用 REST 服务的属性。REST 服务属性的命名与前面部分讨论的每个 REST 服务的 serviceName 相匹配。

执行 mrs.<serviceName>.setAsCurrent() 函数以使给定的 REST 服务成为当前服务。VS Code 的自动完成功能将帮助选择 serviceName。

示例

ts> mrs.myPublicService.setAsCurrent();

注意：当前 REST 服务仅在使用 macOS 上的 [command] + [Return] 和 Linux 和 Windows 上的 [Ctrl] + [Return] 执行完整的 TypeScript 代码块后才可用。它使用异步消息管道，无法等待。因此，尝试访问当前 REST 服务的特定方法将无法在更改它的同一代码块中工作。

5.2.2 使用 VS Code 设置当前 REST 服务

浏览 VS Code 的 Primary Sidebar 中的 DATABASE CONNECTIONS 视图，打开当前 DB 连接以及 MySQL REST Service 树项，右键单击所需的 MRS 服务，然后从上下文菜单中选择 Set as Current REST Service。

当前 REST 服务由一个实心、填充的 REST 服务图标表示。所有其他 REST 服务都使用带轮廓的图标。

5.3 身份验证

如果一些 REST 对象需要身份验证，并且 REST 身份验证应用程序已添加到 REST 服务，请使用 REST 服务客户端 API 对象的 authenticate() 函数。这将显示一个登录对话框，用户可以在其中指定用户帐户的凭据。

ts> myService.authenticate();

authenticate() 函数仅适用于内置的 MRS 身份验证供应商。请确保在添加 REST 身份验证应用程序时设置此供应商。

5.4 查询 REST 对象

在以下示例中，使用 sakila.city 数据库表，如上面的屏幕截图所示。

ts> myService.sakila.city.findFirst();
{
   "city": "A Corua (La Corua)",
   "links": [
      {
         "rel": "self",
         "href": "/myService/sakila/city/1"
      }
   ],
   "cityId": 1,
   "countryId": 87,
   "lastUpdate": "2006-02-15 04:45:25.000000",
   "_metadata": {
      "etag": "EE93452B41984F3F5BBB0395CCB2CED00F5C748FEEA4A36CCD749CC3F85B7CEA"
   }
}

可以过滤字段，并添加条件 where 子句。有关更多信息，请参阅 MRS SDK 客户端 API 文档。

ts> myService.sakila.city.findMany({select: ["city", "cityId"], where: {city: {$like: "NE%"}}});
{
    "items": [
        {
            "city": "Newcastle",
            "links": [
                {
                    "rel": "self",
                    "href": "/myService/sakila/city/364"
                }
            ],
            "cityId": 364,
            "_metadata": {}
        },
        {
            "city": "Nezahualcyotl",
            "links": [
                {
                    "rel": "self",
                    "href": "/myService/sakila/city/365"
                }
            ],
            "cityId": 365,
            "_metadata": {
                "etag": "681C34301F6ED6FD1200505C9C2CFB90E3367A267B7AADBD85186D781FEC7C19"
            }
        }
    ],
    "limit": 25,
    "offset": 0,
    "hasMore": false,
    "count": 2,
    "links": [
        {
            "rel": "self",
            "href": "/myService/sakila/city/"
        }
    ]
}

要使用 REST 对象对话框 快速编辑 REST DB 对象，可以使用 edit() 函数。请注意，此函数仅在 DB Notebook 上可用。

ts> myService.sakila.city.edit()

6 JSON-Relational 对偶视图

6.1 对偶视图简介

对偶视图结合了关系模式的优势和文档数据库的易用性。它们为您的数据提供概念和操作上的二元性，因为它以关系和分层方式组织。您可以在存储在同一张或多张同一张表中的数据的基础上构建不同的对偶视图，从而提供同一共享数据的不同 JSON 层次结构。这意味着应用程序可以访问（创建、查询、修改）相同的数据，作为 JSON 文档集合或一组相关表和列，并且这两种方法可以同时使用。

6.1.1 用例

MySQL REST 服务提供对对偶视图的全面支持。它们用于涵盖关系用例 (1) 和以文档为中心的用例 (2)。

1. 通过 REST 端点使单个关系表或视图可用
   • 将表的行公开为一组**扁平化**的 JSON 文档
   • 允许应用程序在需要时使用传统的关联方法
2. 为一组相关的数据库模式表创建一个 REST 端点
   • 将相关表公开为一组 JSON 文档中的**嵌套** JSON 对象
   • 允许应用程序采用面向文档的方法

下图可视化了这两个用例。

6.1.2 REST 对偶视图工作流程

在 MySQL REST 服务的范围内，JSON-Relational 对偶视图公开为 REST 对偶视图。这些可以使用 CREATE REST DUALITY VIEW MRS DDL 语句或 交互式使用 MRS 对象对话框 的 MySQL Shell for VS Code 扩展创建。

创建 REST 对偶视图后，使用 REST 访问它非常简单。以下工作流程适用。

• 从 REST 对偶视图中获取文档
• 对文档进行必要的更改，包括对嵌套 JSON 对象的更改
• 将文档放回 REST 对偶视图中

下图显示了典型的 JSON 文档更新周期。

数据库会自动检测新文档中的更改并修改底层行，包括所有嵌套表。共享相同数据的对偶视图会立即反映此更改。与使用传统文档数据库相比，这极大地简化了应用程序开发，因为开发人员不再需要担心不一致。

6.2 无锁乐观并发控制

对偶视图可以在不使用锁的情况下安全地并发更新。从数据库中获取的对象具有计算的校验和，称为 ETag，它包含在返回的对象中，在 _metadata.etag 字段中。

当该对象通过 PUT 提交回 MRS 以更新时，原始对象的 ETag 将与 ETag 的当前版本进行比较。如果与对象对应的行在第一次获取后发生了更改，则 ETag 将不匹配。在这种情况下，请求将以 HTTP 状态代码 412 失败。然后，客户端必须再次获取对象，并根据对象的最新版本重新提交其更新请求。

对象校验和包括源行的所有字段以及所有已连接/包含的行，即使是已过滤的字段也是如此。可以使用 @nocheck 属性显式排除字段。

示例

如果首先，GET /myService/sakila/city/1 返回以下 JSON 文档给客户端。

{
    "city": "A Corua (La Corua)",
    "links": [
        {
            "rel": "self",
            "href": "/myService/sakila/city/1"
        }
    ],
    "cityId": 1,
    "country": {
        "country": "Spain",
        "countryId": 87,
        "lastUpdate": "2006-02-15 04:44:00.000000"
    },
    "countryId": 87,
    "lastUpdate": "2006-02-15 04:45:25.000000",
    "_metadata": {
        "etag": "FFA2187AD4B98DF48EC40B3E807E0561A71D02C2F4F5A3B953AA6CB6E41CAD16"
    }
}

接下来，客户端更新对象并将城市名称更改为 A Coruña (La Coruña) 并通过调用 PUT /myService/sakila/city/1 提交。

{
    "city": "A Coruña (La Coruña)",
    "links": [
        {
            "rel": "self",
            "href": "/myService/sakila/city/1"
        }
    ],
    "cityId": 1,
    "country": {
        "country": "Spain",
        "countryId": 87,
        "lastUpdate": "2006-02-15 04:44:00.000000"
    },
    "countryId": 87,
    "lastUpdate": "2006-02-15 04:45:25.000000",
    "_metadata": {
        "etag": "FFA2187AD4B98DF48EC40B3E807E0561A71D02C2F4F5A3B953AA6CB6E41CAD16"
    }
}

如果目标对象在 GET 和 PUT 请求之间发生了更改（例如，由另一个用户更改），则 ETag 检查将失败，并且 PUT 将导致错误 412 Precondition Failed。

6.3 交互式对偶视图设计

虽然 REST 对偶视图可以通过手动编写 CREATE REST DUALITY VIEW MRS DDL 语句来创建，但在可视化编辑器中设计 REST 对偶视图通常容易得多。

MySQL Shell for VS Code 包含 MySQL REST 对象对话框，其中包含一个高级 JSON/Relational Duality 设计器。使用此设计器，可以在几秒钟内创建即使是复杂的嵌套 REST 对偶视图。

DDL Preview 按钮允许在交互式设计 REST 对偶视图时预览相应的 MRS DDL 语句。

6.3.1 构建 JSON/Relational 对偶视图

为单个关系表（或视图）构建 REST 对偶视图非常简单。使用 MySQL Shell for VS Code 添加数据库模式表 会自动创建相应的 REST 对偶视图，其中包含表中的所有列，作为**扁平化**的 JSON 对象。

通过 VS Code 添加数据库模式表等同于调用 CREATE REST DUALITY VIEW MRS DDL 语句，但不带 graphQlObj 定义，这也将表的 所有列添加为**扁平化**的 JSON 对象。

CREATE OR REPLACE REST DUALITY VIEW /city
FROM `sakila`.`city` AS MyServiceSakilaCity;

SHOW CREATE REST VIEW /city;

+-----------------------------------------------+
| CREATE REST DUALITY VIEW                      |
+-----------------------------------------------+
| CREATE OR REPLACE REST DUALITY VIEW /city     |
|     ON SERVICE /myTestService SCHEMA /sakila  |
|     AUTHENTICATION REQUIRED                   |
|     FROM sakila.city AS MyServiceSakilaCity { |
|         cityId: city_id,                      |
|         city: city,                           |
|         countryId: country_id,                |
|         lastUpdate: last_update               |
|     };                                        |
+-----------------------------------------------+

注意：为了能够在不进行身份验证的情况下访问 REST 对象，需要在 MySQL REST 对象对话框中取消选中 Requires Auth 复选框，或者需要将 AUTHENTICATION NOT REQUIRED 子句添加到 MRS DDL 语句中。这应该只在开发时间或当 REST 端点应该公开可用时进行。

6.3.1.1 启用 CRUD 操作

由于默认情况下只启用了 READ CRUD 操作（参见关系对象旁边突出显示的 R），因此只允许对 REST 对象执行读命令。要更改此设置，请在 MySQL REST 对象对话框中切换每个 CRUD 字母（C - 创建、R - 读取、U - 更新和 D - 删除）以启用或禁用相应的函数。

也可以使用 MRS DDL 语句中的注释来实现这一点。

CREATE OR REPLACE REST DUALITY VIEW /city
FROM `sakila`.`city` @INSERT @UPDATE @DELETE AS MyServiceSakilaCity;

下表显示了 CRUD 操作与 SQL 操作之间的映射。

6.3.2 创建嵌套 JSON/Relational 对偶视图

通过启用引用表，该表的列将作为 JSON 结果中的嵌套条目包含在内。请注意，这适用于 1:1 和 1:n 关系。

这将导致以下结果。

myService.sakila.city.findFirst();

{
    "city": "A Corua (La Corua)",
    "links": [
        {
            "rel": "self",
            "href": "/myService/sakila/city/1"
        }
    ],
    "cityId": 1,
    "country": {
        "country": "Spain",
        "countryId": 87,
        "lastUpdate": "2006-02-15 04:44:00.000000"
    },
    "countryId": 87,
    "lastUpdate": "2006-02-15 04:45:25.000000",
    "_metadata": {
        "etag": "FFA2187AD4B98DF48EC40B3E807E0561A71D02C2F4F5A3B953AA6CB6E41CAD16"
    }
}

6.3.3 创建具有未嵌套引用表的 JSON/Relational 对偶视图

如果引用表的列应该添加到上一级，则可以启用 Unnest 选项。

这将导致以下结果。

myService.sakila.city.findFirst();

{
    "city": "A Corua (La Corua)",
    "links": [
        {
            "rel": "self",
            "href": "/myService/sakila/city/1"
        }
    ],
    "cityId": 1,
    "country": "Spain",
    "countryId": 87,
    "lastUpdate": "2006-02-15 04:45:25.000000",
    "_metadata": {
        "etag": "48889BABCBBA1491D25DFE0D7A270FA3FDF8A16DA8E44E42C61759DE1F0D6E35"
    }
}

6.3.4 创建具有缩减引用表的 JSON/Relational 对偶视图

与其将所有列取消嵌套并禁用所有不需要的列，不如使用 Reduce to... 下拉菜单来选择要用于缩减操作的列。

这将导致与上面的查询相同的结果。

myService.sakila.city.findFirst();

{
    "city": "A Corua (La Corua)",
    "links": [
        {
            "rel": "self",
            "href": "/myService/sakila/city/1"
        }
    ],
    "cityId": 1,
    "country": "Spain",
    "countryId": 87,
    "lastUpdate": "2006-02-15 04:45:25.000000",
    "_metadata": {
        "etag": "48889BABCBBA1491D25DFE0D7A270FA3FDF8A16DA8E44E42C61759DE1F0D6E35"
    }
}

7 MRS 对话框参考

本节讨论 MySQL Shell for VS Code 提供的各个 MRS UI 对话框。

7.1 MRS 服务对话框

7.1.1 REST 服务属性

每个 REST 服务都有一组通用的属性。

7.1.2 REST 服务高级选项

以下高级选项可以以 JSON 格式设置

• headers: 接受一个 JSON 对象，其中一个或多个 HTTP 标头名称作为键，其设置作为值。
• http
  • allowedOrigin: 如果设置为 auto，MySQL 路由器会动态将标头 Access-Control-Allow-Origin 设置为生成请求的域。或者，可以将其设置为特定域 https://mydomain.com 或域列表（例如 ["https://mydomain.com", "https://myotherdomain.com"]）。
• logging
  • exceptions: 如果设置为 true，则记录异常。
  • requests
    • body: 如果设置为 true，则记录所有请求的完整正文。
    • headers: 如果设置为 true，则仅记录所有请求的标头。
  • response
    • body: 如果设置为 true，则记录所有响应的完整正文。
    • headers: 如果设置为 true，则仅记录所有响应的标头。
  • returnInternalErrorDetails: 如果设置为 true，则将代码为 500 的原因错误发送到客户端。
  • includeLinksInResults: 如果设置为 false，则结果不包含导航链接。

7.1.2.1 默认 REST 服务选项

以下示例显示了在部署新服务时用作默认值的选项。

注意：这些选项仅推荐用于开发，必须更改才能在生产环境中使用。

通过将 allowedOrigin 设置为 auto，MySQL 路由器会动态将标头 Access-Control-Allow-Origin 设置为生成请求的域。这样做是为了在开发期间解决 Web 浏览器的跨域资源共享 (CORS) 检查。

{
    "headers": {
        "Access-Control-Allow-Credentials": "true",
        "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Requested-With, Origin, X-Auth-Token",
        "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS"
    },
    "http": {
        "allowedOrigin": "auto"
    },
    "logging": {
        "exceptions": true,
        "request": {
            "body": true,
            "headers": true
        },
        "response": {
            "body": true,
            "headers": true
        }
    },
    "returnInternalErrorDetails": true
}

在生产环境中部署 REST 服务时，需要更改以下设置

1. 将 allowedOrigin 更改为 REST 服务运行的域或域（例如，在生产服务器上部署时为 "https://mydomain.com"）。
2. 将 returnInternalErrorDetails 设置为 false。
3. 根据需要调整日志记录设置。

7.2 MRS 模式对话框

7.2.1 REST 模式属性

每个 REST 模式都有一组通用的属性。

7.3 MRS 对象对话框

可以通过对话框设置以下方面。

• 基本设置
  • 应通过 MRS 公开的数据库模式对象
  • 访问 REST 对象的 URL 路径
• 安全性
  • 对象是公开可用还是需要身份验证
  • 允许的 CRUD 操作
  • 允许对引用表进行的 CRUD 操作
  • 是否应强制执行行所有权以启用行级安全性
• JSON/关系二元性
  • 应公开数据库模式对象的哪些列以及如何命名它们
  • 应包含哪些引用表，嵌套还是非嵌套，还是减少为单个字段

8 身份验证和授权

8.1 身份验证管理

MRS 目前支持以下身份验证方法。

8.1.1 MRS REST 服务特定身份验证

身份验证由 MRS 对 MRS REST 服务特定帐户进行处理。应用程序使用 SCRAM（带盐的挑战响应身份验证机制）安全地验证用户。

8.1.2 MySQL 内部身份验证

身份验证由 MRS 对 MySQL 服务器用户帐户进行处理。应用程序使用 SCRAM（带盐的挑战响应身份验证机制）安全地验证用户。

此身份验证方法适用于未公开的应用程序。

8.1.3 OAuth2 身份验证

MRS 支持来自第三方供应商的多个 OAuth2 服务；例如，使用 Facebook、Twitter 和 Google 登录。为了使 MRS 服务能够针对这些供应商进行身份验证，需要在这些供应商处注册为开发人员，并需要创建特定于供应商的身份验证应用程序。然后，需要在 MRS 端配置 OAuth2 特定设置（如 access_token 和 app_id）。

8.2 授权管理

使用 MRS 时，访问给定 REST 资源可能具有几个级别的限制

• 公开访问 - 不需要授权即可访问 REST 资源及其数据
• 完全访问 - 身份验证后，用户可以完全访问 REST 资源的所有数据
• 有限访问 - 身份验证后，用户只能访问 REST 资源数据的子集

MRS 内置支持几种授权模型。这些授权模型定义了最终用户可以查看和操作的给定 REST 资源的哪些数据

• 基于用户所有权 - 用户可以查看自己的数据
• 基于权限，使用角色管理
• 基于用户层次结构
• 基于组
• 基于组层次结构

如果给定项目的用例与提供的授权模型之一匹配，则无需实现自定义授权。

9 MRS 示例

MRS Shell 插件附带一组示例项目，展示了 MySQL REST 服务的可能性。

它们被实现为简单的 渐进式 Web 应用程序 (PWA) 以展示 MRS 提供的功能。

9.1 MRS 笔记示例

MRS 笔记示例实现了一个简单的笔记应用程序，作为 渐进式 Web 应用程序 (PWA)，允许用户之间共享笔记。

9.1.1 MRS 笔记开发人员展示

本示例展示了以下功能。

• 从 JavaScript 和 TypeScript 代码访问 MRS REST 端点。
• 使用 MRS 服务身份验证 REST 端点来支持用户管理
• 使用 JSON Web 令牌 (JWT) 来管理用户会话

9.1.2 MRS 笔记快速指南

要快速使 MRS 笔记示例正常工作，请随时按照本指南操作。如果您想了解有关示例的更多信息，请继续阅读以下章节。

在 MySQL REST 服务上设置、构建和部署 MRS 笔记示例项目需要执行以下步骤。

1. 将 MRS 笔记示例项目保存到磁盘，并使用 VS Code VSCodeProject:examples/mrs_notes 打开它。
2. 配置 MySQL REST 服务。
3. 创建一个新的 MRS 服务（例如 /myService）。
4. 部署 mrs_notes MySQL 数据库模式 examples/mrs_notes/db_schema/mrs_notes.sql
5. 将 MRS 模式转储加载到 MRS 服务中 examples/mrs_notes/mrs_schema/mrsNotes.mrs.json
6. 确保正在运行引导的 MySQL 路由器实例（如果未运行，请启动它）。
7. 通过以下步骤构建和部署应用程序。

9.1.2.1 部署 TypeScript 示例

MrsNotesTS 项目实现了一个完整的 TypeScript 演示应用程序，允许用户之间共享笔记。

1. 如果您在上一节中没有这样做，请将以下项目保存到磁盘，并使用 VS Code VSCodeProject:examples/mrs_notes 打开它。
2. 在 VS Code 中打开项目文件夹后，将焦点设置到 TERMINAL 选项卡并输入 npm install 以安装所需的节点模块。
3. 在 NPM 脚本视图中，运行 package.json/build 命令，该命令将创建一个名为 dist 的文件夹，其中包含部署所需的所有文件。
4. 在文件夹视图中右键单击 dist 文件夹，然后从弹出菜单中选择 将文件夹上传到 MySQL REST 服务。
5. 在 MRS 静态内容集对话框中，设置应用程序应使用的 请求路径，例如 /app，然后单击 上传 以将文件上传到 MRS 服务。
6. 打开 Web 浏览器并访问上一步骤中指定的完整路径以打开应用程序，例如 https://localhost:8443/myService/app/index.html

9.1.2.2 部署 JavaScript 示例

MrsNotes 项目还附带了一个最小的 JavaScript 演示应用程序，允许每个用户存储自己的笔记。

1. 如果您在上一节中没有这样做，请将以下项目保存到磁盘，并使用 VS Code VSCodeProject:examples/mrs_notes 打开它。
2. 在文件夹视图中右键单击 js_app 文件夹，然后从弹出菜单中选择 将文件夹上传到 MySQL REST 服务。
3. 设置应用程序应使用的路径，例如 /app_js，然后单击 上传 以上传文件。
4. 打开 Web 浏览器并访问上一步骤中指定的路径以打开应用程序，例如 https://localhost:8443/myService/app_js/index.html

9.1.3 MRS 笔记示例的 MRS 设置和配置

请参阅 MRS 文档，了解如何详细设置和配置 MRS 服务。

如果您使用的是本地 MRS 部署部署，则可以使用以下简化步骤。

9.1.4 部署 mrsNotes MySQL 数据库模式

mrsNotes MySQL 数据库模式是 MRS 项目的核心。它定义了数据的结构，其数据库表存储了用户在使用应用程序时输入的所有信息。

要创建 mrsNotes 模式，需要执行相应的 SQL 脚本文件。这可以通过 MySQL Shell 或直接在 VS Code 中使用 VS Code 扩展的 MySQL Shell 来完成。

• 如果您在 VS Code 中浏览此文档，请单击 SQL 脚本名称 examples/mrs_notes/db_schema/mrs_notes.sql 旁边的按钮。

• 如果您想在命令行上使用 MySQL Shell，请切换到 mrs_notes 插件目录并运行以下命令。

  mysqlsh dba@localhost –sql -f examples/mrs_notes/db_schema/mrs_notes.sql

9.1.4.1 mrsNotes EER 图

下图显示了 mrsNotes 模式的所有组件。

最重要的数据库表是 note 表。它存储了用户创建的所有笔记。

user 表保存用户的昵称以及用于接收共享笔记邀请电子邮件的电子邮件地址。

user_has_note 表用于管理与其他用户共享笔记。

一旦需要在用户之间共享选定的笔记，就需要添加一个抽象层。然后，此层允许在用户接受参与共享笔记的邀请后，有选择地访问其他用户编写的笔记。

在这种情况下，该层由一个视图和四个存储过程组成。

• notes_all ... 用户可以查看的所有笔记的视图。
• note_share ... 用于与其他用户共享笔记的存储过程。
• note_accept_share ... 用于接受共享笔记的存储过程。
• note_update ... 用于更新共享笔记的存储过程
• note_delete ... 用于删除共享笔记的存储过程

版权所有 (c) 2022, 2023，Oracle 和/或其关联公司。