首页 > 营销学院 > 技术知识

PHP集成Google Admin SDK：通过服务账户列出用户所属群组的教程

本教程详细介绍了如何使用php和google admin sdk通过服务账户（service account）和域范围授权（domain-wide delegation）来获取特定用户所属的google群组列表。文章涵盖了客户端配置、权限设置、oauth流程以及如何正确进行用户模拟，以解决常见的`unauthorized_client`错误，确保api调用的成功。

在Google Workspace环境中，通过编程方式管理用户和群组是常见的需求。本教程将指导您如何使用PHP客户端库和Google Admin SDK来列出特定用户所属的所有Google群组。我们将重点讲解如何正确配置服务账户和域范围授权，以克服常见的认证和授权问题。

1. 环境准备与API配置

在开始编写PHP代码之前，您需要完成以下准备工作：

Google Cloud项目设置：
- 在Google Cloud Console中创建一个新项目或选择一个现有项目。
- 导航到“API和服务” > “库”，搜索并启用 Admin SDK API。
创建服务账户并生成JSON密钥文件：
- 在Google Cloud Console中，导航到“IAM和管理” > “服务账户”。
- 创建一个新的服务账户，并为其分配适当的角色，例如“项目” > “查看者”或更细粒度的角色（尽管Admin SDK的权限主要通过域范围授权控制）。
- 为该服务账户创建一个新的JSON密钥，并下载到您的项目目录中。此文件将用于您的PHP应用程序进行认证。
配置域范围授权（Domain-Wide Delegation）：
- 在Google Cloud Console中，找到您的服务账户的“唯一ID”（Client ID）。
- 登录到您的Google Workspace管理控制台（admin.google.com）。
- 导航到“安全” > “API 控件” > “域范围授权”。
- 添加一个新的API客户端，将服务账户的Client ID粘贴到“客户端 ID”字段中。
- 在“OAuth 范围”字段中，添加以下范围（或根据您的具体需求添加更多）：
  - https://www.googleapis.com/auth/admin.directory.group.readonly (读取群组信息)
  - https://www.googleapis.com/auth/userinfo.email (读取用户邮箱)
  - https://www.googleapis.com/auth/userinfo.profile (读取用户资料)
- 点击“授权”。这一步至关重要，它允许您的服务账户模拟域内的用户执行这些操作。
PHP项目依赖：
- 通过Composer安装Google API客户端库：
```
composer require google/apiclient
```

2. PHP客户端初始化与认证流程

本节将分步介绍如何在PHP中初始化Google客户端，并执行两阶段认证：首先通过OAuth2获取当前登录用户的基本信息，然后切换到服务账户模拟该用户来执行Admin SDK操作。

2.1 用户OAuth2认证获取基本信息

首先，我们需要让用户通过OAuth2登录，以获取他们的邮箱地址。这个邮箱地址稍后将用于服务账户模拟。

<?php

require 'vendor/autoload.php'; // 根据您的项目路径调整

// 创建新的Google客户端实例
$client = new Google_Client();

// 设置您的客户端ID、客户端密钥和重定向URL
// 这些信息从Google Cloud Console的OAuth 2.0客户端ID中获取
$client->setClientId('YOUR_CLIENT_ID.apps.googleusercontent.com');
$client->setClientSecret('YOUR_CLIENT_SECRET');
$client->setRedirectUri('YOUR_REDIRECT_URL'); // 必须与Google Cloud Console中配置的URL一致

$client->setApplicationName("My Google Group Lister");

// 添加获取用户邮箱和资料信息的OAuth范围
$client->addScope("https://www.googleapis.com/auth/userinfo.email");
$client->addScope("https://www.googleapis.com/auth/userinfo.profile");

