البدء السريع بلغة Java

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

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

يمكنك إنشاء تطبيق سطر أوامر Java لإرسال طلبات إلى واجهة برمجة التطبيقات Google Apps Script API.

الأهداف

• إعداد البيئة.
• إعداد العيّنة
• نفِّذ النموذج.

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

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

• حساب Google مع تفعيل Google Drive.

إعداد البيئة

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

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

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

• في وحدة تحكُّم Google Cloud، فعِّل واجهة برمجة التطبيقات Google Apps Script API.

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

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

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

1. في Google Cloud Console، انتقِل إلى القائمة menu > واجهات برمجة التطبيقات والخدمات > شاشة موافقة OAuth.

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

2. بالنسبة إلى نوع المستخدم، اختَر داخلي، ثم انقر على إنشاء.
3. أكمِل نموذج تسجيل التطبيق، ثم انقر على حفظ ومتابعة.

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

5. مراجعة ملخّص تسجيل التطبيق لإجراء تغييرات، انقر على تعديل. إذا بدا تسجيل التطبيق على ما يرام، انقر على الرجوع إلى لوحة البيانات.

مصادقة بيانات الاعتماد لتطبيق سطح المكتب

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

1. في وحدة تحكُّم Google Cloud، انتقِل إلى القائمة menu > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.

   الانتقال إلى بيانات الاعتماد

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

   AppsScript/quickstart/build.gradle

   عرض على GitHub

   apply plugin: 'java'
   apply plugin: 'application'
   
   mainClassName = 'AppsScriptQuickstart'
   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-script:v1-rev20220323-2.0.0'
   }
   

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

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

2. ضمِّن الرمز التالي في ملف Java الجديد:

   appsScript/quickstart/src/main/java/AppsScriptQuickstart.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.script.Script;
   import com.google.api.services.script.model.Content;
   import com.google.api.services.script.model.CreateProjectRequest;
   import com.google.api.services.script.model.File;
   import com.google.api.services.script.model.Project;
   import java.io.FileNotFoundException;
   import java.io.IOException;
   import java.io.InputStream;
   import java.io.InputStreamReader;
   import java.security.GeneralSecurityException;
   import java.util.Arrays;
   import java.util.Collections;
   import java.util.List;
   
   public class AppsScriptQuickstart {
     private static final String APPLICATION_NAME = "Apps Script API Java Quickstart";
     private static final JsonFactory JSON_FACTORY = GsonFactory.getDefaultInstance();
     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 credentials folder at /secret.
      */
     private static final List<String> SCOPES =
         Collections.singletonList("https://www.googleapis.com/auth/script.projects");
     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 = AppsScriptQuickstart.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();
       Script service =
           new Script.Builder(HTTP_TRANSPORT, JSON_FACTORY, getCredentials(HTTP_TRANSPORT))
               .setApplicationName(APPLICATION_NAME)
               .build();
       Script.Projects projects = service.projects();
   
       // Creates a new script project.
       Project createOp = projects.create(new CreateProjectRequest().setTitle("My Script")).execute();
   
       // Uploads two files to the project.
       File file1 = new File()
           .setName("hello")
           .setType("SERVER_JS")
           .setSource("function helloWorld() {\n  console.log(\"Hello, world!\");\n}");
       File file2 = new File()
           .setName("appsscript")
           .setType("JSON")
           .setSource("{\"timeZone\":\"America/New_York\",\"exceptionLogging\":\"CLOUD\"}");
       Content content = new Content().setFiles(Arrays.asList(file1, file2));
       Content updatedContent = projects.updateContent(createOp.getScriptId(), content).execute();
   
       // Logs the project URL.
       System.out.printf("https://script.google.com/d/%s/edit\n", updatedContent.getScriptId());
     }
   }

تنفيذ النموذج

1. تنفيذ النموذج:

   gradle run
   

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

   يشغل تطبيق Java واجهة برمجة التطبيقات لبرمجة تطبيقات Google ويطلبها.

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

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

• المستندات المرجعية لواجهة برمجة التطبيقات لبرمجة التطبيقات
• مستندات برنامج Google APIs للغة Java
• مستندات Javadoc في واجهة برمجة التطبيقات الخاصة ببرمجة Google Apps