إدراج ملفات الوسائط والألبومات التي أنشأها التطبيق

نطاقات التفويض المطلوبة

يتطلب عرض المحتوى الذي تم إنشاؤه من خلال التطبيق نطاق photoslibrary.readonly.appcreateddata. لمزيد من المعلومات عن النطاقات، يُرجى الاطّلاع على نطاقات التفويض.

نظرة عامة

تتيح لك واجهة برمجة التطبيقات Library API إدراج عناصر الوسائط التي أنشأها تطبيقك والوصول إليها.

تشمل بعض الميزات الرئيسية لعرض عناصر الوسائط ما يلي:

  • سرد عناصر الوسائط من ألبومات محددة تم إنشاؤها من خلال التطبيق أو من المكتبة التي تم إنشاؤها في التطبيق بالكامل

  • تطبيق الفلاتر (التاريخ وفئة المحتوى ونوع الوسائط) عند إدراج المحتوى لتضييق نطاق النتائج

  • استرداد عناصر mediaItem مع التفاصيل الأساسية، مثل الروابط المباشرة والبيانات الوصفية

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

إدراج الألبومات التي أنشأها التطبيق

يمكنك إدراج الألبومات التي أنشأها تطبيقك باستخدام albums.list.

REST

في ما يلي نموذج طلب:

GET https://photoslibrary.googleapis.com/v1/albums

يعرض الطلب النتيجة التالية:

{
  "albums": [
    {
      "id": "album-id",
      "title": "album-title",
      "productUrl": "album-product-url",
      "coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly",
      "coverPhotoMediaItemId": "album-cover-media-item-id",
      "isWriteable": "whether-you-can-write-to-this-album",
      "mediaItemsCount": "number-of-media-items-in-album"
    },
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

يحتوي كل ألبوم معروض على معرّف يمكن استخدامه لاسترداد محتويات الألبوم كما هو موضّح في عرض محتويات الألبوم. ويشمل أيضًا العنوان وعدد عناصر الوسائط التي يحتوي عليها.

يشير الرمز productUrl إلى الألبوم في "صور Google" الذي يمكن للمستخدم فتحه.

يحتوي العنصر coverPhotoMediaItemId على معرّف ملف الوسائط الذي يمثّل صورة غلاف هذا الألبوم. للوصول إلى صورة الغلاف هذه، استخدِم coverPhotoBaseUrl. يجب عدم استخدام coverPhotoBaseUrl مباشرةً بدون تحديد مَعلمات إضافية.

يحتوي الردّ أيضًا على nextPageToken. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الفهرسة.

يختلف ردّ الألبومات الفارغة عن غيرها، إذ يتم ضبط mediaItemsCount و coverPhotoMediaItemId على 0 تلقائيًا ويتم حذفهما من ردّ mediaItemsCount. يُرجى العِلم أيضًا أنّ السمة coverPhotoBaseUrl تشير إلى صورة عنصر نائب تلقائي.

سرد محتوى المكتبة الذي تم إنشاؤه من خلال التطبيق

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

لعرض عناصر وسائط، اتصل بالرقم mediaItems.list.

REST

في ما يلي نموذج طلب:

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

يعرض طلب GET الردّ التالي:

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

يحتوي الردّ على قائمة بعناصر الوسائط، مرتبة من الأكثر إلى الأقلّ حداثة. لمزيد من المعلومات، يُرجى الاطّلاع على mediaItems. وتشتمل أيضًا على nextPageToken، تم وصفه بمزيد من التفصيل في التقسيم على صفحات.

إدراج محتوى الألبوم

لإدراج جميع عناصر الوسائط في ألبوم، أضِف الحقل albumId إلى طلب البحث. لمزيد من المعلومات حول albumId، راجع إدراج الألبومات. إذا كانت قيمة albumId غير صالحة، يتم عرض خطأ Bad Request. إذا كان رقم التعريف صالحًا، ولكن الألبوم غير متوفّر للمستخدم الذي تم مصادقة هويته، يتم عرض خطأ Not Found. لمزيد من التفاصيل حول معالجة الأخطاء، يمكنك الاطّلاع على نصائح الأداء وأفضل الممارسات.

REST

في ما يلي نموذج طلب:

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "albumId": "album-id"
}

يعرض طلب POST الاستجابة التالية:

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

يحتوي الردّ على nextPageToken وقائمة بعناصر الوسائط. على عكس ما يحدث عند إدراج محتوى المكتبة، يتم عرض عناصر الوسائط حسب ترتيبها في الألبوم. لمزيد من التفاصيل، يمكنك الاطّلاع على mediaItems والتقسيم على صفحات. يمكن للمستخدم تعديل الطلب في واجهة "صور Google".

في حال ضبط القيمة albumId، لا يمكنك تطبيق فلتر عند إدراج محتويات الألبوم. يؤدي إجراء ذلك إلى ظهور خطأ Bad Request.

تقسيم البيانات على صفحات في واجهة برمجة التطبيقات REST

لتحسين الأداء، قد تؤدي الطرق التي تعرض عددًا كبيرًا من النتائج (مثل methods list) إلى تقسيم الردّ إلى صفحات. يتم تحديد الحد الأقصى لعدد النتائج في كل صفحة من خلال المَعلمة pageSize.

بالنسبة إلى المكالمات إلى mediaItems.search وmediaItems.list، يكون حجم الصفحة التلقائي هو 25 عنصرًا. وننصحك بهذا الحجم لأنّه يحقق التوازن بين حجم الاستجابة ومعدّل الملء. الحد الأقصى لحجم الصفحة لطلبات البحث عن ملف وسائط وطلبات عرضها هو 100 ملف.

حجم الصفحة التلقائي والمُقترَح عند عرض الألبومات هو 20 ألبومًا، ويمكن عرض 50 ألبومًا كحد أقصى.

عندما يكون عدد النتائج المتاحة أكبر من حجم الصفحة، يحتوي الردّ على nextPageToken، ما يشير إلى تطبيقك بأنّ هناك مزيدًا من النتائج التي يجب جلبها من الخادم.

مثال

يجب إلحاق nextPageToken بالطلبات اللاحقة في المَعلمة pageToken، كما هو موضّح في المثال التالي. حدِّد pageToken مع المَعلمات الأخرى المطلوبة للعملية، إما في نص الطلب أو كمَعلمة طلب بحث.

الطلب رقم 1

{
  "pageSize": "5",
  "filters": { … }
}

الردّ 1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

الطلب رقم 2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

الردّ 2

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

تابِع هذا النمط إلى أن تنتهي عناصر nextPageToken الأخرى.

ويكون nextPageToken صالحًا للطلب نفسه فقط. في حال تم تغيير أي مَعلمات، يجب عدم استخدام nextPageToken المستخدَم سابقًا في الطلب نفسه.