在Python中使用Google API刷新令牌：树莓派Gmail应用周期性报错排查

嘿，看你这情况——树莓派上跑的个人Gmail查询应用，每30秒查一次，结果每隔一周左右就在调用messages().list().execute()的时候报错，错误栈还指向oauth2client库。结合长期后台运行的场景，我给你梳理几个最可能的原因和实操的解决思路：

1. 旧OAuth库的令牌刷新坑 #

你用的oauth2client其实早就被Google弃用了，它的令牌刷新逻辑在长期运行（比如连续跑一周）的场景下很容易出问题——比如刷新令牌悄悄过期了，或者代码没正确捕获刷新失败的异常。

• 先搞清楚你用的是桌面应用OAuth令牌还是服务账号凭证？如果是桌面令牌，虽然刷新令牌有效期通常很长，但某些情况下会失效；而服务账号的凭证刷新机制更稳定，特别适合这种24/7跑的后台应用。
• 如果暂时不想换库，那得给代码加个异常处理，专门捕获令牌过期的错误，触发重新刷新：

  from oauth2client.client import HttpAccessTokenRefreshError
  
  try:
      messages = gmail.users().messages().list(userId='me').execute()
  except HttpAccessTokenRefreshError:
      # 这里重新加载凭证或者触发重新授权逻辑
      credentials = refresh_my_credentials()
      gmail = build('gmail', 'v1', credentials=credentials)
      messages = gmail.users().messages().list(userId='me').execute()
  

2. 赶紧升级到官方推荐的新Auth库 #

既然oauth2client已经被弃用，不如直接换用Google现在主推的google-auth系列库，这些库的长期运行稳定性强太多，令牌刷新逻辑也更靠谱。

• 先卸载旧库，装新依赖：

  pip uninstall oauth2client -y
  pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client
  

• 重构你的凭证加载代码，新库会自动处理令牌刷新，甚至会把刷新后的令牌自动存回文件：

  from google.oauth2.credentials import Credentials
  from googleapiclient.discovery import build
  from google.auth.transport.requests import Request
  
  def get_gmail_service():
      # 加载之前生成的token.json
      creds = Credentials.from_authorized_user_file('token.json', ['https://www.googleapis.com/auth/gmail.readonly'])
      
      # 自动检查令牌有效性，过期就刷新并保存
      if not creds or not creds.valid:
          if creds and creds.expired and creds.refresh_token:
              creds.refresh(Request())
              with open('token.json', 'w') as token_file:
                  token_file.write(creds.to_json())
      
      return build('gmail', 'v1', credentials=creds)
  

  这样每次调用服务的时候，都会自动搞定令牌的事儿，不用你手动操心，长期运行稳得一批。

3. 给请求加个重试机制 #

树莓派长期连网，偶尔的网络波动或者Google API临时限流也可能导致请求失败，加个重试逻辑就能避免单次错误直接把应用搞挂。

可以用tenacity库来实现优雅的重试，或者自己写个简单的循环：

from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
from googleapiclient.errors import HttpError

# 最多重试3次，每次等待时间指数增长
@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10), retry=retry_if_exception_type(HttpError))
def fetch_gmail_messages():
    gmail_service = get_gmail_service()
    return gmail_service.users().messages().list(userId='me').execute()

这样遇到临时的429限流、503服务不可用这类错误，会自动重试，不会直接报错。

4. 最后检查下API配额和权限 #

虽然你每30秒一次的调用频率很低，一周才3000多次，远低于Gmail API每日10000次的配额，但还是可以去Google Cloud控制台看看你的项目有没有配额超限的情况。另外，确保你的令牌有gmail.readonly权限，权限不够也会导致执行失败。

总的来说，最优先的建议是升级到新的Google Auth库，旧的oauth2client确实容易在长期运行时出各种奇怪的问题，换库之后大部分问题都能解决。

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