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