如何更新脚本实现特定邮件自动触发响应及排查GCC配置问题

DevOps 小满

2026-7-15

问题解答

一、关于“收到特定主题邮件立即触发脚本”的Google限制问题

Google Apps Script的原生触发器确实没有“收到特定主题邮件即触发”的选项，原生触发器仅支持时间驱动、表单提交、文档编辑等有限场景。这并非Google的功能限制，而是需要通过**Gmail API的Watch功能结合Google Cloud Pub/Sub（GCC）**实现实时邮件触发，也就是你现在尝试的进阶方案。

二、你的Gmail Watch脚本&配置问题排查

核心问题分析（导致测试无反应的常见原因）

1. 脚本占位符未替换

你的setupGmailWatch函数中，const topicName = 'projects/PROJECTID/topics/TOPIC';是占位符，必须替换为你实际的GCP项目ID和Pub/Sub主题名称，否则Gmail无法将通知推送到正确的主题。

2. 缺少Pub/Sub消息验证

Google Pub/Sub推送的消息需要验证签名，否则你的Web应用会拒绝接收（或被Google拦截）。你的doPost函数没有验证逻辑，这是导致无响应的关键原因之一。

3. History ID获取逻辑错误

推送的emailData.historyId是触发通知时的最新历史ID，直接用它作为startHistoryId调用Gmail.Users.History.list，会无法获取到触发通知的那条历史记录。需要用上次保存的历史ID作为起始点。

4. 权限配置缺失

未给Gmail服务账号授权Pub/Sub发布权限：需要在GCP控制台的Pub/Sub主题页面，给gmail-api-push@system.gserviceaccount.com添加「Pub/Sub 发布者」角色。
未启用Gmail API：在Apps Script编辑器中，需启用Gmail高级服务和Apps Script API。
Web应用部署权限错误：部署Web应用时，需设置为「以我自己的身份运行」，访问权限设为「任何人」（配合签名验证确保安全）。

5. 未完成首次手动授权

定时触发器createWatchTrigger调用的setupGmailWatch需要OAuth权限，必须先手动运行一次setupGmailWatch函数，完成权限授权，否则定时触发器会因权限不足失败。

修复后的脚本示例

// 保存上次的historyId到属性服务
function getLastHistoryId() {
  const props = PropertiesService.getUserProperties();
  return props.getProperty('lastHistoryId') || '0';
}

function setLastHistoryId(id) {
  const props = PropertiesService.getUserProperties();
  props.setProperty('lastHistoryId', id);
}

function setupGmailWatch() {
  // 替换为你的实际项目ID和主题名称
  const topicName = 'projects/你的GCP项目ID/topics/你的主题名称';
  const url = 'https://www.googleapis.com/gmail/v1/users/me/watch';

  const options = {
    method: 'post',
    headers: {
      Authorization: 'Bearer ' + ScriptApp.getOAuthToken()
    },
    contentType: 'application/json',
    muteHttpExceptions: true,
    payload: JSON.stringify({
      labelIds: ['INBOX'],
      topicName: topicName,
      // 设置过期时间为7天（Gmail Watch最长有效期）
      expiration: Date.now() + 7 * 24 * 60 * 60 * 1000
    })
  };

  const response = UrlFetchApp.fetch(url, options);
  const result = JSON.parse(response.getContentText());
  // 保存初始historyId
  setLastHistoryId(result.historyId);
  Logger.log('Gmail Watch已设置: ' + JSON.stringify(result));
};

function createWatchTrigger() {
  try {
    // 先删除已存在的同名触发器，避免重复
    const existingTriggers = ScriptApp.getProjectTriggers();
    for (let trigger of existingTriggers) {
      if (trigger.getHandlerFunction() === 'setupGmailWatch') {
        ScriptApp.deleteTrigger(trigger);
      }
    }
    // 每6天触发一次（比7天有效期提前1天）
    ScriptApp.newTrigger('setupGmailWatch')
      .timeBased()
      .everyDays(6)
      .create();
    MailApp.sendEmail({
      to: Session.getActiveUser().getEmail(),
      subject: 'Gmail Watch触发器已创建',
      body: '定时触发器已成功设置，每6天自动刷新Gmail Watch'
    });
  } catch (e) {
    MailApp.sendEmail({
      to: Session.getActiveUser().getEmail(),
      subject: 'Failed to set up Gmail Watch trigger',
      body: 'An error occurred when trying to set up the Gmail Watch trigger: ' + e.message
    });
  }
};

