Java 快速入门

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

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

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

目标

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

前提条件

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

• 已启用 Google Keep 的 Google 账号。

设置环境

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

启用 API

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

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

  启用 API

创建服务账号

服务账号是由应用（而非个人）使用的特殊账号。您可以使用服务账号通过机器人账号访问数据或执行操作，也可以代表 Google Workspace 或 Cloud Identity 用户访问数据。如需了解详情，请参阅了解服务账号。

Google Cloud 控制台

1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > IAM 和管理 > 服务账号。

   转到“服务账号”

2. 点击创建服务账号。
3. 填写服务账号详细信息，然后点击创建并继续。
   注意：默认情况下，Google 会创建一个唯一的服务账号 ID。如果您想更改 ID，请在“服务账号 ID”字段中修改该 ID。
4. 可选：向服务账号分配角色，以授予对 Google Cloud 项目资源的访问权限。如需了解详情，请参阅授予、更改和撤消对资源的访问权限。
5. 点击继续。
6. 可选：输入可以管理此服务账号并执行操作的用户或群组。如需了解详情，请参阅管理服务账号模拟。
7. 点击完成。记下该服务账号的电子邮件地址。

gcloud CLI

1. 创建服务账号：

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. 可选：向服务账号分配角色，以授予对 Google Cloud 项目资源的访问权限。如需了解详情，请参阅授予、更改和撤消对资源的访问权限。

为服务账号创建凭据

您需要获取公钥/私钥对形式的凭据。您的代码会使用这些凭据来授权应用中的服务账号操作。

1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > IAM 和管理 > 服务账号。

   转到“服务账号”

2. 选择您的服务账号。
3. 依次点击密钥 > 添加密钥 > 创建新密钥。
4. 选择 JSON，然后点击创建。

   系统会生成新的公钥/私钥对，并将其作为新文件下载到您的计算机上。将下载的 JSON 文件保存为工作目录中的 credentials.json。此文件是此密钥的唯一副本。如需了解如何安全地存储密钥，请参阅管理服务账号密钥。

5. 点击关闭。

为服务账号设置全网域委托

如需代表 Google Workspace 组织中的用户调用 API，您的服务账号需要由超级用户账号在 Google Workspace 管理控制台中授予全网域授权。如需了解详情，请参阅向服务账号委派全网域授权。

1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > IAM 和管理 > 服务账号。

   转到“服务账号”

2. 选择您的服务账号。
3. 点击显示高级设置。
4. 在“全网域授权”下，找到您的服务账号的“客户端 ID”。点击“复制”图标 将客户端 ID 值复制到剪贴板。

5. 如果您对相关 Google Workspace 账号拥有超级用户访问权限，请点击查看 Google Workspace 管理控制台，然后使用超级用户账号登录，并继续按照以下步骤操作。

   如果您没有对相关 Google Workspace 账号的超级用户访问权限，请与该账号的超级用户联系，并向其发送您的服务账号的客户 ID 和 OAuth 权限范围列表，以便他们在管理控制台中完成以下步骤。

1. 在 Google 管理控制台中，依次点击“菜单”图标 > 安全性 > 访问权限和数据控件 > API 控件。

   前往“应用访问权限控制”页面

2. 点击管理全网域授权。
3. 点击新增。
4. 在“客户端 ID”字段中，粘贴您之前复制的客户端 ID。
5. 在“OAuth 范围”字段中，输入应用所需的范围的逗号分隔列表。这与您在配置 OAuth 权限请求页面时定义的一组范围相同。
6. 点击授权。

准备工作区

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 = 'KeepQuickstart'
   sourceCompatibility = 1.8
   targetCompatibility = 1.8
   version = '1.0'
   
   sourceCompatibility = 1.8
   
   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-keep: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.gson.GsonFactory;
   import com.google.api.client.util.store.FileDataStoreFactory;
   import com.google.api.services.keep.v1.Keep;
   import com.google.api.services.keep.v1.model.Note;
   import com.google.api.services.keep.v1.model.Section;
   import com.google.api.services.keep.v1.model.TextContent;
   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;
   
   public class KeepQuickstart {
   
     private static final String APPLICATION_NAME = "Google Keep API Java Quickstart";
     private static final JsonFactory JSON_FACTORY = GsonFactory.getDefaultInstance();
   
     /**
      * Global instance of the scopes required by this quickstart. If modifying these scopes, delete
      * your previously saved tokens/ folder.
      */
     private static final List<String> KEEP_SCOPES =
         Collections.singletonList("https://www.googleapis.com/auth/keep");
   
     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
      */
     private static Credential getOAuthCredentials(final NetHttpTransport HTTP_TRANSPORT)
         throws IOException {
       // Load client secrets.
       InputStream in = KeepQuickstart.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, KEEP_SCOPES)
               .setDataStoreFactory(new FileDataStoreFactory(new java.io.File("tokens")))
               .setAccessType("offline")
               .build();
       LocalServerReceiver receiver = new LocalServerReceiver.Builder().setPort(8888).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();
       Keep service =
           new Keep.Builder(HTTP_TRANSPORT, JSON_FACTORY, getOAuthCredentials(HTTP_TRANSPORT))
               .setApplicationName(APPLICATION_NAME)
               .build();
   
       Section noteBody =
           new Section().setText(new TextContent().setText("Finish preparations by tomorrow!"));
       Note newNote = new Note().setTitle("Customer call next week").setBody(noteBody);
   
       // Creates a new text note.
       service.notes().create(newNote).execute();
     }
   }
   
   

运行示例

1. 运行示例：

   gradle run
   

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

   您的 Java 应用运行并调用 Google Keep API。

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

后续步骤

• 排查身份验证和授权问题
• Google Keep API 参考文档
• 适用于 Java 的 Google API 客户端文档
• Google Keep API Javadoc 文档