使用 Microsoft Graph 生成 PHP 应用
本教程介绍如何生成使用 Microsoft 图形 API 的 PHP 控制台应用。
提示
如果只希望下载已完成的教程,可以下载或克隆GitHub存储库。
先决条件
在开始本教程之前,应在开发计算机上安装 PHP 和Composer。
你还应拥有包含 Outlook.com 上的邮箱的个人 Microsoft 帐户,或者 Microsoft 工作或学校帐户。 如果没有 Microsoft 帐户,可以使用以下几个选项来获取免费帐户:
- 可以 注册新的个人 Microsoft 帐户。
- 可以注册Microsoft 365开发人员计划以获取免费的Microsoft 365订阅。
备注
本教程是使用 PHP 版本 8.1.5 和 2.3.5 版Composer编写的。 本指南中的步骤可能适用于其他版本,但尚未进行测试。
在门户中注册该应用
在本练习中,你将在Azure Active Directory中注册一个新应用程序,以启用用户身份验证。 可以使用Azure Active Directory管理中心或使用 Microsoft Graph PowerShell SDK 注册应用程序。
注册应用程序以进行用户身份验证
在本部分中,你将注册一个应用程序,该应用程序将使用 设备代码流支持用户身份验证。
打开浏览器,并转到 Azure Active Directory 管理中心。然后,使用 个人帐户(亦称为“Microsoft 帐户”)或 工作或学校帐户 登录。
选择左侧导航栏中的“Azure Active Directory”,再选择“管理”下的“应用注册”。

选择“新注册”。 例如
PHP Graph Tutorial,输入应用程序的名称。根据需要设置 支持的帐户类型 。 选项包括:
选项 Who可以登录? 仅限此组织目录中的帐户 仅Microsoft 365组织中的用户 任何组织目录中的帐户 任何Microsoft 365组织中的用户 (工作或学校帐户) 任何组织目录中的帐户...和个人 Microsoft 帐户 任何Microsoft 365组织中的用户 (工作或学校帐户) 和个人 Microsoft 帐户 保留“重定向 URI”为空。
选择“注册”。 在应用程序的 “概述 ”页上,复制应用程序 (客户端) ID 的值并将其保存,下一步将需要它。 如果仅针对 受支持的帐户类型 选择 此组织目录中的 帐户,请复制 目录 (租户) ID 并保存它。

选择“管理”下的“身份验证”。 找到 “高级设置” 部分,将 “允许公共客户端流 ”切换为 “是”,然后选择 “保存”。

