بدء استخدام مكتبة عملاء Java

لبدء استخدام واجهة برمجة التطبيقات لمكتبة "صور Google" مع مكتبة برامج Java، عليك إعداد مكتبة البرامج في بيئة التطوير. قبل إجراء ذلك، يجب ضبط مشروعك من خلال تفعيل واجهة برمجة التطبيقات عبر وحدة التحكم في واجهة Google API وإعداد معرِّف عميل OAuth 2.0.

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

يتيح معرِّف عميل OAuth 2.0 لمستخدمي تطبيقك تسجيل الدخول والمصادقة، وبالتالي استخدام Library API. لا تتيح واجهة برمجة التطبيقات Library API استخدام حسابات الخدمة، ولاستخدام واجهة برمجة التطبيقات هذه، على المستخدمين تسجيل الدخول إلى حساب Google صالح.

ضبط إعدادات تطبيقك

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

يجب تفعيل واجهة برمجة التطبيقات Library API في مشروعك قبل أن تتمكّن من استخدامها.

1. انتقِل إلى وحدة التحكم في واجهة Google API.
2. من شريط القوائم، اختَر مشروعًا أو أنشِئ مشروعًا جديدًا.
3. لفتح مكتبة Google API، اختَر واجهات برمجة التطبيقات والخدمات > المكتبة من قائمة التنقّل.
4. ابحث عن "Google Photos Library API". اختَر النتيجة الصحيحة وانقر على تفعيل.

طلب معرِّف عميل OAuth 2.0

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

1. انتقِل إلى وحدة التحكم في واجهة Google API واختَر مشروعك.
2. من القائمة، اختر APIs & Services (واجهات برمجة التطبيقات والخدمات) > Credentials (بيانات الاعتماد).
3. في صفحة بيانات الاعتماد، انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
4. اختَر نوع التطبيق. في هذا المثال، نوع التطبيق هو تطبيق الويب.

5. سجّل المصادر التي تم السماح لتطبيقك من خلالها بالوصول إلى Google APIs على النحو التالي:

   1. لتحديد معرِّف العميل، أدخِل اسمًا.

   2. في الحقل مصادر JavaScript المسموح بها، أدخِل أصل تطبيقك. لا يسمح هذا الحقل بأحرف البدل.

      يمكنك إدخال مصادر متعددة للسماح بتشغيل تطبيقك على بروتوكولات أو نطاقات أو نطاقات فرعية مختلفة. يُسمح لعناوين URL التي تُدخلها ببدء طلب OAuth.

      يعرض المثال التالي عنوان URL للتطوير المحلي (تستخدم نماذجنا localhost:8080) وعنوان URL للإنتاج.

      http://localhost:8080
      https://myproductionurl.example.com
      

   3. حقل معرّف الموارد المنتظم (URI) لإعادة التوجيه المعتمد هو نقطة النهاية التي تتلقى الردود من خادم OAuth 2.0. عادةً ما يتضمن ذلك بيئة التطوير الخاصة بك ويشير إلى مسار في تطبيقك.

      http://localhost:8080/auth/google/callback
      https://myproductionurl.example.com/auth/google/callback
      

   4. انقر على إنشاء.

6. من مربع حوار عميل OAuth الناتج، نزِّل ملف JSON الذي يحتوي على إعدادات العميل. تتألف تفاصيل العميل مما يلي:

   • معرِّف العميل
   • سر العميل

   وسيتم استخدام ملف JSON هذا لاحقًا لإعداد مكتبة مصادقة Google للغة Java التي تتوافق مع مكتبة البرامج هذه.

قبل أن تتمكّن من إطلاق تطبيق عام يمكنه الوصول إلى واجهة برمجة تطبيقات Library (واجهة برمجة تطبيقات المكتبة)، يجب أن تُراجع Google تطبيقك. تظهر الرسالة "لم يتم التحقق من التطبيق" على الشاشة عند اختبار التطبيق، حتى يتم التحقق منه.

