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