Navegar na interface de linha de comandos (CLI) do Microsoft Graph

Artigo
11/07/2024

A Microsoft Graph API é enorme e está sempre a crescer. Por conseguinte, o número de comandos na interface de linha de comandos (CLI) do Microsoft Graph também é grande. Encontrar o comando certo para o que pretende alcançar pode ser um desafio, especialmente se ainda não estiver familiarizado com o Microsoft Graph. Este tópico analisa algumas formas de ajudar a encontrar um comando específico.

Observação

Alguns pedidos de recursos do Microsoft Entra requerem a utilização de capacidades de consulta avançadas. Se receber uma resposta a indicar um pedido incorreto, uma consulta não suportada ou uma resposta que inclua resultados inesperados, incluindo o parâmetro de consulta e ConsistencyLevel o $count cabeçalho, poderá permitir que o pedido seja bem-sucedido. Para obter detalhes e exemplos, veja Capacidades avançadas de consulta em objetos de diretório.

Convenções de nomenclatura de comandos

Os comandos na CLI são gerados diretamente a partir da API REST, pelo que os nomes são influenciados pela API. Não tem de compreender os detalhes da API para utilizar a CLI do Microsoft Graph, mas ajuda a compreender a convenção de nomenclatura.

Os comandos da CLI do Microsoft Graph representam recursos no Microsoft Graph e as ações que podem ser realizadas nesses recursos. A estrutura geral dos comandos segue este padrão:

mgc <path-to-resource> <action>

O <path-to-resource> é um ou mais comandos que seguem a estrutura de URL da API de destino. O <action> é o comando final na sequência e indica a ação a tomar no recurso de destino.

Caminho para comandos de recursos

O caminho para o recurso de destino é construído através da sequenciação de um ou mais comandos para representar o URL para o recurso, conforme especificado pela API REST. Para uma API simples como GET /me, um único comando (me) é suficiente para representar o caminho.

Em seguida, veja um exemplo mais complexo: a API get message. Veja os pedidos HTTP para esta API. Se ignorar os pedidos com /me no URL, existem duas outras formas de chamar esta API.

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

Os comandos equivalentes da CLI mapeiam para os segmentos nos URLs. Por exemplo, os segmentos do primeiro URL mapeiam para os seguintes comandos:

/users mapeia para users
/{id | userPrincipalName} mapeia para --user-id (mais informações abaixo)
/messages mapeia para messages
/{id} mapeia para --message-id

Juntando tudo isto, os comandos equivalentes seriam users messages --user-id <user-id> --message-id <message-id>.

Aceder a um item numa coleção

Os segmentos de URL numa API que utilizam um substantivo plural indicam uma coleção. Quando uma API atua num item específico nessa coleção, o URL irá conter um segmento com um ID. No exemplo anterior, os segmentos /users/{id | userPrincipalName} combinam-se para aceder a um utilizador específico na coleção de utilizadores. Estes "segmentos de ID" são representados na CLI do Microsoft Graph por uma opção de ID necessária, com o nome .--<name of resource>-id Estas opções são apresentadas após o comando de ação. Utilize a opção para ver as --help opções necessárias para um determinado comando.

Comandos de ação

Para operações REST básicas, o verbo é determinado pelo método HTTP utilizado para a API.

Método HTTP	Verbo de comando	Exemplo
GET (item único)	`get`	`mgc me get` Referência da API
GET (coleção)	`list`	`mgc users list` Referência da API
POST	`create`	`mgc me messages create` Referência da API
PUT	`put`	`mgc drives items content put` Referência da API
PATCH	`patch`	`mgc me events patch` Referência da API
DELETE	`delete`	`mgc drives items delete` Referência da API

Considere o exemplo da API get message da secção anterior. O caminho para o recurso é representado por users messagese o método HTTP para esta API é GET, devolvendo um único item. Isto significa que o comando resultante para esta API é mgc users messages get --user-id <user-id> --message-id <message-id>.

Parâmetros de listagem

Depois de encontrar o comando correto, pode examinar todos os parâmetros disponíveis com a opção --help . Por exemplo, o comando seguinte lista todos os parâmetros disponíveis para o mgc users messages get comando .

mgc users messages get --help

Localizar comandos disponíveis

Às vezes, saber apenas as convenções de nomenclatura não é suficiente para adivinhar o comando certo. Neste caso, pode utilizar a opção --help iterativamente para procurar os comandos disponíveis na CLI. Por exemplo, mgc --help devolve a lista completa de comandos disponíveis que são válidos como o primeiro comando na sequência. Pode escolher um dos comandos disponíveis e, em seguida, adicioná-lo ao comando anterior para encontrar o próximo nível de comandos.

Exemplo

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

Partilhar via