بدء استخدام Java

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

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

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

الأهداف

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

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

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

إعداد البيئة

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

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

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

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

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

Google Cloud Console

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

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

  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، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.

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

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

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

  5. انقر على إغلاق (Close).

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

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

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

  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.

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

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