بدء استخدام Java

إنشاء تطبيق يستند إلى أسطر الأوامر بلغة Java ويرسل طلبات إلى Directory API

توضّح أدلة البدء السريع كيفية إعداد تطبيق وتشغيله لإرسال طلبات إلى Google Workspace API. يستخدم دليل البدء السريع هذا طريقة مصادقة مبسطة مناسبة لبيئة الاختبار. بالنسبة إلى بيئة الإنتاج، ننصحك بالتعرّف على المصادقة والتفويض قبل اختيار بيانات الاعتماد المناسبة لتطبيقك.

يستخدم دليل البدء السريع هذا مكتبات عملاء واجهة برمجة التطبيقات المقترَحة من Google Workspace للتعامل مع بعض تفاصيل عملية المصادقة والتفويض.

الأهداف

• إعداد البيئة
• إعداد النموذج
• تشغيل النموذج

المتطلبات الأساسية

• الإصدار 11 من Java أو إصدار أحدث
• الإصدار 7.0 من Gradle أو إصدار أحدث.
• مشروع على Google Cloud.

• نطاق Google Workspace تم تفعيل إمكانية الوصول إلى واجهة برمجة التطبيقات فيه .
• حساب على Google في هذا النطاق لديه امتيازات المشرف

إعداد البيئة

لإكمال دليل البدء السريع هذا، عليك إعداد البيئة.

تفعيل واجهة برمجة التطبيقات

قبل استخدام Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيق واحدة أو أكثر في مشروع واحد على Google Cloud.

• في Google Cloud Console، فعِّل Directory API.

  تفعيل واجهة برمجة التطبيقات

إعداد شاشة موافقة OAuth

إذا كنت تستخدم مشروعًا جديدًا على Google Cloud لإكمال دليل البدء السريع هذا، عليك إعداد شاشة موافقة OAuth. إذا سبق لك إكمال هذه الخطوة لمشروعك على Cloud، انتقِل إلى القسم التالي.

1. في Google API Console، انتقِل إلى "القائمة" > منصة Google للمصادقة > العلامة التجارية.

   الانتقال إلى العلامة التجارية

2. إذا سبق لك إعداد منصة Google للمصادقة، يمكنك إعداد إعدادات شاشة موافقة OAuth التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك رسالة لم يتم إعداد منصة Google للمصادقة بعد، انقر على البدء:
1. ضمن معلومات التطبيق، في اسم التطبيق، أدخِل اسمًا للتطبيق.
2. في البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريد إلكتروني للدعم يمكن للمستخدمين التواصل معك من خلاله إذا كانت لديهم أسئلة حول موافقتهم.
3. انقر على التالي.
4. ضمن الجمهور، اختَر داخلي.
5. انقر على التالي.
6. ضمن معلومات الاتصال ، أدخِل عنوان بريد إلكتروني يمكن إعلامك من خلاله بأي تغييرات تطرأ على مشروعك.
7. انقر على التالي.
8. ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API، وإذا كنت موافقًا عليها، ضَع علامة في المربّع أوافق على "سياسة بيانات المستخدمين في خدمات Google API".
9. انقر على متابعة.
10. انقر على إنشاء.
3. يمكنك في الوقت الحالي تخطّي إضافة النطاقات. في المستقبل، عند إنشاء تطبيق لاستخدامه خارج مؤسسة Google Workspace، عليك تغيير نوع المستخدم إلى خارجي. بعد ذلك، أضِف نطاقات التفويض التي يتطلبها تطبيقك. لمزيد من المعلومات، اطّلِع على دليل إعداد شاشة موافقة OAuth الكامل .

تفويض بيانات اعتماد لتطبيق على الكمبيوتر

لمصادقة المستخدمين النهائيين والوصول إلى بيانات المستخدمين في تطبيقك، عليك إنشاء معرّف عميل واحد أو أكثر لبروتوكول OAuth 2.0. يُستخدم معرّف العميل لتعريف تطبيق واحد على خوادم OAuth من Google. إذا كان تطبيقك يعمل على منصات متعددة، عليك إنشاء معرّف عميل منفصل لكل منصة.

1. في Google Cloud Console، انتقِل إلى "القائمة" > منصة Google للمصادقة > العملاء.

   الانتقال إلى العملاء

2. انقر على إنشاء عميل.
3. انقر على نوع التطبيق > تطبيق على الكمبيوتر.
4. في حقل الاسم ، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في Google Cloud Console.
5. انقر على إنشاء.

   تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن "معرّفات عملاء OAuth 2.0".

6. احفظ ملف 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. انقر على حسنًا.

   يتم تشغيل تطبيق Java وإرسال طلبات إلى Directory API.

   يتم تخزين معلومات التفويض في نظام الملفات، لذا لن يُطلب منك منح التفويض في المرة التالية التي تشغِّل فيها نموذج الرمز.

الخطوات التالية

• تجربة Google Workspace APIs في مستكشف واجهات برمجة التطبيقات
• تحديد مشاكل المصادقة والتفويض وحلّها
• أدلة المطوّرين في Directory API
• المستندات المرجعية في Directory API
• مستندات Google APIs Client for Java
• مستندات Javadoc في Directory API