Java 快速入门

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

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

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

目标

  • 设置环境。
  • 设置示例。
  • 运行示例。

前提条件

  • 已启用 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，然后将该文件移至您的工作目录。

准备工作区

  1. 在工作目录中，创建一个新的项目结构：

    gradle init --type basic
mkdir -p src/main/java src/main/resources

  2. 在 src/main/resources/ 目录中，复制您之前下载的 credentials.json 文件。

  3. 打开默认的 build.gradle 文件，并将其内容替换为以下代码：

    gmail/quickstart/build.gradle
    apply plugin: 'java'
apply plugin: 'application'

mainClassName = 'GmailQuickstart'
sourceCompatibility = 11
targetCompatibility = 11
version = '1.0'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.google.api-client:google-api-client:2.0.0'
    implementation 'com.google.oauth-client:google-oauth-client-jetty:1.34.1'
    implementation 'com.google.apis:google-api-services-gmail:v1-rev20220404-2.0.0'
}

设置示例

  1. 在 src/main/java/ 目录中，创建一个新的 Java 文件，其名称与 build.gradle 文件中的 mainClassName 值匹配。

  2. 在新 Java 文件中添加以下代码：

    gmail/quickstart/src/main/java/GmailQuickstart.java
    import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.extensions.java6.auth.oauth2.AuthorizationCodeInstalledApp;
import com.google.api.client.extensions.jetty.auth.oauth2.LocalServerReceiver;
import com.google.api.client.googleapis.auth.oauth2.GoogleAuthorizationCodeFlow;
import com.google.api.client.googleapis.auth.oauth2.GoogleClientSecrets;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.client.util.store.FileDataStoreFactory;
import com.google.api.services.gmail.Gmail;
import com.google.api.services.gmail.GmailScopes;
import com.google.api.services.gmail.model.Label;
import com.google.api.services.gmail.model.ListLabelsResponse;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.security.GeneralSecurityException;
import java.util.Collections;
import java.util.List;

/* class to demonstrate use of Gmail list labels API */
public class GmailQuickstart {
  /**
   * Application name.
   */
  private static final String APPLICATION_NAME = "Gmail API Java Quickstart";
  /**
   * Global instance of the JSON factory.
   */
  private static final JsonFactory JSON_FACTORY = GsonFactory.getDefaultInstance();
  /**
   * Directory to store authorization tokens for this application.
   */
  private static final String TOKENS_DIRECTORY_PATH = "tokens";

  /**
   * Global instance of the scopes required by this quickstart.
   * If modifying these scopes, delete your previously saved tokens/ folder.
   */
  private static final List<String> SCOPES = Collections.singletonList(GmailScopes.GMAIL_LABELS);
  private static final String CREDENTIALS_FILE_PATH = "/credentials.json";

  /**
   * Creates an authorized Credential object.
   *
   * @param HTTP_TRANSPORT The network HTTP Transport.
   * @return An authorized Credential object.
   * @throws IOException If the credentials.json file cannot be found.
   */
  private static Credential getCredentials(final NetHttpTransport HTTP_TRANSPORT)
      throws IOException {
    // Load client secrets.
    InputStream in = GmailQuickstart.class.getResourceAsStream(CREDENTIALS_FILE_PATH);
    if (in == null) {
      throw new FileNotFoundException("Resource not found: " + CREDENTIALS_FILE_PATH);
    }
    GoogleClientSecrets clientSecrets =
        GoogleClientSecrets.load(JSON_FACTORY, new InputStreamReader(in));

    // Build flow and trigger user authorization request.
    GoogleAuthorizationCodeFlow flow = new GoogleAuthorizationCodeFlow.Builder(
        HTTP_TRANSPORT, JSON_FACTORY, clientSecrets, SCOPES)
        .setDataStoreFactory(new FileDataStoreFactory(new java.io.File(TOKENS_DIRECTORY_PATH)))
        .setAccessType("offline")
        .build();
    LocalServerReceiver receiver = new LocalServerReceiver.Builder().setPort(8888).build();
    Credential credential = new AuthorizationCodeInstalledApp(flow, receiver).authorize("user");
    //returns an authorized Credential object.
    return credential;
  }

  public static void main(String... args) throws IOException, GeneralSecurityException {
    // Build a new authorized API client service.
    final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
    Gmail service = new Gmail.Builder(HTTP_TRANSPORT, JSON_FACTORY, getCredentials(HTTP_TRANSPORT))
        .setApplicationName(APPLICATION_NAME)
        .build();

    // Print the labels in the user's account.
    String user = "me";
    ListLabelsResponse listResponse = service.users().labels().list(user).execute();
    List<Label> labels = listResponse.getLabels();
    if (labels.isEmpty()) {
      System.out.println("No labels found.");
    } else {
      System.out.println("Labels:");
      for (Label label : labels) {
        System.out.printf("- %s\n", label.getName());
      }
    }
  }
}

运行示例

  1. 运行示例：

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

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

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

后续步骤