// 处理OAuth回调
if (isset($_GET['code'])) {
    $token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

    if (!isset($token["error"])) {
        $client->setAccessToken($token['access_token']);

        // 获取用户基本信息
        $google_oauth = new Google_Service_Oauth2($client);
        $google_account_info = $google_oauth->userinfo->get();
        $userEmail = $google_account_info->email; // 获取当前登录用户的邮箱

        echo "当前登录用户邮箱: " . $userEmail . "<br>";

        // ... 接下来将进行服务账户模拟操作
    } else {
        echo "OAuth认证失败: " . $token["error_description"];
    }
} else {
    // 如果没有code参数，则重定向到Google认证页面
    $authUrl = $client->createAuthUrl();
    header('Location: ' . filter_var($authUrl, FILTER_SANITIZE_URL));
    exit();
}
?>

2.2 服务账户模拟用户执行Admin SDK操作

在获取到用户邮箱后，我们将切换到使用服务账户进行认证，并模拟该用户来调用Admin SDK。这是获取群组列表的关键步骤。

<?php
// ... 承接上面的代码，在 $userEmail 变量获取之后 ...

        // 配置服务账户认证
        // 加载您的服务账户JSON密钥文件路径
        $client->setAuthConfig('PATH_TO_YOUR_SERVICE_ACCOUNT_KEY.json');

        // 指定要模拟的用户邮箱。
        // 这个邮箱必须是Google Workspace域内的有效用户，
        // 并且该服务账户已通过域范围授权获得了相应的权限。
        $client->setSubject($userEmail); // 模拟当前登录的用户

        // 添加Admin SDK所需的OAuth范围
        // 注意：这个范围也必须在Google Workspace管理控制台的域范围授权中配置
        $client->addScope("https://www.googleapis.com/auth/admin.directory.group.readonly");

        // ... 接下来将进行获取群组列表的操作
?>

重要提示：

芦笋演示

一键出成片的录屏演示软件，专为制作产品演示、教学课程和使用教程而设计。

227 查看详情芦笋演示

setAuthConfig() 应该指向您下载的服务账户JSON密钥文件。
setSubject() 中的邮箱地址是您希望模拟的域内用户的邮箱。在这里，我们使用通过OAuth2认证获取到的当前登录用户的邮箱。
addScope("https://www.googleapis.com/auth/admin.directory.group.readonly") 必须在域范围授权中被服务账户授权。

3. 获取用户所属群组列表

现在，我们已经正确配置了客户端并进行了认证，可以使用Google_Service_Directory服务来查询用户所属的群组。

<?php
// ... 承接上面的代码 ...

        // 初始化Directory服务
        $service = new Google_Service_Directory($client);

        // 设置查询参数，列出指定用户所属的群组
        $optParams = array(
            'domain' => 'YOUR_DOMAIN.com', // 替换为您的Google Workspace域名
            'userKey' => $userEmail        // 使用要查询的用户邮箱
        );

        try {
            // 调用Admin SDK的groups->listGroups方法
            $googleGroups = $service->groups->listGroups($optParams);
            $groups = $googleGroups->getGroups();

            if (!empty($groups)) {
                echo "<h3>用户 " . $userEmail . " 所属的群组:</h3>";
                echo "<ul>";
                foreach ($groups as $group) {
                    echo "<li>" . $group->getEmail() . " (" . $group->getName() . ")</li>";
                }
                echo "</ul>";
            } else {
                echo "用户 " . $userEmail . " 不属于任何群组。";
            }
        } catch (Google_Service_Exception $e) {
            echo "获取群组时发生错误: " . $e->getMessage();
            // 详细错误信息可能在 $e->getErrors() 中
        }

// ...
?>

4. 完整示例代码

将上述所有部分整合，形成一个完整的PHP脚本：

<?php

require 'vendor/autoload.php';

// 创建新的Google客户端实例
$client = new Google_Client();

// --- 第一阶段：用户OAuth2认证，获取用户基本信息 ---
// 设置您的客户端ID、客户端密钥和重定向URL
$client->setClientId('YOUR_CLIENT_ID.apps.googleusercontent.com');
$client->setClientSecret('YOUR_CLIENT_SECRET');
$client->setRedirectUri('YOUR_REDIRECT_URL');
$client->setApplicationName("My Google Group Lister");

