Documentation Home

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

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

字符串参数

字符串在以下情况下需要引用:

  • 该值包含空格

  • 该值本身包含逗号并且用于列表参数(以避免拆分)

  • 该值包含转义字符

  • 该值是一个数字,null, truefalse但它应该是一个字符串。在这些情况下,值应该用内部转义引号引起来。换句话说,如果字符串值为“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和 键: osBucketNameutil.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