跳到主要内容

Google Apps Script 配置指南

目录​

  1. 什么是 Google Apps Script？
  2. 项目中的 Apps Script 用途
  3. 审计日志 Apps Script 配置
  4. 图片插入 Apps Script 配置
  5. Apps Script Execution API 配置
  6. 服务账号权限配置
  7. 测试与验证

什么是 Google Apps Script？​

Google Apps Script 是 Google 提供的一种基于 JavaScript 的脚本平台，可以自动化 Google Workspace 应用（如 Google Sheets、Google Slides、Google Docs）的操作。在本项目中，Apps Script 用于：

  1. 审计日志记录：将用户操作记录到 Google Sheet
  2. 图片插入：将生成的图片插入到 Google Slides

为什么使用 Apps Script？

  1. Google Workspace 集成：可以直接操作 Google Sheets 和 Google Slides，无需复杂的 API 调用
  2. 简化开发：使用熟悉的 JavaScript 语言，开发简单
  3. 执行身份：可以以服务账号身份执行，确保权限控制
  4. 成本效益：Google Apps Script 对个人和企业用户免费

项目中的 Apps Script 用途​

审计日志 Apps Script​

功能：记录用户操作日志到 Google Sheet

用途：

  • 用户登录/登出记录
  • 功能使用记录（市场机会分析、人群信号分析、受众画像幻灯片）
  • 结果数据记录
  • 导出操作记录
  • 用户反馈记录

文件位置：docs/apps-script-code/AuditLogCode.gs

图片插入 Apps Script​

功能：将生成的图片插入到 Google Slides

用途：

  • 将分析结果图表插入到 Google Slides 模板
  • 替换占位符文本为实际图片
  • 在空白幻灯片中插入图片

文件位置：docs/apps-script-code/SlidePictureCode.gs

注意：这两个 Apps Script 项目是完全独立的，需要分别创建和配置。

审计日志 Apps Script 配置​

步骤 1：创建 Google Sheet​

  1. 创建新的 Google Sheet

    • 访问 Google Sheets
    • 创建一个新的空白表格
    • 命名为 InsightHub Audit Log（或您选择的名称）

  2. 记录 Sheet ID

    • 从 URL 中提取 Sheet ID
    • URL 格式：https://docs.google.com/spreadsheets/d/{SHEET_ID}/edit
    • 例如：如果 URL 是 https://docs.google.com/spreadsheets/d/1a2b3c4d5e6f7g8h9i0j/edit，则 Sheet ID 是 1a2b3c4d5e6f7g8h9i0j

步骤 2：创建 Apps Script 项目​

  1. 打开 Apps Script 编辑器

  2. 创建新项目

    • 点击"新建项目"
    • 项目名称：InsightHub Audit Log

  3. 复制代码

    • 打开项目中的 docs/apps-script-code/AuditLogCode.gs 文件
    • 复制全部内容
    • 粘贴到 Apps Script 编辑器的 Code.gs 文件中

步骤 3：配置脚本属性​

  1. 打开项目设置

    • 点击左侧的"项目设置"（齿轮图标）

  2. 添加脚本属性

    • 在"脚本属性"部分，点击"添加脚本属性"
    • 属性：SPREADSHEET_ID
    • 值：您在第 1 步中记录的 Sheet ID
    • 点击"保存脚本属性"

步骤 4：记录 Script ID​

  1. 获取 Script ID

    • 在项目设置页面，找到"脚本 ID"（Script ID）
    • 或从 Apps Script 编辑器 URL 中获取
    • URL 格式：https://script.google.com/home/projects/{SCRIPT_ID}/edit

  2. 配置环境变量

    • （已废弃）旧版本通过 APPS_SCRIPT_AUDIT_ID 使用 Apps Script 记录日志。现已改为使用 AUDIT_LOG_SPREADSHEET_ID 直接写入 Google Sheet，本步骤仅在维护旧版本时需要。
    • 开发环境：添加到 .env 文件
    • 生产环境：添加到 Cloud Build 触发器的替换变量

步骤 5：配置 Sheet 权限​

  1. 共享 Sheet 给服务账号
    • 在 Google Sheet 中，点击右上角的"共享"按钮
    • 添加服务账号邮箱（格式：service-account-name@project-id.iam.gserviceaccount.com）
    • 权限设置为"编辑者"（Editor）
    • 点击"发送"