// 验证Pub/Sub消息签名（关键步骤）
function verifyPubSubSignature(message) {
  const crypto = Utilities.computeHmacSha256Signature(
    message.data,
    Utilities.base64DecodeWebSafe(message.attributes.signingKey)
  );
  const signature = Utilities.base64EncodeWebSafe(crypto);
  return signature === message.attributes.signature;
}

function handleEmailNotification(message) {
  // 验证消息签名
  if (!verifyPubSubSignature(message)) {
    Logger.log('无效的Pub/Sub消息');
    return;
  }

  const data = Utilities.newBlob(Utilities.base64DecodeWebSafe(message.data)).getDataAsString();
  const emailData = JSON.parse(data);
  const lastHistoryId = getLastHistoryId();

  // 从上次保存的historyId开始获取新记录
  const historyList = Gmail.Users.History.list('me', {
    startHistoryId: lastHistoryId,
    historyTypes: 'messageAdded',
    maxResults: 10
  });

  // 处理history为空的情况
  if (!historyList.history) {
    Logger.log('无新的邮件记录');
    // 更新historyId为最新的
    setLastHistoryId(emailData.historyId);
    return;
  }

  const messages = historyList.history
    .map(history => history.messagesAdded)
    .flat()
    .filter(item => item) // 过滤空值
    .map(item => item.message);

  messages.forEach(msg => {
    const email = GmailApp.getMessageById(msg.id);
    const subject = email.getSubject();
    if (subject.includes("For Review (TEST):")) {
      MailApp.sendEmail({
        to: Session.getActiveUser().getEmail(),
        subject: 'YOU GOT AN EMAIL',
        body: `收到主题为【${subject}】的邮件，邮件ID：${msg.id}`
      });
    }
  });

  // 更新historyId为最新的
  setLastHistoryId(emailData.historyId);
};

function doPost(e) {
  try {
    const payload = JSON.parse(e.postData.contents);
    handleEmailNotification(payload.message);
    return ContentService.createTextOutput('Success').setMimeType(ContentService.MimeType.TEXT);
  } catch (error) {
    Logger.log('处理Post请求出错: ' + error.message);
    return ContentService.createTextOutput('Error').setMimeType(ContentService.MimeType.TEXT);
  }
};

配置修复步骤

GCP Pub/Sub主题配置
- 在GCP控制台创建Pub/Sub主题，记录主题的完整名称（projects/项目ID/topics/主题名）。
- 给主题添加权限：成员选择gmail-api-push@system.gserviceaccount.com，角色选择「Pub/Sub 发布者」。
- 创建订阅，选择「推送」类型，输入你的Apps Script Web应用URL（部署后生成的URL），推送格式选「JSON」。
Apps Script配置
- 启用高级服务：点击编辑器左侧「服务」->「添加服务」，找到「Gmail API」并启用。
- 部署Web应用：点击「部署」->「新部署」，类型选「Web应用」，执行权限选「以我自己的身份运行」，访问权限选「任何人」，复制生成的URL到Pub/Sub订阅的推送地址。
- 手动运行setupGmailWatch函数，完成权限授权；再运行createWatchTrigger创建定时刷新触发器。
测试验证
- 发送一封主题含「For Review (TEST):」的邮件到你的邮箱，等待1-2分钟，检查是否收到提醒邮件。
- 查看Apps Script的日志（编辑器左侧「日志」），排查是否有错误信息。

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

如何更新脚本实现特定邮件自动触发响应及排查GCC配置问题

一、关于“收到特定主题邮件立即触发脚本”的Google限制问题 #

二、你的Gmail Watch脚本&配置问题排查 #

核心问题分析（导致测试无反应的常见原因） #