إعداد مكتبة العملاء

تتعامل مكتبة برامج Java مع جميع طلبات البيانات من واجهة برمجة التطبيقات الخلفية بالنيابة عنك، وتعرض الكائنات سهلة الاستخدام التي يمكن استخدامها، بما في ذلك عيّنات التعليمات البرمجية لبعض المهام الشائعة الخاصة بواجهة برمجة التطبيقات. أولاً، عليك تنزيل وتثبيت مكتبة برامج واجهة برمجة التطبيقات لمكتبة "صور Google" للغة Java إلى جانب التبعيات من GitHub. بعد ذلك، يمكنك إعداد بيانات اعتماد OAuth2 للغة Java.

خيارات التنزيل

في ما يلي بعض الخيارات لتنزيل مكتبة العملاء:

• تبعية Gradle:

  لاستخدام هذه المكتبة مع Gradle، أضِف الاعتمادية التالية إلى ملف build.gradle.

  repositories {
    mavenCentral()
  }
  dependencies {
    compile 'com.google.photos.library:google-photos-library-client:1.7.3'
  }
  

• اعتمادية Maven:

  لاستخدام هذه المكتبة مع Maven، أضِف ما يلي إلى ملف pom.xml في Maven.

  <dependency>
    <groupId>com.google.photos.library</groupId>
    <artifactId>google-photos-library-client</artifactId>
    <version>1.7.3</version>
  </dependency>
  

• تنزيل إصدار:

  تحتوي صفحة الإصدارات على عناصر مختلفة لكل إصدار مكتبة، بما في ذلك ملفات الأوعية.

• استنساخ المستودع:

  استخدِم هذه الطريقة إذا كنت تريد تغيير هذه المكتبة أو المساهمة فيها، مثل إرسال طلبات السحب، أو تجربة نماذجنا. عند نسخ المستودع، سيتم تنزيل جميع الملفات في هذا المستودع.

  1. شغِّل git clone https://github.com/google/java-photoslibrary.git عند ظهور الطلب بالأمر.
  2. سيظهر لك دليل "java-photoslibrary". يمكنك الانتقال إليها عن طريق تشغيل cd java-photoslibrary.
  3. افتح ملف build.gradle في بيئة تطوير البرامج (IDE) أو شغِّل ./gradlew assemble في موجه الأوامر لإنشاء المشروع. يمكنك الاطّلاع على ./gradlew tasks للاطّلاع على المهام المتاحة.

إعداد بيانات اعتماد OAuth2 للغة Java

تعمل مكتبة البرامج هذه مع مكتبة مصادقة Google للغة Java. للاطلاع على مزيد من المعلومات، يُرجى الرجوع إلى استخدام OAuth 2.0 مع مكتبة برامج Google API للغة Java.

حدِّد إعدادات OAuth للبرنامج في CredentialsProvider عند إنشاء PhotoLibrarySettings لكائن PhotosLibraryClient.

تجربة بعض النماذج

جرِّب الرمز أدناه لإجراء أول طلب بيانات من واجهة برمجة التطبيقات باستخدام مكتبة برامج Java.

// Set up the Photos Library Client that interacts with the API
PhotosLibrarySettings settings =
     PhotosLibrarySettings.newBuilder()
    .setCredentialsProvider(
        FixedCredentialsProvider.create(/* Add credentials here. */)) 
    .build();

try (PhotosLibraryClient photosLibraryClient =
    PhotosLibraryClient.initialize(settings)) {

    // Create a new Album  with at title
    Album createdAlbum = photosLibraryClient.createAlbum("My Album");

    // Get some properties from the album, such as its ID and product URL
    String id = album.getId();
    String url = album.getProductUrl();

} catch (ApiException e) {
    // Error during album creation
}

هناك المزيد من النماذج على GitHub يمكنك تجربتها.