重要：服务账号必须有 Sheet 的编辑权限，才能写入日志。

图片插入 Apps Script 配置​

步骤 1：创建 Apps Script 项目​

  1. 打开 Apps Script 编辑器

  2. 项目名称

    • 项目名称：InsightHub Slide Picture

  3. 复制代码

    • 打开项目中的 docs/apps-script-code/SlidePictureCode.gs 文件
    • 复制全部内容
    • 粘贴到 Apps Script 编辑器的 Code.gs 文件中

步骤 2：记录 Script ID​

  1. 获取 Script ID

    • 在项目设置页面，找到"脚本 ID"
    • 或从 Apps Script 编辑器 URL 中获取

  2. 配置环境变量

    • 将 Script ID 配置到环境变量 APPS_SCRIPT_SLIDES_ID
    • 开发环境：添加到 .env 文件
    • 生产环境：添加到 Cloud Build 触发器的替换变量

步骤 3：配置执行身份​

  1. 打开项目设置

    • 点击左侧的"项目设置"（齿轮图标）

  2. 执行身份

    • 在"执行身份"部分，选择"我"（Me）
    • 这意味着 Apps Script 会以调用者的身份执行（通常是服务账号）

注意：如果使用服务账号调用，Apps Script 会以服务账号的身份执行，因此服务账号需要有 Google Slides 的访问权限。

Apps Script Execution API 配置​

什么是 Execution API？​

Apps Script Execution API 允许外部应用（如我们的后端服务器）通过 HTTP 请求调用 Apps Script 中的函数，而无需将 Apps Script 部署为 Web App。

启用 Execution API​

  1. 打开 Google Cloud Console

  2. 启用 Apps Script API

    • 导航到"API 和服务" > "库"
    • 搜索"Apps Script API"
    • 点击"启用"

配置服务账号权限​

服务账号需要能够调用 Apps Script Execution API：

  1. 授予服务账号权限
    • 在 Apps Script 项目中，点击右上角的"共享"按钮
    • 添加服务账号邮箱
    • 权限设置为"查看者"（Viewer）即可
    • 点击"发送"

说明：

  • 服务账号只需要"查看者"权限即可调用 Execution API
  • 但执行 Apps Script 时，会以服务账号的身份执行，因此服务账号需要有实际操作的权限（如 Sheet 的编辑权限、Slides 的编辑权限）

服务账号权限配置​

审计日志服务账号权限​

服务账号需要以下权限：

  1. Google Sheet 权限

    • 在审计日志 Sheet 中，将服务账号添加为"编辑者"
    • 服务账号邮箱格式：service-account-name@project-id.iam.gserviceaccount.com

  2. Apps Script 权限

    • 在审计日志 Apps Script 项目中，将服务账号添加为"查看者"
    • 这允许服务账号调用 Execution API

图片插入服务账号权限​

服务账号需要以下权限：

  1. Google Slides 权限

    • 在需要插入图片的 Google Slides 中，将服务账号添加为"编辑者"
    • 或使用 Google Slides 模板，将服务账号添加为"编辑者"

  2. Apps Script 权限

    • 在图片插入 Apps Script 项目中，将服务账号添加为"查看者"
    • 这允许服务账号调用 Execution API

权限配置检查清单​

  • 服务账号已创建
  • 服务账号密钥已下载
  • 审计日志 Sheet 已共享给服务账号（编辑者权限）
  • 审计日志 Apps Script 已共享给服务账号（查看者权限）
  • 图片插入 Apps Script 已共享给服务账号（查看者权限）
  • Google Slides 模板已共享给服务账号（编辑者权限，如需要）

测试与验证​

测试审计日志 Apps Script​

方式 1：在 Apps Script 编辑器中测试​

  1. 选择测试函数

    • 在 Apps Script 编辑器中，选择一个测试函数（如 testLogUserLogin）
    • 点击"运行"按钮

  2. 授权权限

    • 首次运行需要授权
    • 点击"授权访问"
    • 选择您的 Google 账号
    • 点击"允许"

  3. 查看结果

    • 检查 Google Sheet 中是否已写入日志
    • 查看 Apps Script 执行日志，确认无错误

