מדריך למתחילים ב-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, נכנסים לתפריט > IAM & אדמין > חשבונות שירות.

   לדף Service accounts

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

   לדף Service accounts

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

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

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

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

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

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

   לדף Service accounts

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

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

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

1. במסוף Google Admin, נכנסים לתפריט > אבטחה > שליטה בגישה ובנתונים > פקדי 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. מעתיקים את הקובץ credentials.json בספרייה src/main/resources/. שהורדתם בעבר.

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