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

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

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

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

מטרות

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

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

• 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, עוברים לתפריט > IAM & Admin > Service Accounts.

   לדף Service accounts

2. לוחצים על Create service account.
3. ממלאים את פרטי חשבון השירות ולוחצים על Create and continue (יצירה והמשך).
   הערה: כברירת מחדל, Google יוצרת מזהה ייחודי של חשבון שירות. אם רוצים לשנות את המזהה, משנים אותו בשדה Service account ID.
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, עוברים לתפריט > IAM & Admin > Service Accounts.

   לדף Service accounts

2. בוחרים את חשבון השירות.
3. לוחצים על Keys (מפתחות) > Add key (הוספת מפתח) > Create new key (יצירת מפתח חדש).
4. בוחרים באפשרות JSON ולוחצים על Create.

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

5. לוחצים על סגירה.

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

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

1. במסוף Google Cloud, עוברים לתפריט > IAM & Admin > Service Accounts.

   לדף Service accounts

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

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

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

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

   כניסה לדף אמצעי הבקרה של ה-API

2. לוחצים על ניהול הענקת גישה ברמת הדומיין.
3. לוחצים על הוספת חדש.
4. בשדה 'מזהה לקוח', מדביקים את מזהה הלקוח שהעתקתם קודם.
5. בשדה OAuth Scopes (היקפי 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 פועלת ומפעילה את Google Keep API.

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

השלבים הבאים

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