构建实时Gmail邮件通知的Web应用集成指南

# 假设你已经通过OAuth获取了凭据 (credentials)
from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build

# 构建Gmail服务客户端
service = build('gmail', 'v1', credentials=credentials)

# Pub/Sub 主题名称，格式为 projects/YOUR_PROJECT_ID/topics/YOUR_TOPIC_NAME
# 替换 YOUR_PROJECT_ID 和 YOUR_TOPIC_NAME
topic_name = 'projects/your-gcp-project-id/topics/gmail-notifications'

# 配置watch请求体
watch_request = {
    'topicName': topic_name,
    # 'labelIds': ['INBOX'] # 可选：只监听收件箱的变更
}

try:
    # 调用users.watch方法
    response = service.users().watch(userId='me', body=watch_request).execute()
    print(f"Gmail watch setup successful. History ID: {response.get('historyId')}")
except Exception as e:
    print(f"Error setting up Gmail watch: {e}")

// app/Controllers/Webhook.php
namespace App\Controllers;

use CodeIgniter\Controller;
use CodeIgniter\HTTP\ResponseInterface;

class Webhook extends Controller
{
    public function gmail()
    {
        // 验证请求是否来自Google Pub/Sub (可选但强烈推荐)
        // 可以通过验证请求头中的 'X-Goog-Signature' 或其他机制

        $input = $this->request->getRawInput();
        $data = json_decode($input, true);

        // Pub/Sub消息体通常包含一个'message'字段
        if (isset($data['message']['data'])) {
            $message_data = base64_decode($data['message']['data']);
            $notification = json_decode($message_data, true);

            // 检查通知类型，通常是关于邮件历史ID的变更
            if (isset($notification['emailAddress']) && isset($notification['historyId'])) {
                $email_address = $notification['emailAddress'];
                $new_history_id = $notification['historyId'];

                // 这里是处理通知的核心逻辑
                // 你需要：
                // 1. 获取该用户之前存储的 historyId
                // 2. 调用 Gmail API 的 users.history.list 方法，传入 startHistoryId
                //    来获取所有自上次同步以来的变更（包括新邮件）
                // 3. 遍历变更列表，识别新邮件，并进行相应处理（如存储、发送应用内通知）

                log_message('info', "Received Gmail notification for {$email_address}. New historyId: {$new_history_id}");

                // 示例：获取历史变更
                $this->processGmailHistory($email_address, $new_history_id);

                return $this->response->setStatusCode(ResponseInterface::HTTP_OK);
            }
        }

        // 如果消息格式不正确或处理失败，返回非2xx状态码，Pub/Sub会重试
        return $this->response->setStatusCode(ResponseInterface::HTTP_BAD_REQUEST);
    }

    private function processGmailHistory(string $emailAddress, string $newHistoryId)
    {
        // 实际应用中，你需要从数据库中获取该用户上一次处理的 historyId
        // 这里假设我们有一个函数来获取用户的凭据和上一次的 historyId
        $user_credentials = $this->getUserCredentials($emailAddress); // 你的逻辑
        $last_processed_history_id = $this->getLastProcessedHistoryId($emailAddress); // 你的逻辑

        if (!$user_credentials || !$last_processed_history_id) {
            log_message('error', "Could not retrieve credentials or last history ID for {$emailAddress}");
            return;
        }

        $service = build('gmail', 'v1', credentials=$user_credentials);

        try {
            $history_response = $service->users()->history()->list(
                userId='me',
                startHistoryId=$last_processed_history_id,
                historyTypes=['messageAdded'] // 只关注消息添加事件
            )->execute();

            $history_items = $history_response->get('history', []);

            foreach ($history_items as $history_item) {
                if (isset($history_item['messagesAdded'])) {
                    foreach ($history_item['messagesAdded'] as $message_added) {
                        $message_id = $message_added['message']['id'];
                        // 获取新邮件的详细信息
                        $message = $service->users()->messages()->get(userId='me', id=$message_id).execute();
                        log_message('info', "New mail received: " . $message['snippet']);
                        // 在这里触发Web应用内的通知逻辑
                    }
                }
            }

            // 更新用户存储的 historyId 为新的 historyId
            $this->updateLastProcessedHistoryId($emailAddress, $newHistoryId); // 你的逻辑

        } catch (Exception $e) {
            log_message('error', "Error processing Gmail history for {$emailAddress}: {$e->getMessage()}");
        }
    }

    // 辅助函数，需要根据你的应用实际实现
    private function getUserCredentials(string $emailAddress) { /* ... */ return null; }
    private function getLastProcessedHistoryId(string $emailAddress) { /* ... */ return 'YOUR_INITIAL_HISTORY_ID'; } // 首次设置时需存储
    private function updateLastProcessedHistoryId(string $emailAddress, string $newHistoryId) { /* ... */ }
}