מדריך למתחילים ב-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 & Admin > חשבונות שירות.

   כניסה לדף 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 & Admin > חשבונות שירות.

   כניסה לדף Service Accounts

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

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

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

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

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

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

   כניסה לדף Service Accounts

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

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

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

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

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

2. לוחצים על ניהול הענקת גישה ברמת הדומיין.
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
• מסמכי תיעוד של Javadoc ל-Google Keep API