מדריך למתחילים ב-Java

במדריכים למתחילים מוסבר איך מגדירים ומפעילים אפליקציה שמפעילה קריאה ל-Google Workspace API.

במדריכים למתחילים של Google Workspace נעשה שימוש בספריות הלקוח של ה-API כדי לטפל בחלק מהפרטים של תהליך האימות וההרשאה. מומלץ להשתמש בספריות הלקוח באפליקציות שלכם. במדריך למתחילים הזה נעשה שימוש בגישה פשוטה לאימות שמתאימה לסביבת בדיקה. בסביבת ייצור, מומלץ לקרוא על אימות והרשאה לפני בחירת פרטי הכניסה שמתאימים לאפליקציה.

יצירת אפליקציית שורת פקודה ב-Java ששולחת בקשות ל-Google Vault API.

מטרות

• מגדירים את הסביבה.
• מגדירים את המדגם.
• מריצים את הדוגמה.

דרישות מוקדמות

• Java מגרסה 1.8 ואילך.
• Gradle מגרסה 7.0 ואילך.
• פרויקט ב-Google Cloud.

• חשבון Google.

הגדרת הסביבה

כדי להשלים את המדריך למתחילים הזה, צריך להגדיר את הסביבה.

הפעלת ה-API

לפני שמשתמשים ב-Google APIs, צריך להפעיל אותם בפרויקט ב-Google Cloud. אפשר להפעיל ממשק API אחד או יותר בפרויקט אחד ב-Google Cloud.

• במסוף Google Cloud, מפעילים את Google Vault API.

  להפעלת ה-API

הגדרת מסך ההסכמה של OAuth

אם אתם משתמשים בפרויקט חדש ב-Google Cloud כדי להשלים את המדריך למתחילים הזה, תצטרכו להגדיר את מסך ההסכמה של OAuth ולהוסיף את עצמכם כמשתמשי בדיקה. אם כבר השלמתם את השלב הזה בפרויקט ב-Cloud, תוכלו לדלג לקטע הבא.

1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > OAuth consent screen.

   מעבר למסך ההסכמה של OAuth

2. בקטע User type בוחרים באפשרות Internal ולוחצים על Create.
3. ממלאים את טופס הרישום של האפליקציה ולוחצים על שמירה והמשך.

4. בשלב הזה, אפשר לדלג על הוספת היקפי הרשאה וללחוץ על Save and Continue (שמירה והמשך). בעתיד, כשיוצרים אפליקציה לשימוש מחוץ לארגון ב-Google Workspace, צריך לשנות את סוג המשתמש ל-חיצוני, ואז להוסיף את היקפי ההרשאה הנדרשים לאפליקציה.

5. בודקים את סיכום רישום האפליקציה. כדי לבצע שינויים, לוחצים על עריכה. אם הרשמת האפליקציה נראית תקינה, לוחצים על Back to Dashboard.

מתן הרשאה לפרטי כניסה לאפליקציה למחשב

כדי לאמת משתמשי קצה ולגשת לנתוני המשתמשים באפליקציה, צריך ליצור מזהה לקוח אחד או יותר ב-OAuth 2.0. מזהה לקוח משמש לזיהוי אפליקציה אחת בשרתי OAuth של Google. אם האפליקציה פועלת בכמה פלטפורמות, צריך ליצור מזהה לקוח נפרד לכל פלטפורמה.

1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

   כניסה לדף Credentials

2. לוחצים על Create Credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth).
3. לוחצים על Application type (סוג האפליקציה) > Desktop app (אפליקציה למחשב).
4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
5. לוחצים על יצירה. יופיע המסך 'לקוח OAuth נוצר', שבו יוצגו מזהה הלקוח וסוד הלקוח החדשים.
6. לוחצים על אישור. פרטי הכניסה שנוצרו מופיעים בקטע מזהי לקוח OAuth 2.0.
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 ומחליפים את התוכן שלו בקוד הבא:

   vault/quickstart/build.gradle

   הצגת הקוד ב-GitHub
   apply plugin: 'java'
   apply plugin: 'application'
   
   mainClassName = 'Quickstart'
   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-vault:v1-rev20220423-2.0.0'
   }

הגדרת הדוגמה

1. בספרייה src/main/java/, יוצרים קובץ Java חדש עם שם שתואם לערך mainClassName בקובץ build.gradle.

