PDF (US Ltr) - 2.3Mb
PDF (A4) - 2.3Mb
MySQL Shell 提供了公开不同功能的全局对象，例如 dba 用于 InnoDB 集群和 InnoDB 复制集管理操作，util 用于实用程序函数，等等。全局对象提供从 MySQL Shell 的脚本模式调用的函数。除了交互式 MySQL Shell 集成之外，您还可以使用命令行集成直接从终端调用对象函数，使您能够轻松地与其他工具集成。
当您在交互模式下使用 MySQL Shell 附带的 API 时，典型的函数语法如下
object.functionName(parameter1, parameter2, ..., parameterN)参数定义了应将数据提供给 API 函数的顺序。在大多数情况下，API 函数期望参数采用特定数据类型，但是有一些例外情况，其中特定参数可以处理多种数据类型。用于 API 函数中参数的数据类型可以是以下类型之一
标量：字符串、数字、布尔值、空值
列表
字典：键值对，其中键是字符串
对象
列表参数通常限于包含预定义数据类型的元素，例如字符串列表，但是，可能存在支持不同数据类型项目的列表参数。
字典参数接受 key-value 对，其中 keys 是字符串。与键关联的 value 通常应为预定义的数据类型。但是，可能存在相同键支持不同数据类型的值的案例。因此，字典参数可以是以下类型之一
允许一组预定义的键值对，在这种情况下，指定不在预定义集中的键会导致错误。
不存在预定义的键值对集，字典接受任何键
换句话说，一些字典参数指定哪些键是有效的。对于这些参数，尝试使用该集合之外的键会导致错误。当不存在预定义的值集时，可以使用任何数据类型的任何值。没有预定义键列表的字典参数接受任何键值对，只要键不在不同字典参数的预定义集中即可。
要使用命令行集成调用全局对象公开的 API 函数，而无需在 MySQL Shell 中启动交互式会话，您必须以正确的方式提供所需的数据。这包括定义调用 API 函数的方式，以及将 API 函数的参数从命令行参数映射到 API 参数的方式。
重要
并非所有 MySQL Shell 函数都由命令行集成公开。例如，dba.getCluster() 等函数依赖于返回一个对象，该对象随后用于进一步操作。此类操作不会由命令行集成公开。
同样，MySQL Shell 命令行集成不支持对象作为参数。任何参数类型为对象的 API 函数都不能与命令行集成一起使用。对象的生存期仅限于创建它的 MySQL Shell 调用的生存期。由于 mysqlsh 在通过此 API 语法执行对象方法后立即退出，从 API 调用接收或传递到 API 调用的任何对象都会立即超出范围。在开发要通过命令行集成公开的 MySQL Shell 插件时，应考虑这一点。
从命令行调用 MySQL Shell API 函数的一般格式为
$ mysqlsh [shell options] -- [shell_object]+ object_function [anonymous_arguments|named arguments]*其中
shell_object：指定一个全局对象，该对象具有公开用于命令行使用的函数。支持以空格分隔的列表中的嵌套对象。object_function：指定应执行的最后一个shell_object的 API 函数。[anonymous_arguments|named arguments]*：指定传递给object_function调用的参数
对于大多数可用 API，需要单个对象，例如
$ mysqlsh -- shell status但是对于嵌套对象，必须指示对象列表。例如，要调用 shell.options 公开的函数，例如 setPersist(optionName, value)，请使用以下语法
$ mysqlsh -- shell options set-persist defaultMode py类似的情况可能发生在 MySQL Shell 插件中定义的嵌套对象中。
传递给函数的参数可以分为以下类型
-
匿名参数：提供给命令的原始值。例如，在以下调用中，
1、one和true是匿名参数$ mysqlsh -- object command 1 one true -
命名参数：以
--key=value的形式提供的键值对。例如，在以下调用中，--sample和--path是命名参数$ mysqlsh -- object command 1 one true --sample=3 --path=some/path
鉴于参数的这种划分，从命令行集成调用 API 函数的一般格式为
$ mysqlsh [shell options] -- object command [anonymous arguments][named arguments]任何 anonymous arguments 的顺序很重要，因为它们以位置方式处理。另一方面，named arguments 可以出现在任何位置，因为它们首先被处理并与相应的参数相关联。处理命名参数后，匿名参数以位置方式处理。