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

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

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

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

מטרות

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

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

• 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, נכנסים לתפריט menu > ממשקי API ו- שירותים > מסך ההסכמה של OAuth.

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

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

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

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

אישור פרטי כניסה לאפליקציה בשולחן העבודה

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

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

   כניסה לדף Credentials

2. לוחצים על יצירת פרטי כניסה > מזהה לקוח OAuth.
3. לוחצים על סוג אפליקציה > אפליקציית מחשב.
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. מעתיקים את הקובץ credentials.json בספרייה src/main/resources/. שהורדתם בעבר.

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 ל-Java
• מסמכי תיעוד של Javadoc בשביל Google Vault API