使用英语阅读

通过


Microsoft Graph 命令行界面 (CLI)

Microsoft图形 API 非常庞大,并且一直都在增长。 因此,Microsoft Graph 命令行接口 (CLI) 中的命令数也很大。 为想要实现的目标找到正确的命令可能具有挑战性,尤其是在不熟悉 Microsoft Graph 的情况下。 本主题介绍帮助查找特定命令的一些方法。

备注

Microsoft Entra 资源的一些请求需要使用高级查询功能。 如果收到指示错误请求、不支持的查询或包含意外结果的响应(包括 $count 查询参数和 ConsistencyLevel 标头)的响应,则请求可能会成功。 有关详细信息和示例,请参阅 目录对象的高级查询功能

命令命名约定

CLI 中的命令直接从 REST API 生成,因此名称受 API 影响。 无需了解 API 的详细信息就可以使用 Microsoft Graph CLI,但有助于了解命名约定。

Microsoft Graph CLI 命令表示 Microsoft Graph 中的资源以及可对这些资源执行的操作。 命令的常规结构遵循此模式:

mgc <path-to-resource> <action>

<path-to-resource>是遵循目标 API 的 URL 结构的一个或多个命令。 <action>是序列中的最后一个命令,指示对目标资源执行的操作。

资源命令的路径

目标资源的路径是通过对一个或多个命令进行排序来构造的,以表示资源 URL,如 REST API 所指定。 对于像 这样的 GET /me简单 API,单个命令 (me) 就足以表示路径。

接下来,查看更复杂的示例: 获取消息 API。 查看此 API 的 HTTP 请求。 如果忽略 URL 中带有 /me 的请求,还有两种其他方法可以调用此 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>

访问集合中的项

API 中使用复数名词的 URL 段表示集合。 当 API 对该集合中的特定项执行操作时,URL 将包含具有 ID 的段。 在前面的示例中,段 /users/{id | userPrincipalName} 组合在一起以访问用户集合中的特定用户。 这些“ID 段”在 Microsoft Graph CLI 中由所需的 ID 选项表示,该选项的名称类似于 --<name of resource>-id。 这些选项显示在操作命令 后面--help使用 选项查看给定命令的必需选项。

操作命令

对于基本 REST 操作,谓词由用于 API 的 HTTP 方法确定。

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表示,此 API 的 HTTP 方法是 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 选项在 CLI 中搜索可用命令。 例如, 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.
  ...