备注
请注意,你未配置任何 Microsoft Graph对应用注册的权限。 这是因为示例将使用 动态许可 请求用户身份验证的特定权限。
创建 PHP 控制台应用
首先初始化新的Composer项目。 在要在其中创建项目的目录中打开命令行接口 (CLI) 。 运行以下命令:
composer init
回答提示。 可以接受大多数问题的默认值,但应回答 n 以下问题:
Would you like to define your dependencies (require) interactively [yes]? n
Would you like to define your dev dependencies (require-dev) interactively [yes]? n
Add PSR-4 autoload mapping? Maps namespace "Microsoft\Graphtutorial" to the entered relative path. [src/, n to skip]: n
安装依赖项
在继续操作之前,请添加一些稍后将使用的附加依赖项。
- Microsoft Graph SDK for PHP 来调用 Microsoft Graph。
- 用于从 .env 文件读取环境变量的 vlucas/phpdotenv。
在 CLI 中运行以下命令以安装依赖项。
composer require microsoft/microsoft-graph vlucas/phpdotenv
加载应用程序设置
在本部分中,你将向项目添加应用注册的详细信息。
在项目的根目录中创建名为 .env 的文件,并添加以下代码。
根据下表更新值。
设置 值 CLIENT_ID应用注册的客户端 ID AUTH_TENANT如果选择仅允许组织中的用户登录的选项,请将此值更改为租户 ID。 否则,请保留为 common.重要
如果你使用的是源代码管理(如 git),现在最好从源代码管理中排除 .env 文件,以避免无意中泄露应用 ID。
设计应用
在本部分中,你将创建一个简单的基于控制台的菜单。
在项目根目录中创建名为 main.php 的文件。 添加打开和关闭 PHP 标记。
<?php ?>在 PHP 标记之间添加以下代码。
在结束 PHP 标记之前,在文件末尾添加以下占位符方法。 你将在后续步骤中实现它们。
function initializeGraph(): void { // TODO } function greetUser(): void { // TODO } function displayAccessToken(): void { // TODO } function listInbox(): void { // TODO } function sendMail(): void { // TODO } function listUsers(): void { // TODO } function makeGraphCall(): void { // TODO }
这会实现基本菜单,并从命令行读取用户的选择。
添加用户身份验证
在本部分中,将从上一练习扩展应用程序,以支持使用 Azure AD 进行身份验证。 这是获取调用 Microsoft Graph 所需的 OAuth 访问令牌所必需的。
为用户身份验证配置Graph客户端
在本部分中, GuzzleHttp\Client 你将使用该类通过设备 代码流请求访问令牌。
在项目根目录中创建名为 GraphHelper.php 的新文件。 添加以下代码。
<?php use Microsoft\Graph\Graph; use Microsoft\Graph\Http; use Microsoft\Graph\Model; use GuzzleHttp\Client; class GraphHelper { } ?>将以下代码添加到
GraphHelper类。将 main.php 中的空
initializeGraph函数替换为以下内容。
此代码从 .env 文件加载信息,并初始化两个属性,一个 Client 对象和一个 Graph 对象。 该Client对象将用于请求访问令牌,该Graph对象将用于调用 Microsoft Graph。
测试 DeviceCodeCredential
接下来,添加代码以从中 GraphHelper获取访问令牌。
将以下函数添加到
GraphHelper类。将 main.php 中的空
displayAccessToken函数替换为以下内容。生成并运行应用。 在系统提示输入选项时输入
1。 应用程序显示 URL 和设备代码。$ php main.php PHP Graph Tutorial Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 1 To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code RB2RUD56D to authenticate.打开浏览器并浏览到显示的 URL。 输入提供的代码并登录。
重要
请注意浏览到浏览器时登录到浏览器的任何
https://microsoft.com/devicelogin现有Microsoft 365帐户。 使用浏览器功能(例如配置文件、来宾模式或专用模式)来确保将身份验证为要用于测试的帐户。完成后,返回到应用程序以查看访问令牌。
提示
仅 出于验证和调试目的,只能使用 Microsoft 的联机令牌分析器 https://jwt.ms解码工作或学校帐户的用户访问令牌 () 。 如果在调用 Microsoft Graph 时遇到令牌错误,这可能很有用。 例如,验证
scp令牌中的声明是否包含预期的 Microsoft Graph权限范围。
获取用户
在本部分中,你将将 Microsoft Graph合并到应用程序中。 对于此应用程序,你将使用 Microsoft Graph SDK for PHP 来调用 Microsoft Graph。
将以下代码添加到
GraphHelper类。将 main.php 中的空
greetUser函数替换为以下内容。
如果现在运行应用,则在登录应用后,欢迎你按名称操作。
Hello, Megan Bowen!
Email: MeganB@contoso.com
代码解释
考虑函数中的 getUser 代码。 这只是几行,但有一些关键详细信息需要注意。
访问“me”
该函数生成对 Get 用户 API 的请求。 可通过以下两种方式访问此 API:
GET /me
GET /users/{user-id}
在这种情况下,代码将调用 GET /me API 终结点。 这是一种快捷方式,用于在不知道用户 ID 的情况下获取经过身份验证的用户。
备注
GET /me由于 API 终结点获取经过身份验证的用户,因此它仅适用于使用用户身份验证的应用。 仅限应用的身份验证应用无法访问此终结点。
请求特定属性
该函数使用 $select查询参数 指定所需的属性集。
强类型返回类型
该函数从 API 返回 User 从 JSON 响应反序列化的对象。 由于代码使用 $select,因此仅请求的属性在返回 User 的对象中具有值。 所有其他属性都将具有默认值。
列出收件箱
在本部分中,你将添加在用户的电子邮件收件箱中列出邮件的功能。
将以下代码添加到
GraphHelper类。将 main.php 中的空
listInbox函数替换为以下内容。运行应用、登录并选择选项 2 以列出收件箱。
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 2 Message: Updates from Ask HR and other communities From: Contoso Demo on Yammer Status: Read Received: Mon, 18 Apr 2022 14:24:16 +0000 Message: Employee Initiative Thoughts From: Patti Fernandez Status: Read Received: Mon, 18 Apr 2022 13:52:03 +0000 Message: Voice Mail (11 seconds) From: Alex Wilber Status: Unread Received: Wed, 13 Apr 2022 02:30:27 +0000 Message: Our Spring Blog Update From: Alex Wilber Status: Unread Received: Tue, 12 Apr 2022 16:46:01 +0000 Message: Atlanta Flight Reservation From: Alex Wilber Status: Unread Received: Mon, 11 Apr 2022 13:39:10 +0000 Message: Atlanta Trip Itinerary - down time From: Alex Wilber Status: Unread Received: Fri, 08 Apr 2022 18:36:01 +0000 ... More messages available? True
代码解释
考虑函数中的 getInbox 代码。
访问已知邮件文件夹
该函数将传递 /me/mailFolders/inbox/messages 给请求生成器,后者生成对 列表消息 API 的请求。 由于它包含段 /mailFolders/inbox ,因此 API 只会返回请求的邮件文件夹中的邮件。 在这种情况下,由于收件箱是用户邮箱中的默认已知文件夹,因此可通过其已知名称访问该收件箱。 通过将已知名称替换为邮件文件夹的 ID 属性,以相同的方式访问非默认文件夹。 有关可用的已知文件夹名称的详细信息,请参阅 mailFolder 资源类型。
访问集合
getUser与上一部分返回单个对象的函数不同,此方法返回消息集合。 Microsoft Graph中返回集合的大多数 API 不会在单个响应中返回所有可用结果。 相反,它们使用 分页 返回部分结果,同时为客户端提供请求下一个“页面”的方法。
默认页面大小
使用分页的 API 实现默认页面大小。 对于消息,默认值为 10。 客户端可以使用$top查询参数请求更多 (或更少 ) 。 在 getInbox请求生成器上使用方法完成 setPageSize 此操作。
备注
传入的 setPageSize 值是上限,而不是显式数字。 API 将返回一些消息 ,直至 指定的值。
获取后续页面
如果服务器上有更多可用的结果,则集合响应包括一个 @odata.nextLink 具有 API URL 的属性,用于访问下一页。 PHP SDK 将此信息公开为 isEnd 集合请求对象上的方法。 如果此方法返回 false,则有更多的结果可用。 方法可以访问 getPage 下一页。
集合排序
该函数使用 $orderby查询参数 请求按消息接收时间排序的结果 (receivedDateTime 属性) 。 它包括 DESC 关键字,以便首先列出最近收到的消息。
发送邮件
在本部分中,你将添加以经过身份验证的用户发送电子邮件的功能。
将以下代码添加到
GraphHelper类。将 main.php 中的空
sendMail函数替换为以下内容。运行应用、登录并选择选项 3 以向自己发送电子邮件。
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 3 Mail sent.备注
如果要从Microsoft 365开发人员计划中测试开发人员租户,则可能无法传递您发送的电子邮件,并且可能会收到未送达报告。 如果发生这种情况,请通过Microsoft 365 管理中心联系支持人员。
代码解释
考虑函数中的 sendMail 代码。
发送邮件
该函数将传递 /me/sendMail 给请求生成器,后者生成发送 邮件 API 的请求。 请求生成器采用包含要发送的消息的请求正文。
创建对象
与之前对仅读取数据的 Microsoft Graph的调用不同,此调用会创建数据。 若要使用客户端库执行此操作,请创建一个代表数据的关联数组,设置所需的属性,然后在 API 调用中发送它。 由于调用正在发送数据, POST 因此将使用该方法,而不是 GET使用该方法。
可选:配置仅限应用的身份验证
在本部分中,你将更新上一部分中的应用注册,以支持 仅限应用的身份验证。 仅限应用的身份验证是后台服务的一个不错选择,还有一些 API 仅支持仅限应用的身份验证。 如果打算使用本教程的仅限应用的部分,则只需完成本部分。 如果没有,可以安全地跳到下一步。
重要
Microsoft Graph Go SDK 目前Community预览版。 在此期间,预计会发生重大更改。 本教程是使用版本 0.19.1 编写的。
重要
本部分中的步骤需要具有全局管理员角色的工作/学校帐户。
在 Azure AD 管理中心打开上一部分中的应用注册。
在“管理”下选择 “API 权限”。
通过选择其行中的省略号 (...) 并选择“删除权限”,删除配置权限下 的 默认 User.Read 权限。
选择 “添加权限”,然后 选择 Microsoft Graph。
选择 应用程序权限。
选择 User.Read.All,然后选择 “添加权限”。
选择 “授予管理员同意...”,然后选择 “是 ”以为所选权限提供管理员同意。

在 “管理” 下选择 “证书和机密”,然后选择 “新建客户端机密”。
输入说明,选择持续时间,然后选择 “添加”。
从 “值 ”列复制机密,在后续步骤中需要它。
重要
此客户端密码不会再次显示,所以请务必现在就复制它。
备注
请注意,与注册用户身份验证时的步骤不同,在本部分中确实配置了 Microsoft Graph 应用注册权限。 这是因为仅应用身份验证使用 客户端凭据流,这要求对应用注册配置权限。 有关详细信息,请参阅 .default 范围 。
可选:添加仅限应用的身份验证
在本部分中,你将向应用程序添加仅限应用的身份验证。 本部分是可选的,需要完成 可选:配置仅限应用的身份验证。 这些步骤只能使用工作或学校帐户完成。
为仅限应用的身份验证配置Graph客户端
在本部分中,你将使用 客户端凭据流请求访问令牌。
根据下表更新 .env 中的值。
设置 值 TENANT_ID组织的租户 ID CLIENT_SECRET上一步中生成的客户端机密 将以下函数添加到 GraphHelper.php。
可选:列出用户
在本部分中,你将添加使用仅应用身份验证列出Azure Active Directory中所有用户的功能。 本部分是可选的,需要完成 可选:配置仅限应用的身份验证 和 可选:添加仅限应用的身份验证。 这些步骤只能使用工作或学校帐户完成。
将以下代码添加到
GraphHelper类。将 main.php 中的空
listUsers函数替换为以下内容。运行应用、登录并选择选项 4 列出用户。
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 4 User: Adele Vance ID: 05fb57bf-2653-4396-846d-2f210a91d9cf Email: AdeleV@contoso.com User: Alex Wilber ID: a36fe267-a437-4d24-b39e-7344774d606c Email: AlexW@contoso.com User: Allan Deyoung ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0 Email: AllanD@contoso.com User: Bianca Pisani ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Email: NO EMAIL User: Brian Johnson (TAILSPIN) ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Email: BrianJ@contoso.com ... More users available? true
代码解释
考虑函数中的 getUsers 代码。 它与以下代码 getInbox非常相似:
- 它获取用户的集合
- 它用于
$select请求特定属性 - 它用于
setPageSize限制返回的用户数 - 它用于
$orderBy对响应进行排序
关键区别在于,此代码使用而不是$userClient使用 $appClient。 两个客户端使用相同的语法和请求生成器,但配置了不同的凭据。
可选:添加自己的代码
在本部分中,你将向应用程序添加自己的 Microsoft Graph 功能。 这可能是 Microsoft Graph文档或Graph资源管理器或你创建的代码的代码片段。 本部分是可选的。
更新应用
将以下代码添加到
GraphHelper类。将 main.php 中的空
makeGraphCall函数替换为以下内容。
选择 API
在 Microsoft Graph中查找要尝试的 API。 例如, 创建事件 API。 可以使用 API 文档中的一个示例,或创建自己的 API 请求。
配置权限
检查所选 API 参考文档的 “权 限”部分,查看支持哪些身份验证方法。 例如,某些 API 不支持仅限应用或个人 Microsoft 帐户。
- 若要使用用户身份验证调用 API (如果 API 支持用户 (委派) 身份验证) ,请在 .env 中添加所需的权限范围。
- 若要使用仅应用身份验证调用 API, (API 是否支持) ,请在 Azure AD 管理中心中添加所需的权限范围。
添加代码
将代码添加到 makeGraphCall GraphHelper.php 中的函数中。
恭喜!
你已完成 PHP Microsoft Graph 教程。 现在,你有一个调用 Microsoft Graph 的工作应用,可以试验和添加新功能。 请访问 Microsoft Graph概述,查看可以使用 Microsoft Graph 访问的所有数据。
PHP 示例
你有关于此部分的问题? 如果有,请向我们提供反馈,以便我们对此部分作出改进。