Java 快速入门

创建一个 Java 命令行应用，用于向 Postmaster Tools API 发出请求。

快速入门介绍了如何设置和运行调用 Google Workspace API 的应用。本快速入门使用一种简化的身份验证方法，该方法适用于测试环境。对于生产环境，我们建议您先了解身份验证和授权，然后再选择适合您应用的访问凭据。

本快速入门使用 Google Workspace 推荐的 API 客户端库来处理身份验证和授权流程的一些细节。

目标

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

前提条件

• Java 11 或更高版本。
• Gradle 7.0 或更高版本。
• Google Cloud 项目。

• 已启用 Gmail 的 Google 账号。

设置环境

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

启用 API

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

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

  启用 API

配置 OAuth 权限请求页面

如果您要使用新的 Google Cloud 云项目完成本快速入门，请配置 OAuth 权限请求页面。如果您已为 Cloud 项目完成此步骤，请跳至下一部分。

1. 在 Google API 控制台中，依次前往菜单 menu > Google Auth 平台 > 品牌推广。

   前往“品牌塑造”

2. 如果您已配置 Google Auth 平台，则可以在品牌推广、受众群体和数据访问中配置以下 OAuth 同意屏幕设置。如果您看到一条消息，提示尚未配置 Google Auth 平台，请点击开始使用：
1. 在应用信息下的应用名称中，输入应用的名称。
2. 在用户支持邮箱中，选择一个支持电子邮件地址，以便用户在对自己的同意情况有疑问时与您联系。
3. 点击下一步。
4. 在受众群体下，选择内部。
5. 点击下一步。
6. 在联系信息下，输入一个电子邮件地址，以便您接收有关项目变更的通知。
7. 点击下一步。
8. 在完成部分，查看 Google API 服务用户数据政策，如果您同意该政策，请选择我同意 Google API 服务：用户数据政策。
9. 点击继续。
10. 点击创建。
3. 目前，您可以跳过添加范围的步骤。 未来，如果您创建的应用供 Google Workspace 组织以外的用户使用，则必须将用户类型更改为外部。然后，添加应用所需的授权范围。如需了解详情，请参阅完整的配置 OAuth 同意指南。

为桌面应用授权凭据

如需对最终用户进行身份验证并访问应用中的用户数据，您需要创建一个或多个 OAuth 2.0 客户端 ID。客户端 ID 用于向 Google 的 OAuth 服务器标识单个应用。如果您的应用在多个平台上运行，您必须为每个平台分别创建客户端 ID。

1. 在 Google Cloud 控制台中，依次前往菜单 menu > Google Auth 平台 > 客户端。

   前往“客户”页面

2. 点击创建客户端。
3. 依次点击应用类型 > 桌面应用。
4. 在名称字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 点击创建。

   新创建的凭证会显示在“OAuth 2.0 客户端 ID”下。

6. 将下载的 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 文件，并将其内容替换为以下代码：

     apply plugin: 'java'
   apply plugin: 'application'
   
   mainClassName = 'GmailPostmasterToolsQuickstart'
   sourceCompatibility = 1.8
   targetCompatibility = 1.8
   version = '1.0'
   
   repositories {
       mavenCentral()
   }
   
   dependencies {
       implementation 'com.google.api-client:google-api-client:1.23.0'
       implementation 'com.google.oauth-client:google-oauth-client-jetty:1.23.0'
       implementation 'com.google.apis:google-api-services-gmailpostmastertools:v1-rev20210528-1.31.0'
   }
   

设置示例

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

2. 在新的 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.jackson2.JacksonFactory;
   import com.google.api.client.util.store.FileDataStoreFactory;
   import com.google.api.services.gmailpostmastertools.v2.PostmasterTools;
   import com.google.api.services.gmailpostmastertools.v2.model.*;
   
   import java.io.*;
   import java.security.GeneralSecurityException;
   import java.util.Collections;
   import java.util.List;
   
   public class PostmasterToolsApiQuickStart {
       private static final String APPLICATION_NAME = "PostmasterTools API Java Quickstart";
       private static final JsonFactory JSON_FACTORY = JacksonFactory.getDefaultInstance();
       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("https://www.googleapis.com/auth/postmaster.readonly");
       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 = PostmasterToolsApiQuickStart.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(8891).build();
           return new AuthorizationCodeInstalledApp(flow, receiver).authorize("user");
       }
   
       public static void main(String... args) throws IOException, GeneralSecurityException {
           // Build a new authorized API client service.
           final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
           PostmasterTools postmasterTools = new PostmasterTools.Builder(HTTP_TRANSPORT, JSON_FACTORY, getCredentials(HTTP_TRANSPORT))
                   .setApplicationName(APPLICATION_NAME)
                   .build();
   
           List<Domain> domains = postmasterTools.domains().list().execute().getDomains();
           if (domains == null || domains.isEmpty()) {
               System.out.println("No domains found!");
           } else {
               for (Domain domain : domains) {
                   System.out.println(domain.toPrettyString());
                   System.out.println("Querying stats for " + domain.getName());
                   try {
                       Date startDate = new Date().setYear(2024).setMonth(1).setDay(1);
                       Date endDate = new Date().setYear(2024).setMonth(1).setDay(7);
                       QueryDomainStatsResponse statsResponse = postmasterTools.domains().domainStats()
                               .query(domain.getName())
                               .setStartDate(startDate)
                               .setEndDate(endDate)
                               .execute();
                       System.out.println(statsResponse.toPrettyString());
                   } catch (Exception e) {
                       System.out.println("Error querying stats: " + e.getMessage());
                   }
               }
           }
       }
   }
   
   

运行示例

1. 运行示例：

   gradle run
   

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

   您的 Java 应用运行并调用 Postmaster Tools API。

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

后续步骤

• 在 API 探索器中试用 Google Workspace API
• 排查身份验证和授权问题
• Postmaster Tools API REST 参考文档
• 适用于 Java 的 Google API 客户端文档
• Postmaster Tools API Javadoc 文档