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

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

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

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

מטרות

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

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

• Java 1.8 ומעלה.
• Gradle 7.0 ואילך.
• פרויקט של Google Cloud.

• חשבון Google שמופעל בו Google Keep.

הגדרת הסביבה

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

הפעלת ה-API

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

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

  להפעלת ה-API

יצירה של חשבון שירות

חשבון שירות הוא סוג מיוחד של חשבון, שמשמש אפליקציה ולא אדם. תוכלו להשתמש בחשבון שירות כדי לגשת לנתונים או לבצע פעולות באמצעות החשבון הרובוטי, או כדי לגשת לנתונים בשם משתמשי Google Workspace או Cloud Identity. למידע נוסף, ראו הסבר על חשבונות שירות.

מסוף Google Cloud

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

   לדף Service accounts

2. לוחצים על Create service account.
3. ממלאים את פרטי חשבון השירות ולוחצים על Create and continue.
4. אופציונלי: מקצים תפקידים לחשבון השירות כדי לתת גישה למשאבים של הפרויקט ב-Google Cloud. פרטים נוספים זמינים במאמר הענקה, שינוי וביטול גישה למשאבים.
5. לוחצים על המשך.
6. אופציונלי: מזינים משתמשים או קבוצות שיכולים לנהל ולבצע פעולות באמצעות חשבון השירות הזה. פרטים נוספים זמינים במאמר ניהול התחזות לחשבון שירות.
7. לוחצים על סיום. רושמים בצד את כתובת האימייל של חשבון השירות.

‫CLI של gcloud

1. יוצרים את חשבון השירות:

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

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

יצירת פרטי כניסה לחשבון שירות

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

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

   לדף Service accounts

2. בוחרים את חשבון השירות.
3. לוחצים על מפתחות > הוספת מפתח > יצירת מפתח חדש.
4. בוחרים באפשרות JSON ולאחר מכן לוחצים על יצירה.

   זוג המפתחות הציבורי/הפרטי החדש נוצר ומורידים למחשב כקובץ חדש. שומרים את קובץ ה-JSON שהורדתם בתור credentials.json בספריית העבודה. הקובץ הזה הוא העותק היחיד של המפתח הזה. מידע נוסף על אחסון המפתח באופן מאובטח זמין במאמר ניהול מפתחות של חשבונות שירות.

5. לוחצים על Close.

הגדרה של הענקת גישה ברמת הדומיין לחשבון שירות

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

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

   לדף Service accounts

2. בוחרים את חשבון השירות.
3. לוחצים על הצגת הגדרות מתקדמות.
4. בקטע 'הענקת גישה ברמת הדומיין', מאתרים את 'מזהה הלקוח' של חשבון השירות. לוחצים על 'העתקה' content_copy כדי להעתיק את הערך של מזהה הלקוח ללוח.

5. אם יש לכם הרשאת סופר-אדמין בחשבון Google Workspace הרלוונטי, לוחצים על הצגת מסוף Admin ב-Google Workspace, ואז נכנסים באמצעות חשבון משתמש של סופר-אדמין וממשיכים לבצע את השלבים האלה.

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

1. במסוף Google Admin, נכנסים לתפריט menu > אבטחה > בקרת גישה ונתונים > בקרות API.

   למעבר אל 'אמצעי בקרה ל-API'

2. לוחצים על Manage Domain Wide Delegation.
3. לוחצים על חדש.
4. בשדה Client ID (מזהה הלקוח), מדביקים את מזהה הלקוח שהעתקתם קודם לכן.
5. בשדה 'היקפי הרשאות OAuth', מזינים רשימה מופרדת בפסיקים של היקפי ההרשאות שנדרשים לאפליקציה. זו אותה קבוצת היקפים שהגדרת כשהגדרת את מסך ההסכמה ל-OAuth.
6. לוחצים על Authorize.

הכנת סביבת העבודה

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 חדש בשם שתואם לערך של mainClassName בקובץ build.gradle.

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 מפעילה את ממשק ה-API של Google Keep ומבצעת אותו.

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

השלבים הבאים

• פתרון בעיות באימות ובהרשאה
• מאמרי העזרה של Google Keep API
• מסמכי תיעוד של לקוח Google APIs ל-Java
• מסמכי תיעוד של Google Keep API ל-Javadoc