Навигация по интерфейсу командной строки Microsoft Graph (CLI)

Статья
11/07/2024

API Microsoft Graph огромен и постоянно растет. Поэтому количество команд в интерфейсе командной строки Microsoft Graph (CLI) также велико. Поиск подходящей команды для того, чего вы хотите достичь, может оказаться сложной задачей, особенно если вы еще не знакомы с Microsoft Graph. В этом разделе рассматриваются некоторые способы поиска конкретной команды.

Примечание.

Для некоторых запросов к ресурсам Microsoft Entra требуется использование расширенных возможностей запросов. Если вы получите ответ, указывающий на неправильный запрос, неподдерживаемый запрос или ответ, содержащий непредвиденные результаты, включая $count параметр запроса и ConsistencyLevel заголовок, может позволить запросу выполнить успешное выполнение. Дополнительные сведения и примеры см. в разделе Расширенные возможности запросов к объектам каталогов.

Соглашения об именовании команд

Команды в интерфейсе командной строки создаются непосредственно из REST API, поэтому на имена влияет API. Вам не нужно понимать подробности API, чтобы использовать Microsoft Graph CLI, но это помогает понять соглашение об именовании.

Команды Интерфейса командной строки Microsoft Graph представляют ресурсы в Microsoft Graph и действия, которые можно выполнить с этими ресурсами. Общая структура команд соответствует следующему шаблону:

mgc <path-to-resource> <action>

— <path-to-resource> это одна или несколько команд, которые соответствуют структуре URL-адреса целевого API. Является <action> последней командой в последовательности и указывает действие, которое необходимо выполнить с целевым ресурсом.

Путь к командам ресурсов

Путь к целевому ресурсу создается путем последовательности одной или нескольких команд для представления URL-адреса ресурса, как указано в REST API. Для простого API, например GET /me, достаточно одной команды (me) для представления пути.

Далее рассмотрим более сложный пример: API получения сообщений. Просмотрите HTTP-запросы для этого API. Если вы игнорируете запросы с /me в URL-адресе, существует два других способа вызова этого API.

GET /users/{id | userPrincipalName}/messages/{id}
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages/{id}

Эквивалентные команды CLI сопоставляют с сегментами в URL-адресах. Например, сегменты первого URL-адреса сопоставляется со следующими командами:

/users сопоставляется с users
/{id | userPrincipalName} сопоставляется с --user-id (подробнее об этом ниже)
/messages сопоставляется с messages
/{id} сопоставляется с --message-id

Если объединить все это вместе, эквивалентными командами будет users messages --user-id <user-id> --message-id <message-id>.

Доступ к элементу в коллекции

Сегменты URL-адресов в API, использующие существительное во множественном числе, указывают на коллекцию. Когда API работает с определенным элементом в этой коллекции, URL-адрес будет содержать сегмент с идентификатором. В предыдущем примере сегменты /users/{id | userPrincipalName} объединяются для доступа к определенному пользователю в коллекции пользователей. Эти "сегменты идентификаторов" представлены в Интерфейсе командной строки Microsoft Graph обязательным параметром идентификатора, который называется как --<name of resource>-id. Эти параметры отображаются после команды действия. Используйте параметр , --help чтобы просмотреть обязательные параметры для заданной команды.

Команды действий

Для базовых операций REST команда определяется методом HTTP, используемым для API.

Метод HTTP	Командная команда	Пример
GET (один элемент)	`get`	`mgc me get` Справочник по API
GET (коллекция)	`list`	`mgc users list` Справочник по API
POST	`create`	`mgc me messages create` Справочник по API
PUT	`put`	`mgc drives items content put` Справочник по API
PATCH	`patch`	`mgc me events patch` Справочник по API
DELETE	`delete`	`mgc drives items delete` Справочник по API

Рассмотрим пример API получения сообщений из предыдущего раздела. Путь к ресурсу представлен users messages, а метод HTTP для этого API — GET, возвращающий один элемент. Это означает, что результирующая команда для этого API имеет значение mgc users messages get --user-id <user-id> --message-id <message-id>.

Параметры перечисления

После того как вы найдете нужную команду, вы можете проверить все доступные параметры с помощью --help параметра . Например, следующая команда выводит список всех доступных mgc users messages get параметров для команды .

mgc users messages get --help

Поиск доступных команд

Иногда просто знать соглашения об именовании недостаточно, чтобы угадать правильную команду. В этом случае можно использовать --help параметр итеративно для поиска доступных команд в интерфейсе командной строки. Например, mgc --help возвращает полный список доступных команд, допустимых в качестве первой команды в последовательности. Вы можете выбрать одну из доступных команд, а затем добавить ее в предыдущую команду, чтобы найти команды следующего уровня.

Пример

$ mgc --help
Description:
  Microsoft Graph CLI

Usage:
  mgc [command] [options] [[--] <additional arguments>...]]

Options:
  -?, -h, --help  Show help and usage information
  --version       Show version information

Commands:
  admin
  agreement-acceptances
  agreements
  app-catalogs
  applications
  ...

$ mgc applications --help
Description:
  Provides operations to manage the collection of application entities.

Usage:
  mgc applications [command] [options]

Options:
  -?, -h, --help  Show help and usage information

Commands:
  add-key                             Provides operations to call the addKey method.
  add-password                        Provides operations to call the addPassword method.
  app-management-policies             Provides operations to manage the appManagementPolicies property of the
                                      microsoft.graph.application entity.
  check-member-groups                 Provides operations to call the checkMemberGroups method.
  ...

Поделиться через