Navigation dans l’interface de ligne de commande (CLI) Microsoft Graph

Article
11/07/2024

L’API Microsoft Graph est énorme et elle ne cesse de croître. Par conséquent, le nombre de commandes dans l’interface de ligne de commande (CLI) Microsoft Graph est également élevé. Trouver la commande appropriée pour ce que vous souhaitez accomplir peut être difficile, en particulier si vous n’êtes pas déjà familiarisé avec Microsoft Graph. Cette rubrique examine certaines façons de trouver une commande particulière.

Remarque

Certaines demandes de ressources Microsoft Entra nécessitent l’utilisation de fonctionnalités de requête avancées. Si vous obtenez une réponse indiquant une requête incorrecte, une requête non prise en charge ou une réponse qui inclut des résultats inattendus, y compris le paramètre de requête et ConsistencyLevel l’en-tête $count peut permettre à la requête de réussir. Pour plus d’informations et d’exemples, consultez Fonctionnalités de requête avancées sur les objets d’annuaire.

Conventions de nommage des commandes

Les commandes dans l’interface CLI étant générées directement à partir de l’API REST, les noms sont influencés par l’API. Vous n’avez pas besoin de comprendre les détails de l’API pour utiliser l’interface CLI Microsoft Graph, mais il est utile de comprendre la convention de nommage.

Les commandes CLI Microsoft Graph représentent les ressources dans Microsoft Graph et les actions qui peuvent être effectuées sur ces ressources. La structure générale des commandes suit ce modèle :

mgc <path-to-resource> <action>

est <path-to-resource> une ou plusieurs commandes qui suivent la structure d’URL de l’API cible. <action> est la dernière commande de la séquence et indique l’action à effectuer sur la ressource cible.

Chemin d’accès aux commandes de ressource

Le chemin d’accès à la ressource cible est construit en séquenceant une ou plusieurs commandes pour représenter l’URL de la ressource, comme spécifié par l’API REST. Pour une API simple comme GET /me, une seule commande (me) suffit pour représenter le chemin d’accès.

Examinez ensuite un exemple plus complexe : l’API get message. Examinez les requêtes HTTP pour cette API. Si vous ignorez les requêtes avec /me dans l’URL, il existe deux autres façons d’appeler cette API.

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

Les commandes CLI équivalentes sont mappées aux segments dans les URL. Par exemple, les segments de la première URL sont mappés aux commandes suivantes :

/users mappe à users
/{id | userPrincipalName} correspond à --user-id (plus d’informations ci-dessous)
/messages mappe à messages
/{id} mappe à --message-id

En mettant tout cela ensemble, les commandes équivalentes seraient users messages --user-id <user-id> --message-id <message-id>.

Accès à un élément d’une collection

Les segments d’URL dans une API qui utilisent un nom au pluriel indiquent une collection. Lorsqu’une API agit sur un élément spécifique de cette collection, l’URL contient un segment avec un ID. Dans l’exemple précédent, les segments /users/{id | userPrincipalName} se combinent pour accéder à un utilisateur spécifique dans la collection d’utilisateurs. Ces « segments d’ID » sont représentés dans l’interface CLI Microsoft Graph par une option d’ID obligatoire, nommée comme --<name of resource>-id. Ces options s’affichent après la commande d’action. Utilisez l’option --help pour afficher les options requises pour une commande donnée.

Commandes d’action

Pour les opérations REST de base, le verbe est déterminé par la méthode HTTP utilisée pour l’API.

Méthode HTTP	Verbe de commande	Exemple
GET (élément unique)	`get`	`mgc me get` Informations de référence sur l’API
GET (collection)	`list`	`mgc users list` Informations de référence sur l’API
POST	`create`	`mgc me messages create` Informations de référence sur l’API
PUT	`put`	`mgc drives items content put` Informations de référence sur l’API
PATCH	`patch`	`mgc me events patch` Informations de référence sur l’API
SUPPRIMER	`delete`	`mgc drives items delete` Informations de référence sur l’API

Considérez l’exemple d’API obtenir un message de la section précédente. Le chemin d’accès à la ressource est représenté par users messages, et la méthode HTTP pour cette API est GET, qui retourne un seul élément. Cela signifie que la commande obtenue pour cette API est mgc users messages get --user-id <user-id> --message-id <message-id>.

Liste des paramètres

Une fois que vous avez trouvé la commande appropriée, vous pouvez examiner tous les paramètres disponibles à l’aide de l’option --help . Par exemple, la commande suivante répertorie tous les paramètres disponibles pour la mgc users messages get commande .

mgc users messages get --help

Recherche des commandes disponibles

Parfois, il ne suffit pas de connaître les conventions d’affectation de noms pour deviner la bonne commande. Dans ce cas, vous pouvez utiliser l’option --help de manière itérative pour rechercher les commandes disponibles dans l’interface CLI. Par exemple, mgc --help retourne la liste complète des commandes disponibles qui sont valides en tant que première commande de la séquence. Vous pouvez choisir l’une des commandes disponibles, puis l’ajouter à la commande précédente pour rechercher le niveau de commande suivant.

Exemple

$ 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.
  ...

Partager via