بدء استخدام Java

توضّح عمليات البدء السريع كيفية إعداد تطبيق يستدعي واجهة برمجة التطبيقات Google Workspace API وتشغيله.

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

أنشئ تطبيق سطر أوامر Java يُرسل طلبات إلى Google Calendar API.

الأهداف

• اضبط إعدادات البيئة.
• إعداد العيّنة
• شغِّل العيّنة.

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

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

• حساب Google تم تفعيل "تقويم Google" فيه

إعداد البيئة

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

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

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

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

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

ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

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

1. في وحدة تحكّم Google Cloud، انتقِل إلى رمز القائمة > > العلامة التجارية.

   الانتقال إلى "الهوية البصرية للعلامة التجارية"

2. إذا سبق لك ضبط ، يمكنك ضبط إعدادات شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth التالية في العلامة التجارية وشريحة الجمهور والوصول إلى البيانات. إذا ظهرت لك رسالة تفيد بأنّ لم يتم ضبطه بعد، انقر على البدء:
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، انتقِل إلى رمز القائمة > > العملاء.

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

2. انقر على إنشاء عميل.
3. انقر على نوع التطبيق > تطبيق كمبيوتر مكتبي.
4. في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. ولا يظهر هذا الاسم إلا في "وحدة تحكّم Google Cloud".
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 التلقائي واستبدِل محتوياته بالرمز التالي:

   calendar/quickstart/build.gradle

   العرض على GitHub
   apply plugin: 'java'
   apply plugin: 'application'
   
   mainClassName = 'CalendarQuickstart'
   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-calendar:v3-rev20220715-2.0.0'
   }

إعداد العيّنة

1. في الدليل src/main/java/، أنشِئ ملف Java جديدًا يحمل اسمًا يتطابق مع قيمة mainClassName في ملف build.gradle.

2. أدرِج الرمز التالي في ملف Java الجديد:

   calendar/quickstart/src/main/java/CalendarQuickstart.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.DateTime;
   import com.google.api.client.util.store.FileDataStoreFactory;
   import com.google.api.services.calendar.Calendar;
   import com.google.api.services.calendar.CalendarScopes;
   import com.google.api.services.calendar.model.Event;
   import com.google.api.services.calendar.model.Events;
   
   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;
   
   /* class to demonstrate use of Calendar events list API */
   public class CalendarQuickstart {
     /**
      * Application name.
      */
     private static final String APPLICATION_NAME = "Google Calendar 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(CalendarScopes.CALENDAR_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 = CalendarQuickstart.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();
       Credential credential = new AuthorizationCodeInstalledApp(flow, receiver).authorize("user");
       //returns an authorized Credential object.
       return credential;
     }
   
     public static void main(String... args) throws IOException, GeneralSecurityException {
       // Build a new authorized API client service.
       final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
       Calendar service =
           new Calendar.Builder(HTTP_TRANSPORT, JSON_FACTORY, getCredentials(HTTP_TRANSPORT))
               .setApplicationName(APPLICATION_NAME)
               .build();
   
       // List the next 10 events from the primary calendar.
       DateTime now = new DateTime(System.currentTimeMillis());
       Events events = service.events().list("primary")
           .setMaxResults(10)
           .setTimeMin(now)
           .setOrderBy("startTime")
           .setSingleEvents(true)
           .execute();
       List<Event> items = events.getItems();
       if (items.isEmpty()) {
         System.out.println("No upcoming events found.");
       } else {
         System.out.println("Upcoming events");
         for (Event event : items) {
           DateTime start = event.getStart().getDateTime();
           if (start == null) {
             start = event.getStart().getDate();
           }
           System.out.printf("%s (%s)\n", event.getSummary(), start);
         }
       }
     }
   }

تشغيل العيّنة

1. شغِّل العيّنة:

   gradle run
   

2. في المرة الأولى التي تُشغِّل فيها العيّنة، سيُطلب منك تفويض الوصول:
   1. إذا لم تكن مسجِّلاً الدخول إلى حسابك على Google، سجِّل الدخول عندما يُطلب منك ذلك. إذا كنت مسجّلاً الدخول إلى حسابات متعددة، اختَر حسابًا واحدًا لاستخدامه في التفويض.
   2. انقر على قبول.

   يتم تشغيل تطبيق Java ويطلب Google Calendar API.

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

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

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