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

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

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

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

الأهداف

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

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

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

إعداد البيئة

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

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

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

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

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

وحدة التحكّم في Google Cloud

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

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

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

واجهة سطر الأوامر gcloud

  1. أنشئ حساب الخدمة: 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. اختياري: يمكنك تعيين أدوار لحساب الخدمة لمنح الإذن بالوصول إلى موارد مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الرجوع إلى مقالة منح إمكانية الوصول إلى الموارد وتغييرها وإبطالها.

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

وعليك الحصول على بيانات الاعتماد على شكل مفتاحَي تشفير عام/خاص. هذه بيانات الاعتماد المستخدمة من قِبل الرمز لتفويض إجراءات حساب الخدمة داخل تطبيقك.
  1. في وحدة التحكّم في Google Cloud، انتقِل إلى القائمة . > إدارة الهوية وإمكانية الوصول و المشرف > حسابات الخدمة.

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

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

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

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

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

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

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

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

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

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

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

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

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

    يتم تشغيل تطبيق Java واستدعاء واجهة برمجة تطبيقات Google Keep.

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

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