מדריך למתחילים בנושא Java

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

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

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

מטרות

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

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

• ‫Java מגרסה 11 ומעלה.
• ‫Gradle 7.0 ואילך.
• פרויקט ב-Google Cloud.

• דומיין ב-Google Workspace עם גישה מופעלת ל-API.
• חשבון Google בדומיין הזה עם הרשאות אדמין.

מגדירים את הסביבה

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

מפעילים את ה-API

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

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

  להפעלת ה-API

מגדירים את מסך ההסכמה של OAuth

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

1. ב-Google API Console, נכנסים לתפריט > פלטפורמת האימות של Google > מיתוג.

   מעבר לדף Branding

2. אם כבר הגדרתם את פלטפורמת האימות של Google, אתם יכולים לקבוע את ההגדרות הבאות של מסך ההסכמה ל-OAuth בקטעים מיתוג, קהל וגישה לנתונים. אם מופיעה ההודעה Google Auth platform not configured yet, לוחצים על Get Started:
1. בקטע App Information בשדה App name, מזינים שם לאפליקציה.
2. בקטע User support email, בוחרים כתובת אימייל לתמיכה שאליה משתמשים יפנו אם יש להם שאלות לגבי ההסכמה שלהם.
3. לוחצים על Next.
4. בקטע Audience, לוחצים על Internal.
5. לוחצים על Next.
6. בקטע Contact Information, מזינים כתובת אימייל שאליה אפשר לשלוח התראות על שינויים בפרויקט.
7. לוחצים על Next.
8. בקטע Finish, קוראים את המדיניות של Google בנושא נתוני משתמשים בשירותי API. אם אתם מסכימים, מסמנים את התיבה I agree to the Google API Services: User Data Policy.
9. לוחצים על Continue.
10. לוחצים על Create.
3. כרגע אתם יכולים לדלג על הוספת היקפי הרשאות. בעתיד, כשתיצרו אפליקציה לשימוש מחוץ לארגון שלכם ב-Google Workspace, תצטרכו לשנות את סוג המשתמש ל-External. לאחר מכן מוסיפים את היקפי ההרשאות שהאפליקציה דורשת. למידע נוסף, אפשר לעיין במדריך המלא בנושא הגדרת הסכמה ל-OAuth.

מאשרים את פרטי הכניסה של האפליקציה למחשב

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

1. במסוף Google Cloud, פותחים את התפריט > Google Auth platform > Clients.

   מעבר אל "לקוחות"

2. לוחצים על Create Client.
3. לוחצים על Application type‏ > Desktop app.
4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
5. אופציונלי: אם האפליקציה היא סוכן AI שמבצע פעולות בשם המשתמשים, בוחרים באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI. אם האפליקציה תומכת גם בתהליכי עבודה של סוכני AI וגם בתכונות רגילות למשתמשים, צריך ליצור לקוחות OAuth נפרדים לכל אחד מהם. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את הלקוח.
6. לוחצים על יצירה.

   פרטי הכניסה החדשים שנוצרו מופיעים בקטע OAuth 2.0 Client IDs.

7. שומרים את קובץ ה-JSON בשם credentials.json ומעבירים את הקובץ לספריית העבודה.

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

1. בספריית העבודה, יוצרים מבנה פרויקט חדש:

   gradle init --type basic
   mkdir -p src/main/java src/main/resources 
   

2. בספרייה src/main/resources/, מעתיקים את הקובץ credentials.json שהורדתם קודם.

3. פותחים את קובץ ברירת המחדל build.gradle ומחליפים את התוכן שלו בקוד הבא:

   adminSDK/directory/quickstart/build.gradle

   הצגת הקוד ב-GitHub
   apply plugin: 'java'
   apply plugin: 'application'
   
   mainClassName = 'AdminSDKDirectoryQuickstart'
   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-admin-directory:directory_v1-rev20220919-2.0.0'
   }

מגדירים את הדוגמה

1. בספרייה src/main/java/, יוצרים קובץ Java חדש עם שם שתואם לערך mainClassName בקובץ build.gradle.

2. מוסיפים את הקוד הבא לקובץ ה-Java החדש:

   adminSDK/directory/quickstart/src/main/java/AdminSDKDirectoryQuickstart.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.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.directory.Directory;
   import com.google.api.services.directory.DirectoryScopes;
   import com.google.api.services.directory.model.User;
   import com.google.api.services.directory.model.Users;
   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 AdminSDKDirectoryQuickstart {
     /**
      * Application name.
      */
     private static final String APPLICATION_NAME = "Google Admin SDK Directory API Java Quickstart";
     /**
      * Global instance of the JSON factory.
      */
     private static final JsonFactory JSON_FACTORY = GsonFactory.getDefaultInstance();
     /**
      * Directory to store authorization tokens for this application.
      */
     private static final String TOKENS_DIRECTORY_PATH = "tokens";
   
     /**
      * Global instance of the scopes required by this quickstart.
      * If modifying these scopes, delete your previously saved tokens/ folder.
      */
     private static final List<String> SCOPES =
         Collections.singletonList(DirectoryScopes.ADMIN_DIRECTORY_USER_READONLY);
     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 If the credentials.json file cannot be found.
      */
     private static Credential getCredentials(final NetHttpTransport HTTP_TRANSPORT)
         throws IOException {
       // Load client secrets.
       InputStream in = AdminSDKDirectoryQuickstart.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, SCOPES)
           .setDataStoreFactory(new FileDataStoreFactory(new java.io.File(TOKENS_DIRECTORY_PATH)))
           .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();
       Directory service =
           new Directory.Builder(HTTP_TRANSPORT, JSON_FACTORY, getCredentials(HTTP_TRANSPORT))
               .setApplicationName(APPLICATION_NAME)
               .build();
   
       // Print the first 10 users in the domain.
       Users result = service.users().list()
           .setCustomer("my_customer")
           .setMaxResults(10)
           .setOrderBy("email")
           .execute();
       List<User> users = result.getUsers();
       if (users == null || users.size() == 0) {
         System.out.println("No users found.");
       } else {
         System.out.println("Users:");
         for (User user : users) {
           System.out.println(user.getName().getFullName());
         }
       }
     }
   }

מריצים את הדוגמה

1. מריצים את הדוגמה:

   gradle run
   

2. בפעם הראשונה שמריצים את הקוד לדוגמה, מופיעה בקשה לאשר את הגישה:
   1. אם עדיין לא נכנסתם לחשבון Google, תתבקשו להיכנס אליו. אם נכנסתם לכמה חשבונות, בחרו חשבון אחד שבו תרצו להשתמש לצורך הרשאה.
   2. לוחצים על Accept.

   אפליקציית Java פועלת ושולחת קריאה ל-Directory API.

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

השלבים הבאים

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