Python 快速入门

快速入门介绍了如何设置和运行调用 Google Workspace API 的应用。

Google Workspace 快速入门使用 API 客户端库来处理身份验证和授权流程的一些细节。我们建议您为自己的应用使用客户端库。本快速入门使用适合测试环境的简化身份验证方法。对于生产环境，我们建议您先了解身份验证和授权，然后再选择适合您的应用的访问凭据。

创建一个向 Gmail API 发出请求的 Python 命令行应用。

目标

  • 设置环境。
  • 安装客户端库。
  • 设置示例。
  • 运行示例。

前提条件

如需运行本快速入门，您需要满足以下前提条件：

  • 已启用 Gmail 的 Google 账号。

设置环境

如需完成本快速入门，请设置您的环境。

启用 API

在使用 Google API 之前，您需要先在 Google Cloud 项目中启用它们。您可以在单个 Google Cloud 项目中启用一个或多个 API。

  • 在 Google Cloud 控制台中，启用 Gmail API。

    启用 API

如果您使用新的 Google Cloud 项目完成本快速入门，请配置 OAuth 同意屏幕，并将自己添加为测试用户。如果您已为 Cloud 项目完成此步骤，请跳至下一部分。

  1. 在 Google Cloud 控制台中，依次点击“菜单”图标 > API 和服务 > OAuth 权限请求页面。

    转到 OAuth 同意屏幕

  2. 在用户类型字段中，选择内部，然后点击创建。
  3. 填写应用注册表单，然后点击保存并继续。

  4. 现在，您可以跳过添加镜重，然后点击保存并继续。 今后，如果您创建的应用要在 Google Workspace 组织之外使用，则必须将用户类型更改为外部，然后添加应用所需的授权范围。

  5. 查看应用注册摘要。如需进行更改，请点击修改。如果应用注册未出现任何问题，请点击返回信息中心。

为桌面应用授权凭据

如需对最终用户进行身份验证并访问应用中的用户数据，您需要创建一个或多个 OAuth 2.0 客户端 ID。客户端 ID 用于向 Google 的 OAuth 服务器标识单个应用。如果您的应用在多个平台上运行，您必须为每个平台分别创建客户端 ID。
  1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > API 和服务 > 凭据。

    进入“凭据”页面

  2. 依次点击创建凭据 > OAuth 客户端 ID。
  3. 依次点击应用类型 > 桌面应用。
  4. 在名称字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
  5. 点击创建。系统随即会显示“OAuth 客户端已创建”屏幕，其中会显示您的新客户端 ID 和客户端密钥。
  6. 点击确定。新创建的凭据会显示在 OAuth 2.0 客户端 ID 下。
  7. 将下载的 JSON 文件另存为 credentials.json，然后将该文件移至您的工作目录。

安装 Google 客户端库

  • 安装 Python 版 Google 客户端库：

    pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

配置示例

  1. 在工作目录中，创建一个名为 quickstart.py 的文件。

  2. 在 quickstart.py 中添加以下代码：

    gmail/quickstart/quickstart.py
    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.discovery import build
from googleapiclient.errors import HttpError

# If modifying these scopes, delete the file token.json.
SCOPES = ["https://www.googleapis.com/auth/gmail.readonly"]


def main():
  """Shows basic usage of the Gmail API.
  Lists the user's Gmail labels.
  """
  creds = None
  # The file token.json stores the user's access and refresh tokens, and is
  # created automatically when the authorization flow completes for the first
  # time.
  if os.path.exists("token.json"):
    creds = Credentials.from_authorized_user_file("token.json", SCOPES)
  # If there are no (valid) credentials available, let the user log in.
  if not creds or not creds.valid:
    if creds and creds.expired and creds.refresh_token:
      creds.refresh(Request())
    else:
      flow = InstalledAppFlow.from_client_secrets_file(
          "credentials.json", SCOPES
      )
      creds = flow.run_local_server(port=0)
    # Save the credentials for the next run
    with open("token.json", "w") as token:
      token.write(creds.to_json())

  try:
    # Call the Gmail API
    service = build("gmail", "v1", credentials=creds)
    results = service.users().labels().list(userId="me").execute()
    labels = results.get("labels", [])

    if not labels:
      print("No labels found.")
      return
    print("Labels:")
    for label in labels:
      print(label["name"])

  except HttpError as error:
    # TODO(developer) - Handle errors from gmail API.
    print(f"An error occurred: {error}")


if __name__ == "__main__":
  main()

运行示例

  1. 在工作目录中，构建并运行示例：

    python3 quickstart.py
  1. 首次运行该示例时，系统会提示您授予访问权限：
    1. 如果您尚未登录 Google 账号，请在系统提示时登录。如果您登录了多个账号，请选择一个账号用于授权。
    2. 点击接受。

    您的 Python 应用运行并调用 Gmail API。

    授权信息会存储在文件系统中，因此当您下次运行示例代码时，系统不会提示您进行授权。

后续步骤