Azure Sphere CLI
Пакет SDK для Azure Sphere предоставляет интерфейс командной строки (CLI) Azure Sphere, доступный в PowerShell, командной строке Windows или командной оболочке Linux. Azure Sphere CLI — это набор команд, используемых для создания ресурсов Azure Sphere и управления ими.
Интерфейс командной строки Azure Sphere устанавливается вместе с классическим интерфейсом командной строки Azure Sphere в Windows и Linux, поэтому у вас есть доступ к обоим интерфейсам. Чтобы использовать Azure Sphere CLI, выполните следующие действия.
- В Windows используйте PowerShell или стандартную командную строку Windows.
- В Linux используйте любую командную оболочку.
Запуск Интерфейса командной строки Azure Sphere
Теперь вы можете запустить Azure Sphere CLI с azsphere помощью команды из командной строки Windows или PowerShell. Мы рекомендуем Использовать PowerShell, так как он предлагает функцию завершения вкладки , которая недоступна в командной строке Windows.
В Linux azure Sphere CLI можно запустить из любого интерфейса командной строки (CLI). Во время установки отображается уведомление, позволяющее задать Azure Sphere CLI или классический интерфейс командной строки Azure Sphere в качестве предпочтительной версии интерфейса командной строки по умолчанию.
Введите Yes , чтобы выбрать Azure Sphere CLI, или тип No для использования классического интерфейса командной строки Azure Sphere. Дополнительные сведения см. в статье Установка пакета SDK azure Sphere .
Примечание
Краткая форма для команд не поддерживается в версии Azure Sphere CLI. Для просмотра списка доступных команд рекомендуется использовать функцию завершения табуляции . В Windows ярлык командной строки классического разработчика Azure Sphere можно использовать только с классической командной строкой Azure Sphere.
Функции ввода CLI
В этом разделе описываются функции ввода, доступные в Azure Sphere CLI:
Команды
Все команды в Azure Sphere CLI начинаются с azsphere. Например:
azsphere login
---------------------
Name
=====================
bob@contoso.com
---------------------
Поиск команд
Команды в cli организованы по группам. Полные справочные сведения о доступных командах и параметрах можно просмотреть с помощью --help классического интерфейса командной строки Azure Sphere и Azure Sphere CLI.
Полный список команд можно получить, выполнив команду azsphere --help.
Например:
- Для классического интерфейса командной строки Azure Sphere используйте или
azsphere --helpazsphere -? - Для Azure Sphere CLI используйте или
azsphere --helpazsphere -h
Параметры
Имя параметра предшествует двойным дефисам (--), которые сигналит о том, что слово, следующее за дефисом, является параметром. Используйте пробел для разделения имени и значения параметра. Параметры, которые являются составными словами, разделяются дефисом (-) в новом интерфейсе командной строки.
Например, --component-id или --application-update
Упрощенная идентификация объектов
В Azure Sphere CLI используется один параметр для идентификации каждого типа объекта. Это означает, что можно указать идентификатор, имя, IP-адрес или расположение, применимые к этому параметру.
Например, можно использовать идентификатор клиента или имя клиента в следующей команде:
azsphere device list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
Или
azsphere device list --tenant MyTenant
Это реализовано для --deviceпараметров , --tenant, --productи --device-group .
Например:
azsphere device-group update --device-group CoffeeMaker/Development
------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- -------------------------
Id TenantId OsFeedType ProductId Name Description UpdatePolicy AllowCrashDumpsCollection
===============================================================================================================================================================================================================================================
7f860cc1-4949-4000-a541-9a988ba4c3cd 143adbc9-1bf0-4be2-84a2-084a331d81cb Retail 6f52bead-700d-4289-bdc2-2f11f774270e Marketing Marketing device group Accept all updates from the Azure Sphere Security Service. False
------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- -------------------------
Несколько значений
Некоторые команды разрешают несколько значений для одного параметра. В этом случае можно либо указать параметр с каждым значением, либо один параметр, за которым следует список значений, разделенных пробелами. Например, следующие две команды эквивалентны:
azsphere image-package pack-application --package-directory myDirectory --destination myImagePackage --executables filepath-1 --executables filepath-2
azsphere image-package pack-application --package-directory myDirectory --destination myImagePackage --executables filepath-1 filepath-2
Обязательные и необязательные параметры
При выполнении azsphere <command> <sub-command> --help отображается список параметров, применимых к этой команде. Параметр [Обязательно] указывает, является ли параметр обязательным для успешного выполнения команды. Все остальные параметры являются необязательными.
Если требуемый параметр отсутствует, вам будет предложено ввести значение параметра.
Например:
azsphere role delete --help
Command
azsphere role delete : Deletes a role from a user in the current Azure Sphere tenant.
Arguments
--role -r [Required] : Role to be deleted. Values from: azsphere role show-types.
--user -u [Required] : The user from whom the role is being deleted. Specify user e-mail.
Values from: azsphere role list.
Tenant Selection Arguments
--tenant -t : The tenant to perform this operation in. Overrides the default selected
tenant. Specify tenant ID or tenant name. Values from: azsphere tenant
list.
Global Arguments
--debug : Increase logging verbosity to show all debug logs.
--help -h : Show this help message and exit.
--only-show-errors : Only show errors, suppressing warnings.
--output -o : Output format. Allowed values: json, jsonc, none, table, tsv, yaml,
yamlc. Default: table.
--query : JMESPath query string. See http://jmespath.org/ for more information and
examples.
--verbose : Increase logging verbosity. Use --debug for full debug logs.
Пути ввода и вывода
В Azure Sphere CLI имена параметров, используемые для указания пути и имени файла, были обновлены, чтобы они были соответствующими контексту команды.
Например:
azsphere image-package pack-application --package-directory C:\AppSamples\LocalSamples\HelloWorld\HelloWorld_HighLevelApp\out\ARM-Debug\approotHelloWorld_HighLevelApp --destination myimage.imagepackage
Здесь указывает входной каталог для пакета, --package-directory а --destination параметр — путь и имя файла для результирующего пакета изображения.
Завершение вкладки
Заполнение вкладки позволяет автоматически завершить запись команды в интерфейсе командной строки. На вкладке Azure Sphere CLI заполнение поддерживается для групп, команд, имен параметров и значений параметров. Введите несколько символов команды и нажмите клавишу TAB , чтобы выбрать нужный текст завершения. Если несколько элементов начинаются с первоначально введенного текста, продолжайте нажимать клавишу TAB , пока не появится нужный элемент.
В Windows PowerShell 7.1 предлагает функцию завершения вкладок, которая недоступна в командной строке Windows.
Чтобы включить заполнение табуляции в Windows PowerShell, выполните команду Import-Module -name AzsphereCli.
Эта команда включает завершение табуляции только для сеанса. Вы можете добавить скрипт в профиль PowerShell , чтобы настроить среду и включить завершение табуляции для каждого запускаемого сеанса PowerShell.
В Linux Azure Sphere CLI поддерживает функцию завершения вкладок для команд в оболочке Bash.
Кроме того, автозавершение помогает обнаруживать доступные для использования команды, параметры и значения параметров. Для этого используется клавиши CTRL+ПРОБЕЛ в Windows PowerShell или дважды нажмите клавишу TAB в оболочке Linux Bash.
Например, введите команду azsphere product update и используйте функцию автозаполнения, чтобы просмотреть список доступных параметров.
Аналогичным образом введите azsphere product update --product и используйте автозаполнение, чтобы просмотреть список доступных продуктов в клиенте.
Интерактивный режим (предварительная версия)
Важно
Эта функция доступна в предварительной версии. Она может быть изменена или удалена в будущем выпуске.
Новый интерфейс командной строки предлагает интерактивный режим, который автоматически отображает справочные сведения и упрощает выбор команд, вложенных команд, параметров и значений параметров. Войдите в интерактивный режим с помощью команды azsphere interactive . Командная строка изменится на azsphere>> , чтобы указать, что вы теперь выполняете команды в интерактивной оболочке.
Дополнительные сведения см. в статье Интерактивный режим Azure Sphere CLI.
Функции вывода ИНТЕРФЕЙСА командной строки
В этом разделе описываются функции вывода, доступные в Azure Sphere CLI:
- Поддерживаемые форматы выходных данных
- Перенаправление и разбиение на страницы
- Выходные данные команды cli запроса
В следующих разделах описываются функции вывода, доступные в новом интерфейсе командной строки.
Поддерживаемые форматы выходных данных
Доступные форматы выходных данных в новом интерфейсе командной строки: json, jsonc (цветной JSON), tsv (значения, разделенные табуляциями), table (доступные для чтения таблицы ASCII) и yaml. По умолчанию CLI выводит .table Дополнительные сведения о доступных форматах вывода см. в статье Поддерживаемые форматы вывода для Azure Sphere CLI.
Перенаправление и разбиение на страницы
Azure Sphere CLI не поддерживает интерактивное разбиение на страницы. Однако стандартные выходные данные команды можно перенаправить в файл. В следующем примере для командной строки Windows, Windows PowerShell и оболочки Linux Bash стандартные выходные данные отправляются в output.txt, а стандартная ошибка отправляется в logs.txt.
azsphere device list --verbose > output.txt 2> logs.txt
Вы также можете разбить выходные данные на страницы на экране, перейдя в существующие средства разбиения на страницы.
Например:
- В PowerShell (Windows):
azsphere device list | Out-Host –Paging - В командной строке (Windows):
azsphere device list | more - В оболочке Bash (Linux):
azsphere device list | less
Примечание
Эта операция может выполняться медленно в зависимости от объема возвращаемых данных.
Дополнительные сведения о разбиении на страницы для классического интерфейса командной строки Azure Sphere см. в статье Разбиение на страницы и перенаправление результатов.
Выходные данные команды cli запроса
Azure Sphere CLI использует --query аргумент для выполнения запроса JMESPath по результатам команд. JMESPath — это язык запросов для JSON, предоставляющий возможность выбирать и изменять данные из выходных данных CLI. Запросы выполняются в выходных данных JSON перед форматированием отображения.
Аргумент --query поддерживается всеми командами в Azure Sphere CLI. Дополнительные сведения и примеры см. в руководстве по JMESPath и запросе выходных данных команды Azure CLI .
Обратная совместимость
Интерфейс командной строки поддерживает обратную совместимость. В каждом выпуске мы стремимся поддерживать обратную совместимость как для входных данных (имена команд, имена параметров, значения параметров), так и для их выходных данных в JSON и YAML. В случаях, когда такая совместимость невозможна, мы предоставим уведомление по крайней мере за 6 месяцев до внесения изменений. Дополнительные сведения см. в статье Важные изменения (функции снятия с учета) в Azure Sphere CLI.
Коды выхода
Успешная команда возвращает ноль. Любое ненулевое значение можно интерпретировать как код ошибки. После успешного выполнения выходные данные JSON и YAML имеют обратную совместимость договорных гарантий.
Предоставление отзывов
Если вы нашли ошибку в Azure Sphere, сообщите о проблеме на сайте GitHub. Чтобы отправить отзыв из командной строки, используйте команду обратной связи.
Эффективное использование Azure Sphere CLI
Azure Sphere CLI можно использовать из Bash, PowerShell или из окна командной строки. Вот несколько советов по использованию интерфейса командной строки.
- Использование кавычек в значениях. Если вы предоставляете параметру значение, содержащее пробелы, заключите его в кавычки. В Bash или PowerShell интерпретируются как одиночные, так и двойные кавычки. В командной строке Windows интерпретируются только двойные кавычки. Одинарные кавычки интерпретируются как часть значения. Например,
azsphere product create --name "My Fridge Product". Дополнительные сведения см. в разделе Кавычки и escape-символы. - Многие команды Azure Sphere отображают сведения в консоли в формате по умолчанию
table. Например,azsphere product device-group list --product DW100. Иногда отображаемая информация не подходит для консоли. Это может вызвать проблемы, если вы хотите скопировать и вставить сведения. Рекомендуется использовать следующие варианты:- Измените размер консоли и запустите команду еще раз.
- Используйте выходные данные JSON для кратких выходных данных и создания скриптов. Например,
azsphere product device-group list --product DW100 --output json. - Используйте заполнение табуляции в Windows PowerShell или оболочке Bash для автоматического завершения записи команды.
- Используйте интерактивный режим , который предоставляет интерактивную среду для автоматического отображения информации и упрощает выбор команд и вложенных команд. Войдите в интерактивный режим с помощью команды azsphere interactive . Командная строка изменится на azsphere>> , чтобы указать, что вы теперь выполняете команды в интерактивной оболочке.