// 添加获取用户邮箱和资料信息的OAuth范围
$client->addScope("https://www.googleapis.com/auth/userinfo.email");
$client->addScope("https://www.googleapis.com/auth/userinfo.profile");

$userEmail = null;

if (isset($_GET['code'])) {
    $token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

    if (!isset($token["error"])) {
        $client->setAccessToken($token['access_token']);

        // 获取用户基本信息
        $google_oauth = new Google_Service_Oauth2($client);
        $google_account_info = $google_oauth->userinfo->get();
        $userEmail = $google_account_info->email; // 获取当前登录用户的邮箱

        echo "当前登录用户邮箱: " . $userEmail . "<br>";

        // --- 第二阶段：服务账户模拟用户，执行Admin SDK操作 ---
        // 配置服务账户认证
        // 加载您的服务账户JSON密钥文件路径
        $client->setAuthConfig('PATH_TO_YOUR_SERVICE_ACCOUNT_KEY.json');

        // 指定要模拟的用户邮箱
        $client->setSubject($userEmail); 

        // 添加Admin SDK所需的OAuth范围
        $client->addScope("https://www.googleapis.com/auth/admin.directory.group.readonly");

        // 初始化Directory服务
        $service = new Google_Service_Directory($client);

        // 设置查询参数，列出指定用户所属的群组
        $optParams = array(
            'domain' => 'YOUR_DOMAIN.com', // 替换为您的Google Workspace域名
            'userKey' => $userEmail        // 使用要查询的用户邮箱
        );

        try {
            // 调用Admin SDK的groups->listGroups方法
            $googleGroups = $service->groups->listGroups($optParams);
            $groups = $googleGroups->getGroups();

            if (!empty($groups)) {
                echo "<h3>用户 " . $userEmail . " 所属的群组:</h3>";
                echo "<ul>";
                foreach ($groups as $group) {
                    echo "<li>" . $group->getEmail() . " (" . $group->getName() . ")</li>";
                }
                echo "</ul>";
            } else {
                echo "用户 " . $userEmail . " 不属于任何群组。";
            }
        } catch (Google_Service_Exception $e) {
            echo "获取群组时发生错误: " . $e->getMessage() . "<br>";
            echo "详细错误: " . print_r(json_decode($e->getMessage(), true), true);
        }

    } else {
        echo "OAuth认证失败: " . $token["error_description"];
    }
} else {
    // 如果没有code参数，则重定向到Google认证页面
    $authUrl = $client->createAuthUrl();
    header('Location: ' . filter_var($authUrl, FILTER_SANITIZE_URL));
    exit();
}
?>

请务必将代码中的 YOUR_CLIENT_ID.apps.googleusercontent.com、YOUR_CLIENT_SECRET、YOUR_REDIRECT_URL、PATH_TO_YOUR_SERVICE_ACCOUNT_KEY.json 和 YOUR_DOMAIN.com 替换为您的实际值。

5. 关键注意事项与故障排除

unauthorized_client 错误：这是最常见的错误，通常意味着：
- 服务账户权限不足：确保您的服务账户已在Google Workspace管理控制台中通过域范围授权，并添加了所有必要的OAuth范围（例如 https://www.googleapis.com/auth/admin.directory.group.readonly）。
- OAuth范围不匹配：代码中addScope添加的范围必须与域范围授权中配置的范围完全一致。
- setAuthConfig 或 setSubject 配置不当：确保JSON密钥文件路径正确，并且setSubject中使用的邮箱是Google Workspace域内的有效用户。
- API未启用：确保在Google Cloud项目中已启用Admin SDK API。
域范围授权的Client ID：在Google Workspace管理控制台中配置域范围授权时，请使用服务账户的唯一ID（通常在服务账户详情页面的“详细信息”标签页中），而不是OAuth 2.0客户端ID。
模拟用户：setSubject方法用于指定服务账户要模拟的域内用户。只有通过域范围授权的服务账户才能模拟用户。
错误处理：始终使用try-catch块来捕获Google_Service_Exception，以便更好地诊断API调用失败的原因。

