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

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

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

يمكنك إنشاء تطبيق سطر أوامر Java يُجري طلبات إلى Google Keep API.

الأهداف

• إعداد البيئة
• قم بإعداد العيّنة.
• شغِّل العيّنة.

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

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

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

إعداد البيئة

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

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

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

• في وحدة تحكُّم Google Cloud، فعِّل Google Keep API.

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

إنشاء حساب خدمة

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

وحدة تحكُّم Google Cloud

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

   الانتقال إلى حسابات الخدمة

2. انقر على إنشاء حساب خدمة.
3. املأ تفاصيل حساب الخدمة، ثم انقر على إنشاء ومتابعة.
4. اختياري: عيّن الأدوار لحساب الخدمة لمنح الإذن بالوصول إلى موارد مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة منح الموارد وتغييرها وإبطالها.
5. انقر على متابعة.
6. اختياري: أدخِل المستخدمين أو المجموعات التي يمكنها إدارة الإجراءات وتنفيذها باستخدام حساب الخدمة هذا. للتعرُّف على المزيد من التفاصيل، يُرجى الاطِّلاع على إدارة انتحال هوية حساب الخدمة.
7. انقر على تم. دوِّن عنوان البريد الإلكتروني لحساب الخدمة.

gcloud CLI

1. أنشئ حساب الخدمة:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

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

إنشاء بيانات اعتماد لحساب خدمة

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

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

   الانتقال إلى حسابات الخدمة

2. اختَر حساب الخدمة.
3. انقر على المفاتيح > إضافة مفتاح > إنشاء مفتاح جديد.
4. اختَر JSON، ثم انقر على إنشاء.

   يتم إنشاء زوج المفتاح العام/الخاص وتنزيله على جهازك كملف جديد. احفظ ملف JSON الذي تم تنزيله بتنسيق credentials.json في دليل العمل. وهذا الملف هو النسخة الوحيدة من هذا المفتاح. للحصول على معلومات حول طريقة تخزين المفتاح بأمان، يُرجى الاطّلاع على إدارة مفاتيح حساب الخدمة.

5. انقر على إغلاق.

إعداد التفويض على مستوى النطاق لحساب الخدمة

لطلب البيانات من واجهات برمجة التطبيقات نيابةً عن المستخدمين في مؤسسة على Google Workspace، يجب أن يتم منح حساب الخدمة الخاص بك تفويضًا للسلطة على مستوى النطاق في "وحدة تحكّم مشرف Google Workspace" من خلال حساب مشرف متميّز. لمزيد من المعلومات، يُرجى الاطّلاع على تفويض صلاحية على مستوى النطاق لحساب خدمة.

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

   الانتقال إلى حسابات الخدمة

2. اختَر حساب الخدمة.
3. انقر على إظهار الإعدادات المتقدمة.
4. ضمن "التفويض على مستوى النطاق"، ابحث عن "معرّف العميل" لحساب الخدمة. انقر على نسخ content_copy لنسخ قيمة معرّف العميل إلى الحافظة.

5. إذا كان لديك إذن وصول مشرف متميّز إلى حساب Google Workspace ذي الصلة، انقر على عرض وحدة تحكّم مشرف Google Workspace، ثم سجِّل الدخول باستخدام حساب مستخدم مشرف متميّز وواصِل اتّباع الخطوات التالية.

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

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

   الانتقال إلى عناصر تحكُّم واجهة برمجة التطبيقات

2. انقر على إدارة التفويض على مستوى النطاق.
3. انقر على إضافة جهة اتصال جديدة.
4. في حقل "معرّف العميل"، الصِق معرّف العميل الذي نسخته سابقًا.
5. في الحقل "نطاقات OAuth"، أدخِل قائمة بالنطاقات التي يتطلبها تطبيقك مفصولة بفواصل. هذه هي مجموعة النطاقات نفسها التي تم تحديدها عند ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth.
6. انقر على تفويض.

تجهيز مساحة العمل

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 واستدعاء واجهة برمجة تطبيقات Google Keep.

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

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

• تحديد مشاكل المصادقة والترخيص وحلّها
• المستندات المرجعية لواجهة Google Keep API
• مستندات عميل Google APIs لـ Java
• مستندات JavaScript لواجهة برمجة تطبيقات Google Keep