如何通过Google Admin API查询用户邮箱存储用量以触发告警？

要获取用户邮箱存储用量并实现告警，你需要使用Admin SDK Reports API的userUsageReport.get接口，而非activities.list（后者用于审计操作日志，不返回存储用量数据）。以下是具体实现步骤和修改后的代码：

核心要点 #

• 用userUsageReport.get接口，指定parameters为gmail:used_quota_in_mb,gmail:quota_limit_in_mb，分别获取已用存储和总配额
• 确保服务账号已被授予Workspace超级管理员权限（通过Admin控制台的「API权限」添加）
• 批量获取用户时需处理分页逻辑（当userKey='all'时，结果可能分多页返回）

修改后的代码示例 #

let privatekey = require("./spartan-concord-344213-d46691ffcd02.json");
let spreadsheetPriKey = require("./spreadsheet_service_account.json");

const { JWT } = require('google-auth-library');
const { google } = require('googleapis');

// 配置JWT认证客户端
let jwtClient = new JWT({
    email: privatekey.client_email,
    key: privatekey.private_key,
    subject: 'subject@email.com', // 必须为Workspace超级管理员邮箱
    scopes: [
        'https://www.googleapis.com/auth/apps.order',
        'https://www.googleapis.com/auth/admin.reports.audit.readonly',
        'https://www.googleapis.com/auth/admin.reports.usage.readonly',
        'https://www.googleapis.com/auth/admin.directory.user',
        'https://www.googleapis.com/auth/admin.directory.user.readonly',
    ],
});

let jwtSpreadsheetClient = new JWT({
    email: spreadsheetPriKey.client_email,
    key: spreadsheetPriKey.private_key,
    scopes: [
        'https://spreadsheets.google.com/feeds',
        'https://www.googleapis.com/auth/drive',
        'https://www.googleapis.com/auth/spreadsheets.readonly'
    ],
});

const sites = [];

// 先加载站点域名列表
jwtSpreadsheetClient.authorize(async function (err, tokens) {
    if (err) {
        console.log(err);
        return;
    } else {
        google.options({ auth: jwtSpreadsheetClient });
        const client = google.sheets({ version: "v4" });
        const supportEmail = await client.spreadsheets.values.get({
            spreadsheetId: 'ID',
            range: 'Sites!C2:C',
        });
        let suppEmails = supportEmail.data.values;
        suppEmails.forEach(element => {
            if (element[0] != null) {
                sites.push(element[0]);
            }
        });

        // 域名加载完成后，执行存储用量检查
        await checkUserStorageUsage();
    }
});

// 检查用户存储用量的核心函数
async function checkUserStorageUsage() {
    try {
        await jwtClient.authorize();
        google.options({ auth: jwtClient });

        const reportsService = google.admin({ version: 'reports_v1' });
        const directoryService = google.admin({ version: 'directory_v1' });

        // 遍历每个站点域名
        for (const domain of sites) {
            // 获取该域名下所有用户
            let nextPageToken = null;
            do {
                const usersResponse = await directoryService.users.list({
                    domain: domain,
                    maxResults: 500,
                    orderBy: 'email',
                    pageToken: nextPageToken
                });

                const users = usersResponse.data.users || [];
                nextPageToken = usersResponse.data.nextPageToken;

                // 遍历用户获取存储用量
                for (const user of users) {
                    const usageResponse = await reportsService.userUsageReport.get({
                        userKey: user.primaryEmail,
                        date: new Date().toISOString().split('T')[0], // 使用当前日期获取最新数据
                        parameters: 'gmail:used_quota_in_mb,gmail:quota_limit_in_mb'
                    });

                    const usageData = usageResponse.data.usageReports?.[0]?.parameters;
                    if (usageData) {
                        const usedQuota = parseFloat(usageData.find(p => p.name === 'gmail:used_quota_in_mb')?.intValue);
                        const quotaLimit = parseFloat(usageData.find(p => p.name === 'gmail:quota_limit_in_mb')?.intValue);
                        const usagePercent = (usedQuota / quotaLimit) * 100;

                        // 告警逻辑：使用率超过90%时触发
                        if (usagePercent > 90) {
                            console.log(`告警：用户 ${user.primaryEmail} 邮箱存储已使用 ${usagePercent.toFixed(2)}%，已用 ${usedQuota}MB，总配额 ${quotaLimit}MB`);
                            // 此处可添加邮件/通知发送逻辑
                        } else {
                            console.log(`用户 ${user.primaryEmail} 邮箱存储使用率 ${usagePercent.toFixed(2)}%，已用 ${usedQuota}MB，总配额 ${quotaLimit}MB`);
                        }
                    }
                }
            } while (nextPageToken);
        }
    } catch (err) {
        console.error('获取存储用量失败:', err);
    }
}

额外注意事项 #

• 日期格式：date参数需为YYYY-MM-DD格式，使用当前日期可获取最新用量数据
• 分页处理：用户数量超过maxResults时，通过nextPageToken循环拉取所有用户数据
• 权限验证：确认服务账号已在Workspace Admin控制台中被授予「查看用户用量报告」权限，且subject为有效超级管理员邮箱
• API配额：Google API有调用次数限制，批量获取时建议添加适当延迟，避免触发限流

内容的提问来源于stack exchange，提问作者Yuri Alves