理解自动化认证挑战
当python脚本需要与google服务（如google sheets、google drive或google apps script）交互时，通常会采用oauth 2.0协议进行身份验证。这个过程通常涉及用户在浏览器中登录google账户，并授权应用程序访问其google数据。对于一次性或交互式任务而言，这种方式是可行的。
然而，在需要端到端自动化（例如定时任务、后台服务或无头服务器上的脚本）的场景中，重复的用户交互式认证会成为一个严重障碍。每次运行脚本都要求手动登录和授权，这完全违背了自动化的初衷。核心挑战在于如何让脚本在没有人工干预的情况下，安全地获取并维持对Google服务的访问权限。
核心概念与准备工作
要实现Python脚本对Google Apps Script的无缝自动化调用，我们需要理解并准备以下关键组件：
-
Google Cloud 项目与API启用：
- 确保你有一个Google Cloud项目。
- 在该项目中，启用“Google Apps Script API”。这是Python脚本调用Apps Script的基础。
-
OAuth 2.0 客户端凭据 (credentials.json)：
- 在Google Cloud Console中，为你的项目创建一个OAuth 2.0客户端ID（通常选择“桌面应用”类型）。
- 下载生成的JSON文件，并将其命名为credentials.json，放置在Python脚本的同一目录下。此文件包含客户端ID和客户端密钥，用于首次启动认证流程。
-
授权范围 (Scopes)：
- Scopes定义了你的应用程序可以访问的Google服务和数据类型。选择最小必要的权限至关重要，以降低安全风险。例如，如果你的Apps Script只操作Google Sheets，则只需要https://www.googleapis.com/auth/spreadsheets。
- 在本文的示例中，为了演示更广泛的集成能力，我们使用了一组相对全面的Scopes，但在实际生产环境中应严格限制。
-
令牌文件 (token.json)：
- 这是实现自动化认证的核心。首次成功授权后，Google会返回一个访问令牌（access token）和一个刷新令牌（refresh token）。
- 访问令牌用于短期内直接访问API，而刷新令牌则用于在访问令牌过期后，无需用户再次授权即可获取新的访问令牌。
- token.json文件将持久化存储这些令牌，允许脚本在后续运行时直接加载并使用它们，从而跳过交互式认证。
实现无缝认证的Python代码
以下Python代码演示了如何利用token.json文件实现Google Apps Script的自动化认证和调用。该方案的核心逻辑是：检查是否存在有效的token.json；如果存在，则加载并尝试刷新；如果不存在或无效，则启动新的认证流程并保存结果。
import os.path
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient import errors
from googleapiclient.discovery import build
# 定义所需的API范围。建议仅使用脚本所需的最小范围。
# 以下范围列表涵盖了广泛的Apps Script和Drive操作，请根据实际需求进行调整。
SCOPES = [
"https://www.googleapis.com/auth/script.projects",
"https://www.googleapis.com/auth/script.external_request",
"https://www.googleapis.com/auth/drive.readonly",
"https://www.googleapis.com/auth/drive",
"https://www.googleapis.com/auth/drive.scripts",
"https://www.googleapis.com/auth/script.processes",
"https://www.googleapis.com/auth/spreadsheets",
"https://www.googleapis.com/auth/script.scriptapp",
]
def run_apps_script_with_auth(script_deployment_id: str, function_name: str):
"""
使用持久化认证凭据调用Google Apps Script API。
Args:
script_deployment_id (str): Google Apps Script的部署ID（不是项目ID）。
function_name (str): 要执行的Apps Script函数名称。
"""
creds = None
# 1. 检查是否存在token.json文件。如果存在，尝试加载凭据。
# token.json存储了用户的访问和刷新令牌，在首次授权流程完成后自动创建。
if os.path.exists("token.json"):
creds = Credentials.from_authorized_user_file("token.json", SCOPES)
# 2. 如果没有有效的凭据，或者凭据已过期且有刷新令牌，则刷新凭据。
# 否则，启动新的认证流程。
if not creds or not creds.valid:
if creds and creds.expired and creds.refresh_token:
# 凭据过期但有刷新令牌，使用刷新令牌获取新的访问令牌
print("凭据已过期，正在尝试刷新令牌...")
creds.refresh(Request())
else:
# 没有有效的凭据，或者刷新令牌也无效/不存在，启动新的认证流程。
# 这会打开浏览器窗口，要求用户进行交互式授权。
print("未找到有效凭据或凭据无效，正在启动新的认证流程...")
flow = InstalledAppFlow.from_client_secrets_file(
"credentials.json", SCOPES
)
creds = flow.run_local_server(port=0) # port=0 会自动选择一个可用端口
# 3. 将新获得的或刷新的凭据保存到token.json文件中，以便下次运行使用。
with open("token.json", "w") as token:
token.write(creds.to_json())
print("凭据已保存到 token.json。")
try:
# 4. 使用获得的凭据构建Google Apps Script API服务客户端。
service = build("script", "v1", credentials=creds)
# 5. 创建一个执行请求对象，指定要运行的Apps Script函数。
request_body = {"function": function_name}
# 6. 调用Apps Script API执行指定的函数。
print(f"正在执行Apps Script: {function_name} (部署ID: {script_deployment_id})...")
response = service.scripts().run(body=request_body, scriptId=script_deployment_id).execute()
# 7. 处理API响应。
if 'error' in response:
# Apps Script执行失败，打印错误详情。
error_details = response['error']['details']
print(f"Apps Script执行失败。错误详情: {error_details}")
# 可以根据需要解析更具体的错误信息，例如堆栈跟踪。
else:
# Apps Script执行成功，打印结果。
print(f"Apps Script执行成功。结果: {response.get('response', {}).get('result')}")
except errors.HttpError as error:
# 捕获并打印Google API调用过程中发生的HTTP错误。
print(f"Google API调用失败: {error.content}")
except Exception as e:
# 捕获其他潜在的运行时错误。
print(f"发生未知错误: {e}")
# 示例用法
if __name__ == "__main__":
# 替换为你的Google Apps Script部署ID和要执行的函数名。
# 部署ID可以在Apps Script编辑器中，“部署”->“管理部署”中找到。
my_script_deployment_id = "YOUR_APPS_SCRIPT_DEPLOYMENT_ID" # 例如：AKfycbxtDnDYa2mTZKB6WoqK_D9PDsLZyqb7GQAh7pvER-K-rMFXYNa6oVOhzXHsyfyl8vLz
my_function_name = "helloWorld" # 你的Apps Script项目中定义的函数名
# 首次运行时会打开浏览器进行授权，之后会复用token.json，实现自动化。
run_apps_script_with_auth(my_script_deployment_id, my_function_name)如何获取 script_deployment_id： 在Google Apps Script编辑器中，点击“部署”->“新建部署”。选择“API可执行文件”类型。部署成功后，会生成一个“部署ID”，这就是你需要填入 my_script_deployment_id 的值。请注意，这不是Apps Script项目的ID，而是特定部署的ID。
注意事项与最佳实践
在实现自动化认证时，务必考虑以下几点以确保安全性、稳定性和可维护性：
立即学习“Python免费学习笔记（深入）”；
-
最小权限原则 (Least Privilege Principle)：
- 仔细审查并仅选择你的Apps Script实际运行所需的最小SCOPES。例如，如果你的脚本只读取Google Sheets数据，则不需要https://www.googleapis.com/auth/drive的写入权限。过度授权会增加潜在的安全风险。
-
凭据文件的安全管理：
- credentials.json和token.json文件包含敏感的认证信息。绝不能将它们提交到公共版本控制系统（如GitHub）。
- 在生产环境中，应采用更安全的凭据管理方式，例如：
- 使用环境变量存储客户端ID和密钥。
- 利用云服务提供商的密钥管理服务（如Google Secret Manager）。
- 确保运行脚本的环境具有适当的文件系统权限，以保护这些文件。
-
刷新令牌的生命周期：
- 虽然刷新令牌通常具有较长的生命周期（通常是永久的，直到用户撤销授权或Google Cloud项目被删除），但并非绝对永久。在极少数情况下，刷新令牌也可能失效，此时需要重新进行一次完整的用户交互式授权流程。
-
错误处理与日志记录：
- 示例代码包含了基本的try-except块来捕获googleapiclient.errors.HttpError和其他通用异常。在实际应用中，应根据业务逻辑进行更细致的错误处理，例如记录详细的错误日志、发送通知或实现重试机制。
- 解析API响应中的error字段，可以获取Apps Script内部执行失败的具体信息，这对于调试至关重要。
-
无头（Headless）环境部署：
- 在没有图形界面（如服务器、Docker容器、CI/CD流水线）的环境中，flow.run_local_server(port=0)这种交互式授权方式将无法工作。
- 对于这类环境，你需要预先在一个有界面的机器上运行一次脚本，生成token.json文件，然后将该文件安全地部署到无头环境中。或者，考虑使用服务账户（Service Account）进行认证，但服务账户对Apps Script的调用方式有所不同，通常用于直接操作Google Workspace服务，而不是通过API执行用户部署的Apps Script。
总结
通过采用持久化的认证令牌（token.json），Python脚本可以有效地绕过Google Apps Script API调用的重复认证问题，实现真正的自动化。这种方法允许开发者构建健壮、无需人工干预的自动化流程，极大地提升了集成效率和可靠性。遵循最小权限原则和严格的安全实践，是确保自动化系统安全运行的关键。
