如 第 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 调用说明了如何
为函数中的选项参数定义
threads
和
键:
osBucketName
util.dumpInstance()
$ mysqlsh -- util dump-instance my-dump --threads=8 --osBucketName=my-bucket
列出键
您可以通过以下方式在字典中定义列表键的值:
将值定义为 JSON 数组。
将值定义为逗号分隔的值列表。
重复定义键的值。
例如,在以下调用中,
excludeSchemas
传递给
util.dumpInstance()
操作的键的定义是等效的:
-
使用逗号分隔的值列表:
$ 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 --decodeColumn=myColumn=1
--key=value
如上一节所示,使用语法
通过命名参数支持字典参数
。还有另一种情况,参数必须指定为命名参数:在列表参数之后定义的参数。提供属于列表参数的参数的最方便的方法是使用匿名参数,例如List Arguments中的示例所示:
$ mysqlsh root@localhost -- util dump-schemas sakila employees
但是,此示例缺少参数的自变量
outputUrl
,这对于操作是必需的util.dumpSchemas()
。因为所有剩余的匿名参数都作为项目包含在模式列表中,所以无法将 指定outputUrl
为匿名参数。例如,以下内容将
不起作用:
$ mysqlsh root@localhost -- util dump-schemas sakila employees path/to/dump
在此调用中,路径path/to/dump
将被解释为架构列表中的另一项。因此,从命令行调用函数时,必须将在列表参数之后定义的任何参数指定为命名参数。例如:
$ mysqlsh root@localhost -- util dump-schemas sakila employees --outputUrl=path/to/dump