总结

通过本教程，您应该已经掌握了如何使用PHP和Google Admin SDK，结合服务账户和域范围授权来获取特定用户所属的Google群组列表。关键在于正确配置Google Cloud项目、服务账户、域范围授权，并在PHP代码中分阶段进行认证：首先通过OAuth2获取用户身份，然后利用服务账户模拟该用户来执行Admin SDK操作。遵循这些步骤将有效避免常见的认证和授权问题，确保您的应用程序能够顺利与Google Workspace API交互。

以上就是PHP集成Google Admin SDK：通过服务账户列出用户所属群组的教程的详细内容，更多请关注php中文网其它相关文章！

# 这是 # 益智玩具营销推广方案 # 网站推广价格有区别没 # 国外网络营销推广获客 # html5标签与seo # 婚庆网站建设定制 # 凌海seo网站营销推广 # 如何提升seo技能 # 智能营销网站怎么做推广 # 奉化网站建设哪里找 # 大渡口网站推广费用 # 所需 # 邮箱地址 # 创建一个 # 如何使用 # 该用户 # php # 重定向 # 客户端 # 群组 # 您的 # php脚本 # api调用 # 邮箱 # google # ai # access # app # composer # go # json # js

相关栏目：【 Google疑问12 】【 Facebook疑问10 】【优化推广96088 】【技术知识133117 】【 IDC资讯59369 】【网络运营7196 】【 IT资讯61894 】

2025-12-05

SQL多表关联如何理解_核心原理解析助你掌握关键方法【教程】 SQL多表连接如何理解_JOIN关联关系详细步骤解析【指导】 SQL多表连接结果异常怎么办_JOIN条件排查方法解析【指导】 SQL索引下推是什么_ICP机制性能提升原理【教程】 SQL跨表统计怎么写_重要技巧总结提升查询效率【技巧】 SQL注入如何防护_完整逻辑拆解助力系统化掌握【技巧】 SQL上传文件信息建模方法_SQL存储文件元数据方案 SQL多语种存储方案设计_SQL字符集选择策略 SQL字符串处理如何编写_重要技巧总结提升查询效率【教学】 SQL去重查询怎么实现_优化思路讲解帮助高效处理数据【技巧】 SQL统计复购用户怎么做_多次行为分析SQL思路【教程】 SQL字符串处理如何编写_优化思路讲解帮助高效处理数据【教程】 SQL动态字段解析技巧_SQL解析JSON多层字段 SQL线上慢SQL如何治理_规范与工具实践总结【技巧】 SQL表结构如何演进_兼容老数据设计思路【教程】 SQL排序规则如何设置_ORDERBY排序原理与性能说明【指导】 SQL去重查询怎么实现_真实案例解析强化复杂查询思维【教学】 SQL按字段范围分批处理_SQL避免长时间锁表 SQL统计不同字段组合数量_多列聚合查询技巧【技巧】 SQL多字段去重怎么处理_GROUPBY去重思路说明【教学】

了解您产品搜索量及市场趋势，制定营销计划

同行竞争及网站分析保障您的广告效果

点击免费数据支持

提交您的需求，1小时内享受我们的专业解答。

运城市盐湖区信雨科技有限公司

运城市盐湖区信雨科技有限公司是一家深耕海外推广领域十年的专业服务商，作为谷歌推广与Facebook广告全球合作伙伴，聚焦外贸企业出海痛点，以数字化营销为核心，提供一站式海外营销解决方案。公司凭借十年行业沉淀与平台官方资源加持，打破传统外贸获客壁垒，助力企业高效开拓全球市场，成为中小企业出海的可靠合作伙伴。