Python调用Google脚本教程

一分耕耘，一分收获！既然打开了这篇文章《Python调用Google脚本：自动化认证教程》，就坚持看下去吧！文中内容包含等等知识点...希望你能在阅读本文后，能真真实实学到知识或者帮你解决心中的疑惑，也欢迎大佬或者新人朋友们多留言评论，多给建议！谢谢！

理解自动化认证挑战

当Python脚本需要与Google服务（如Google Sheets、Google Drive或Google Apps Script）交互时，通常会采用OAuth 2.0协议进行身份验证。这个过程通常涉及用户在浏览器中登录Google账户，并授权应用程序访问其Google数据。对于一次性或交互式任务而言，这种方式是可行的。

然而，在需要端到端自动化（例如定时任务、后台服务或无头服务器上的脚本）的场景中，重复的用户交互式认证会成为一个严重障碍。每次运行脚本都要求手动登录和授权，这完全违背了自动化的初衷。核心挑战在于如何让脚本在没有人工干预的情况下，安全地获取并维持对Google服务的访问权限。

核心概念与准备工作

要实现Python脚本对Google Apps Script的无缝自动化调用，我们需要理解并准备以下关键组件：

1. Google Cloud 项目与API启用：
   • 确保你有一个Google Cloud项目。
   • 在该项目中，启用“Google Apps Script API”。这是Python脚本调用Apps Script的基础。
2. OAuth 2.0 客户端凭据 (credentials.json)：
   • 在Google Cloud Console中，为你的项目创建一个OAuth 2.0客户端ID（通常选择“桌面应用”类型）。
   • 下载生成的JSON文件，并将其命名为credentials.json，放置在Python脚本的同一目录下。此文件包含客户端ID和客户端密钥，用于首次启动认证流程。
3. 授权范围 (Scopes)：
   • Scopes定义了你的应用程序可以访问的Google服务和数据类型。选择最小必要的权限至关重要，以降低安全风险。例如，如果你的Apps Script只操作Google Sheets，则只需要https://www.googleapis.com/auth/spreadsheets。
   • 在本文的示例中，为了演示更广泛的集成能力，我们使用了一组相对全面的Scopes，但在实际生产环境中应严格限制。
4. 令牌文件 (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。

注意事项与最佳实践

在实现自动化认证时，务必考虑以下几点以确保安全性、稳定性和可维护性：

1. 最小权限原则 (Least Privilege Principle)：
   • 仔细审查并仅选择你的Apps Script实际运行所需的最小SCOPES。例如，如果你的脚本只读取Google Sheets数据，则不需要https://www.googleapis.com/auth/drive的写入权限。过度授权会增加潜在的安全风险。
2. 凭据文件的安全管理：
   • credentials.json和token.json文件包含敏感的认证信息。绝不能将它们提交到公共版本控制系统（如GitHub）。
   • 在生产环境中，应采用更安全的凭据管理方式，例如：
     • 使用环境变量存储客户端ID和密钥。
     • 利用云服务提供商的密钥管理服务（如Google Secret Manager）。
     • 确保运行脚本的环境具有适当的文件系统权限，以保护这些文件。
3. 刷新令牌的生命周期：
   • 虽然刷新令牌通常具有较长的生命周期（通常是永久的，直到用户撤销授权或Google Cloud项目被删除），但并非绝对永久。在极少数情况下，刷新令牌也可能失效，此时需要重新进行一次完整的用户交互式授权流程。
4. 错误处理与日志记录：
   • 示例代码包含了基本的try-except块来捕获googleapiclient.errors.HttpError和其他通用异常。在实际应用中，应根据业务逻辑进行更细致的错误处理，例如记录详细的错误日志、发送通知或实现重试机制。
   • 解析API响应中的error字段，可以获取Apps Script内部执行失败的具体信息，这对于调试至关重要。
5. 无头（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调用的重复认证问题，实现真正的自动化。这种方法允许开发者构建健壮、无需人工干预的自动化流程，极大地提升了集成效率和可靠性。遵循最小权限原则和严格的安全实践，是确保自动化系统安全运行的关键。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。