5.8.2.2 定义参数

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

由于显示的这些困难以及不同平台的终端行为可能有所不同,因此支持以下格式。

字符串参数

字符串仅在以下情况下需要加引号

  • 该值包含空格

  • 该值本身包含逗号,并且是列表参数(以避免分割)

  • 该值包含转义字符

  • 该值是数字、nulltruefalse,但它应该是一个字符串。在这些情况下,该值应使用内部转义引号加引号。换句话说,如果字符串值为“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 参数定义 threadsosBucketName

$ 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