方式 2：通过后端 API 测试​

  1. 启动后端服务器

    cd server
    npm run dev

  2. 调用测试端点（如果存在）

    • 或直接调用审计日志 API 端点
    • 检查 Sheet 中是否已写入日志

测试图片插入 Apps Script​

方式 1：在 Apps Script 编辑器中测试​

  1. 准备测试数据

    • 创建一个测试 Google Slides
    • 在幻灯片中添加占位符文本（如 {{图片}}）
    • 准备一个 Base64 编码的测试图片

  2. 运行测试函数

    • 在 Apps Script 编辑器中，选择 testInsertImage 函数
    • 修改函数参数（Presentation ID、占位符、图片数据）
    • 点击"运行"

  3. 查看结果

    • 检查 Google Slides 中占位符是否已被图片替换
    • 查看 Apps Script 执行日志，确认无错误

方式 2：通过后端 API 测试​

  1. 调用图片插入 API
    • 通过后端 API 调用图片插入功能
    • 检查 Google Slides 中图片是否已插入

验证配置​

检查清单​

  • Apps Script 项目已创建
  • 代码已正确复制
  • Script ID 已记录并配置到环境变量
  • Apps Script API 已启用
  • 服务账号权限已配置
  • 测试函数运行成功
  • 日志/图片已正确写入/插入

常见问题​

Q1：Apps Script 执行失败，提示权限不足？​

错误信息：PERMISSION_DENIED 或 You do not have permission to call this function

可能原因：

  1. 服务账号没有 Apps Script 项目的访问权限
  2. Apps Script API 未启用
  3. 服务账号没有实际操作资源的权限（如 Sheet 的编辑权限）

解决方案：

  1. 在 Apps Script 项目中，将服务账号添加为"查看者"
  2. 启用 Apps Script API
  3. 在 Sheet/Slides 中，将服务账号添加为"编辑者"

Q2：审计日志无法写入 Sheet？​

错误信息：Exception: You do not have permission to perform that action

可能原因：

  1. 服务账号没有 Sheet 的编辑权限
  2. Script ID 配置错误
  3. Sheet ID 配置错误

解决方案：

  1. 在 Sheet 中，将服务账号添加为"编辑者"
  2. （遗留）确认部署脚本中不再引用 APPS_SCRIPT_AUDIT_ID。
  3. 检查 Apps Script 项目中的脚本属性 SPREADSHEET_ID 是否正确

Q3：如何获取 Script ID？​

方式 1：从项目设置获取

  1. 在 Apps Script 编辑器中，点击"项目设置"（齿轮图标）
  2. 在"常规"部分，找到"脚本 ID"

方式 2：从 URL 获取

  • Apps Script 编辑器 URL 格式：https://script.google.com/home/projects/{SCRIPT_ID}/edit
  • 从 URL 中提取 SCRIPT_ID 部分

Q4：Apps Script 执行超时？​

错误信息：Execution timeout

可能原因：

  1. Apps Script 执行时间超过 6 分钟（免费版限制）
  2. 处理的数据量过大
  3. 网络问题

解决方案：

  1. 优化 Apps Script 代码，减少执行时间
  2. 分批处理数据
  3. 检查网络连接

Q5：如何查看 Apps Script 执行日志？​

方式 1：在编辑器中查看

  1. 在 Apps Script 编辑器中，点击"执行"（▶️）按钮
  2. 查看"执行日志"面板

方式 2：在 Google Cloud Console 中查看

  1. 打开 Google Cloud Console
  2. 导航到"日志" > "日志浏览器"
  3. 筛选 Apps Script 相关日志

总结​

本章节详细介绍了 Google Apps Script 的配置步骤，包括：

  1. Apps Script 概述：什么是 Apps Script，为什么使用它
  2. 审计日志配置：如何创建和配置审计日志 Apps Script
  3. 图片插入配置：如何创建和配置图片插入 Apps Script
  4. Execution API 配置：如何启用和配置 Execution API
  5. 服务账号权限：如何配置服务账号的权限
  6. 测试与验证：如何测试和验证配置

正确配置 Apps Script 是系统功能正常运行的关键，请按照步骤逐一完成配置。

相关文档：