如 第 5.8.2.1 节,“MySQL Shell API 函数的命令行集成” 所述,MySQL Shell 中可用的大多数 API 都会为所提供的参数指定特定的数据类型。命令行参数中的值可以使用 JSON 规范提供,但需要考虑以下事项。某些终端会对数据进行自己的预处理,这会影响数据传递到 MySQL Shell 的方式,具体取决于所使用的终端。例如
某些终端会在找到空格时分割参数。
连续空格可能会被分割逻辑忽略。
引号可能会被删除。
MySQL Shell 会将终端传递给它的值进行解释,因此您必须以正确格式化的方式将数据提供给终端。例如
- 重要
某些终端要求转义引号
-
在以下情况下,字符串参数应加引号
它们包含空格
该参数是列表参数,并且包含逗号
它们包含转义字符
API 参数可以接受不同的数据类型,而该值(基于 JSON 规范)可能为错误的数据类型。
使用 JSON 定义参数时,请对字符串值和字符串键加引号。避免在引号项之外使用空格。
以下示例说明了一些参数处理方法。
-
要传入多个参数,每个参数都是一个字符串,则无需加引号
$ mysqlsh -- object function simple string
在这种情况下,MySQL Shell 会获取两个参数 - 参数 1 是
simple
,参数 2 是string
。 -
如果您希望将这两个字符串视为单个参数,则必须用引号将它们括起来,如下所示
$ mysqlsh -- object function "simple string"
在这种情况下,MySQL Shell 会获取一个参数 - 参数 1 是
simple string
。 -
要使用包含反斜杠等字符的参数,则必须用引号将字符串括起来。否则,该字符将被忽略。例如
$ mysqlsh -- object function simple\tstring
在这种情况下,MySQL Shell 会获取一个参数 -
simpletstring
,反斜杠字符 (\
) 已被忽略。要确保反斜杠字符传递到 MySQL Shell,请用引号将字符串括起来
$ mysqlsh -- object function "simple\tstring"
在这种情况下,MySQL Shell 会获取一个参数 -
simple\tstring
。
使用命令行集成时,定义 JSON 数组有其自身的注意事项。例如,在 MySQL Shell 交互模式中,您可以将 JSON 数组定义为
["simple",123]
要使用命令行集成中的相同数组,则需要进行特定的引号。以下示例说明了如何正确引用 JSON 数组
-
尝试以与交互模式相同的方式传递 JSON 数组不起作用
$ mysqlsh -- object function ["simple", 123]
在这种情况下,MySQL Shell 会获取两个参数 - 参数 1 是
[simple,
,参数 2 是123]
。 -
数组中不使用空格会有所帮助,但它仍然不是有效的 JSON 数组
$ mysqlsh -- object function ["simple",123]
在这种情况下,MySQL Shell 会获取一个参数 -
[simple,123]
。 -
要创建有效的 JSON 数组,请在已引用字符串元素中添加转义引号,例如
$ mysqlsh -- object function ["\"simple\"",123]
在这种情况下,MySQL Shell 会获取一个参数 -
["simple",123]
。
要使用包含 JSON 对象的 JSON 数组,需要以类似的方式进行引用。例如,在 MySQL Shell 交互模式中,您可以将包含 JSON 对象的 JSON 数组定义为
{"firstName":"John","lastName":"Smith"}
以下示例说明了如何在命令行集成中正确引用相同数组
-
尝试以与交互模式相同的方式传递 JSON 数组不起作用
$ mysqlsh -- object function {"firstName":"John","lastName":"Smith"}
在这种情况下,MySQL Shell 会获取两个参数 - 参数 1 是
firstName:John
,参数 2 是lastName:Smith
。 -
对字符串数据使用转义引号会导致
$ mysqlsh -- object function {"\"firstName\"":"\"John\"","\"lastName\"":"\"Smith\""}
在这种情况下,MySQL Shell 会获取两个参数 - 参数 1 是
"firstName":"John"
,参数 2 是"lastName":"Smith"
。 -
要解决此问题,您需要另外引用整个 JSON 对象,以获得
$ mysqlsh -- object function "{"\"firstName\"":"\"John\"","\"lastName\"":"\"Smith\""}"
在这种情况下,MySQL Shell 会获取一个参数 -
{"firstName":"John","lastName":"Smith"}
。
由于显示的这些困难以及不同平台的终端行为可能有所不同,因此支持以下格式。
字符串仅在以下情况下需要加引号
该值包含空格
该值本身包含逗号,并且是列表参数(以避免分割)
该值包含转义字符
该值是数字、
null
、true
、false
,但它应该是一个字符串。在这些情况下,该值应使用内部转义引号加引号。换句话说,如果字符串值为“true”,则应在 CLI 调用中将其定义为 ""true""。
除了 JSON 数组外,列表参数还可以以以下方式提供
逗号分隔的值列表
单独的匿名参数
处理列表参数(按位置顺序)时,所有剩余的匿名参数都属于该列表的一部分。以下 MySQL Shell CLI 调用是等效的
-
使用逗号分隔的值列表
$ mysqlsh root@localhost -- util dump-schemas sakila,employees
-
使用连续的匿名参数
$ mysqlsh root@localhost -- util dump-schemas sakila employees
-
使用 JSON 数组
$ mysqlsh root@localhost -- util dump-schemas ["\"sakila\"","\"employees\""]
字典是使用键值对创建的,字典参数中键的值也可以使用命名参数指定
--key=value
以下 MySQL Shell CLI 调用说明了如何在 util.dumpInstance()
函数中为 options 参数定义 threads
和 osBucketName
键
$ mysqlsh -- util dump-instance my-dump --threads=8 --osBucketName=my-bucket
列表键
您可以通过以下方式定义字典中列表键的值
将值定义为 JSON 数组。
将值定义为逗号分隔的值列表。
重复定义键的值。
例如,在以下调用中,传递给 util.dumpInstance()
操作的 excludeSchemas
键的定义是等效的
-
使用逗号分隔的值列表
$ mysqlsh root@localhost -- util dump-instance --outputUrl="my-dump" --excludeSchemas=sakila,employees
-
使用 JSON 数组
$ mysqlsh root@localhost -- util dump-instance --outputUrl="my-dump" --excludeSchemas=["\"sakila\"","\"employees\""]
-
为
--excludeSchemas
键定义多个值$ mysqlsh root@localhost -- util dump-instance --outputUrl="my-dump" --excludeSchemas=sakila --excludeSchemas=employees
字典键
嵌套字典受以下限制支持
仅支持一层嵌套。
不支持内部预定义键的验证。
不支持内部预期数据类型的验证。
定义嵌套字典中键值的语法如下
--key=innerKey=value
例如,要定义 decodeColumns
键并将其传递给 util.importTable()
操作
$ mysqlsh -- util import-table --decodeColumns=myColumn=1
如上一节所示,字典参数通过使用 --key=value
语法的命名参数来支持。在以下情况下,参数必须指定为命名参数:在列表参数之后定义的参数。提供属于列表参数的参数的最方便方法是使用匿名参数,例如 列表参数 中示例所示
$ mysqlsh root@localhost -- util dump-schemas sakila employees
但是,此示例缺少 outputUrl
参数的参数,该参数对于 util.dumpSchemas()
操作是必需的。由于所有剩余的匿名参数都包含在 schemas 列表中的项目中,因此无法将 outputUrl
指定为匿名参数。例如,以下将不起作用
$ mysqlsh root@localhost -- util dump-schemas sakila employees path/to/dump
在此调用中,路径 path/to/dump
将被解释为 schemas 列表中的另一个项目。因此,在从命令行调用函数时,必须将任何在列表参数之后定义的参数指定为命名参数。例如
$ mysqlsh root@localhost -- util dump-schemas sakila employees --outputUrl=path/to/dump