5.8.2.2 Defining Arguments — MySQL Shell 9.2

5.8.2.2 Определение аргументов

Как упоминалось в разделе 5.8.2.1 «Интеграция командной строки для функций API MySQL Shell», большинство API, доступных в MySQL Shell, ожидают определённый тип данных для предоставляемых аргументов. Значения в аргументах командной строки могут быть предоставлены с использованием спецификации 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", оно должно быть определено в вызове командной строки как ""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 для параметра options в функции 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 --decodeColumns=myColumn=1

Дополнительные именованные аргументы

Как показано в предыдущем разделе, параметры словаря поддерживаются с помощью именованных аргументов, используя синтаксис --key=value. Существует еще один случай, когда аргументы должны быть указаны как именованные: параметры, которые определены после параметра списка. Наиболее удобный способ предоставить аргументы, относящиеся к параметру списка, — это использование анонимных аргументов, например, как показано в примере в списке аргументов:

$ 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