5.8.2.1 Command Line Integration for MySQL Shell API Functions — MySQL Shell 9.2

5.8.2.1 Интеграция командной строки для функций API MySQL Shell

MySQL Shell предоставляет глобальные объекты, которые экспонируют различные функциональности, такие как dba для управления операциями InnoDB Cluster и InnoDB ReplicaSet, util для служебных функций и так далее. Глобальные объекты предоставляют функции, которые вызываются из режимов скриптов в MySQL Shell. Помимо интеграции в интерактивный MySQL Shell, вы можете использовать интеграцию командной строки для прямого вызова функций объектов из терминала, что позволит вам легко интегрироваться с другими инструментами.

При использовании API, включенных в MySQL Shell в интерактивном режиме, типичный синтаксис функции выглядит следующим образом:

object.functionName(parameter1, parameter2, ..., parameterN)

Параметры определяют порядок, в котором данные должны предоставляться функции API. В большинстве случаев функции API ожидают параметры определенного типа данных, однако существуют некоторые исключения, где определённый параметр может обрабатывать несколько типов данных. Типы данных, используемые для параметров в функциях API, могут быть следующими:

Скаляры: строка, число, булево значение, null
Списки
Словари: пары ключ-значение, где ключ — строка
Объекты

Параметры списка обычно ограничены элементами предопределенного типа данных, например, список строк. Однако могут быть параметры списка, которые поддерживают элементы различных типов данных.

Параметры словаря принимают пары key-value, где keys являются строками. value, связанные с ключом, обычно ожидаются определённого типа данных. Однако могут быть случаи, когда для значений одного ключа поддерживаются различные типы данных. Следовательно, параметры словаря могут быть одного из следующих типов:

Допускается предопределённый набор пар ключ-значение, в котором указание ключей, не входящих в предопределённый набор, приводит к ошибке.
Предопределённый набор пар ключ-значение отсутствует, словарь принимает любой ключ

Другими словами, некоторые параметры словаря указывают, какие ключи допустимы. Для этих параметров попытка использования ключа за пределами этого набора приводит к ошибке. Когда предопределённый набор значений отсутствует, может использоваться любое значение любого типа данных. Параметры словаря, не имеющие предопределённого списка ключей, принимают любые пары ключ-значение, при условии, что ключ не входит в предопределённый набор другого параметра словаря.

Для использования интеграции командной строки для вызова функций API, экспонируемых глобальными объектами, без необходимости запуска интерактивной сессии в MySQL Shell, необходимо предоставить необходимые данные правильным способом. Это включает в себя определение того, как вызывается функция API, а также способ сопоставления её параметров из аргументов командной строки в аргументы API.

Важно

Не все функции MySQL Shell экспонируются через интеграцию командной строки. Например, функция, такая как dba.getCluster(), полагается на возврат объекта, который затем используется в дальнейших операциях. Такие операции не экспонируются через интеграцию командной строки.

Аналогично, интеграция командной строки MySQL Shell не поддерживает объекты в качестве параметров. Любая функция API с параметром типа объект не может использоваться с интеграцией командной строки. Жизненный цикл объекта ограничен жизненным циклом вызова MySQL Shell, который его создал. Так как mysqlsh завершается сразу после выполнения метода объекта через этот синтаксис API, любые объекты, полученные или переданные в вызов API, будут немедленно выведены из области видимости. Это следует учитывать при разработке плагинов MySQL Shell, которые вы хотите экспонировать с помощью интеграции командной строки.

Общий формат вызова функции API MySQL Shell из командной строки:

$ mysqlsh [shell options] -- [shell_object]+ object_function [anonymous_arguments|named arguments]*

Где:

shell_object: определяет глобальный объект с функциями, экспонированными для использования в командной строке. Поддерживает вложенные объекты в списке, разделённые пробелами.
object_function: определяет функцию API последнего shell_object, которая должна быть выполнена.
[anonymous_arguments|named arguments]*: определяет аргументы, передаваемые в вызов object_function

Для большинства доступных API требуется один объект, например:

$ mysqlsh -- shell status

Но для вложенных объектов список объектов должен быть указан. Например, для вызова функции, экспонируемой shell.options, такой как setPersist(optionName, value), используйте синтаксис:

$ mysqlsh -- shell options set-persist defaultMode py

Аналогичная ситуация может возникнуть с вложенными объектами, определёнными в плагинах MySQL Shell.

Передаваемые вами аргументы функций можно разделить на следующие типы:

Безымянные аргументы: это сырые значения, предоставляемые команде. Например, в следующем вызове 1, one и true являются безымянными аргументами:
```
$ mysqlsh -- object command 1 one true
```
Именованные аргументы: это пары ключ-значение, предоставляемые в форме --key=value. Например, в следующем вызове --sample и --path являются именованными аргументами:
```
$ mysqlsh -- object command 1 one true --sample=3 --path=some/path
```

Учитывая это разделение аргументов, общий формат вызова функции API из интеграции командной строки:

$ mysqlsh [shell options] -- object command [anonymous arguments][named arguments]

Порядок любых anonymous arguments важен, поскольку они обрабатываются позиционно. С другой стороны, named arguments могут появляться где угодно, так как они обрабатываются первыми и связываются с соответствующим параметром. После обработки именованных аргументов безымянные аргументы обрабатываются позиционно.