2. מוסיפים את הקוד הבא לקובץ ה-Java החדש:

   vault/quickstart/src/main/java/Quickstart.java

   הצגת הקוד ב-GitHub
   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.HttpTransport;
   import com.google.api.client.json.gson.GsonFactory;
   import com.google.api.client.json.JsonFactory;
   import com.google.api.client.util.store.FileDataStoreFactory;
   import com.google.api.services.vault.v1.VaultScopes;
   import com.google.api.services.vault.v1.model.*;
   import com.google.api.services.vault.v1.Vault;
   
   import java.io.FileNotFoundException;
   import java.io.IOException;
   import java.io.InputStream;
   import java.io.InputStreamReader;
   import java.util.Arrays;
   import java.util.List;
   
   public class Quickstart {
     /**
      * Application name.
      */
     private static final String APPLICATION_NAME =
         "Google Vault API Java Quickstart";
   
     /**
      * Directory to store authorization tokens for this application.
      */
     private static final java.io.File DATA_STORE_DIR = new java.io.File("tokens");
     /**
      * Global instance of the JSON factory.
      */
     private static final JsonFactory JSON_FACTORY = GsonFactory.getDefaultInstance();
     private static final String CREDENTIALS_FILE_PATH = "/credentials.json";
     /**
      * Global instance of the scopes required by this quickstart.
      * <p>
      * If modifying these scopes, delete your previously saved credentials
      * at ~/.credentials/vault.googleapis.com-java-quickstart
      */
     private static final List<String> SCOPES =
         Arrays.asList(VaultScopes.EDISCOVERY_READONLY);
     /**
      * Global instance of the {@link FileDataStoreFactory}.
      */
     private static FileDataStoreFactory DATA_STORE_FACTORY;
     /**
      * Global instance of the HTTP transport.
      */
     private static HttpTransport HTTP_TRANSPORT;
   
     static {
       try {
         HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
         DATA_STORE_FACTORY = new FileDataStoreFactory(DATA_STORE_DIR);
       } catch (Throwable t) {
         t.printStackTrace();
         System.exit(1);
       }
     }
   
     /**
      * Creates an authorized Credential object.
      *
      * @return an authorized Credential object.
      * @throws IOException
      */
     public static Credential authorize() throws IOException {
       // Load client secrets.
       InputStream in =
           Quickstart.class.getResourceAsStream("/credentials.json");
       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(DATA_STORE_FACTORY)
               .setAccessType("offline")
               .build();
       Credential credential = new AuthorizationCodeInstalledApp(
           flow, new LocalServerReceiver()).authorize("user");
       System.out.println(
           "Credentials saved to " + DATA_STORE_DIR.getAbsolutePath());
       return credential;
     }
   
     /**
      * Build and return an authorized Vault client service.
      *
      * @return an authorized Vault client service
      * @throws IOException
      */
     public static Vault getVaultService() throws IOException {
       Credential credential = authorize();
       return new Vault.Builder(HTTP_TRANSPORT, JSON_FACTORY, credential)
           .setApplicationName(APPLICATION_NAME)
           .build();
     }
   
     public static void main(String[] args) throws IOException {
       // Build a new authorized API client service.
       Vault service = getVaultService();
   
       // List the first 10 matters.
       ListMattersResponse response = service.matters().list()
           .setPageSize(10)
           .execute();
       List<Matter> matters = response.getMatters();
       if (matters == null || matters.size() == 0) {
         System.out.println("No matters found.");
         return;
       }
       System.out.println("Matters:");
       for (Matter matter : matters) {
         System.out.printf("%s (%s)\n", matter.getName(),
             matter.getMatterId());
       }
     }
   }

הרצת הדוגמה

1. מריצים את הדוגמה:

   gradle run
   

2. בפעם הראשונה שתפעילו את הדוגמה, תתבקשו לאשר את הגישה:
   1. אם עדיין לא נכנסתם לחשבון Google, נכנסים אליו כשמופיעה בקשה לעשות זאת. אם נכנסתם לכמה חשבונות, בוחרים חשבון אחד לצורך ההרשאה.
   2. לוחצים על אישור.

   אפליקציית Java פועלת ומפעילה את Google Vault API.

   פרטי ההרשאה מאוחסנים במערכת הקבצים, כך שבפעם הבאה שתפעילו את הקוד לדוגמה לא תתבקשו להעניק הרשאה.

השלבים הבאים

• פתרון בעיות באימות ובהרשאות
• מאמרי העזרה של Vault API
• משאבי עזרה ל-Google APIs Client for Java
• מסמכי תיעוד של Javadoc בנושא Google Vault API