Navegación por la interfaz de línea de comandos (CLI) de Microsoft Graph

Artículo
11/07/2024

Microsoft Graph API es enorme y está creciendo todo el tiempo. Por lo tanto, el número de comandos de la interfaz de línea de comandos (CLI) de Microsoft Graph también es grande. Encontrar el comando adecuado para lo que quiere lograr puede ser un desafío, especialmente si aún no está familiarizado con Microsoft Graph. En este tema se examinan algunas maneras de ayudar a encontrar un comando determinado.

Nota:

Algunas solicitudes de recursos de Microsoft Entra requieren el uso de funcionalidades avanzadas de consulta. Si recibe una respuesta que indica una solicitud incorrecta, una consulta no admitida o una respuesta que incluye resultados inesperados, incluidos el parámetro y ConsistencyLevel el $count encabezado de consulta, puede permitir que la solicitud se realice correctamente. Para obtener detalles y ejemplos, consulte Funcionalidades avanzadas de consulta en objetos de directorio.

Convenciones de nomenclatura de comandos

Los comandos de la CLI se generan directamente desde la API REST, por lo que la API influye en los nombres. No es necesario comprender los detalles de la API para usar la CLI de Microsoft Graph, pero ayuda a comprender la convención de nomenclatura.

Los comandos de la CLI de Microsoft Graph representan los recursos de Microsoft Graph y las acciones que se pueden realizar en esos recursos. La estructura general de los comandos sigue este patrón:

mgc <path-to-resource> <action>

<path-to-resource> es uno o más comandos que siguen la estructura de dirección URL de la API de destino. <action> es el comando final de la secuencia e indica la acción que se va a realizar en el recurso de destino.

Ruta de acceso a los comandos de recursos

La ruta de acceso al recurso de destino se construye mediante la secuenciación de uno o varios comandos para representar la dirección URL del recurso, tal y como especifica la API REST. Para una API simple como GET /me, un único comando (me) es suficiente para representar la ruta de acceso.

A continuación, examine un ejemplo más complejo: la API get message. Examine las solicitudes HTTP de esta API. Si omite las solicitudes con /me en la dirección URL, hay otras dos maneras de llamar a esta API.

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

Los comandos equivalentes de la CLI se asignan a los segmentos de las direcciones URL. Por ejemplo, los segmentos de la primera dirección URL se asignan a los siguientes comandos:

/users asigna a users
/{id | userPrincipalName} asigna a --user-id (más información sobre esto a continuación)
/messages asigna a messages
/{id} asigna a --message-id

Al combinarlo todo, los comandos equivalentes serían users messages --user-id <user-id> --message-id <message-id>.

Acceso a un elemento de una colección

Los segmentos de dirección URL de una API que usan un sustantivo plural indican una colección. Cuando una API actúa en un elemento específico de esa colección, la dirección URL contendrá un segmento con un identificador. En el ejemplo anterior, los segmentos /users/{id | userPrincipalName} se combinan para tener acceso a un usuario específico de la colección de usuarios. Estos "segmentos de identificador" se representan en la CLI de Microsoft Graph mediante una opción de identificador necesaria, que se denomina como --<name of resource>-id. Estas opciones aparecen después del comando de acción. Use la --help opción para ver las opciones necesarias para un comando determinado.

Comandos de acción

En el caso de las operaciones REST básicas, el verbo viene determinado por el método HTTP usado para la API.

Método HTTP	Verbo de comando	Ejemplo
GET (elemento único)	`get`	`mgc me get` Referencia de API
GET (colección)	`list`	`mgc users list` Referencia de API
POST	`create`	`mgc me messages create` Referencia de API
PUT	`put`	`mgc drives items content put` Referencia de API
PATCH	`patch`	`mgc me events patch` Referencia de API
DELETE	`delete`	`mgc drives items delete` Referencia de API

Considere el ejemplo get message API de la sección anterior. La ruta de acceso al recurso se representa mediante users messagesy el método HTTP para esta API es GET, devolviendo un solo elemento. Esto significa que el comando resultante para esta API es mgc users messages get --user-id <user-id> --message-id <message-id>.

Enumeración de parámetros

Una vez que haya encontrado el comando correcto, puede examinar todos los parámetros disponibles mediante la --help opción . Por ejemplo, el siguiente comando enumera todos los parámetros disponibles para el mgc users messages get comando.

mgc users messages get --help

Búsqueda de comandos disponibles

A veces, conocer las convenciones de nomenclatura no es suficiente para adivinar el comando correcto. En este caso, puede usar la --help opción de forma iterativa para buscar los comandos disponibles en la CLI. Por ejemplo, mgc --help devuelve la lista completa de comandos disponibles que son válidos como primer comando de la secuencia. Puede elegir uno de los comandos disponibles y, a continuación, agregarlo al comando anterior para buscar el siguiente nivel de comandos.

Ejemplo

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

Compartir a través de