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

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

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

نظرة عامة

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

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

  • أدرِج ملفات الوسائط من ألبومات محدَّدة تم إنشاؤها من خلال تطبيق، أو من كل التطبيقات التي تم إنشاؤها في التطبيق. مكتبة

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

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

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

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

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

راحة

إليك نموذج طلب:

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 ويتم حذفها من REST. الاستجابة. تجدر الإشارة أيضًا إلى أنّ coverPhotoBaseUrl يشير إلى عنصر نائب تلقائي. .

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

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

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

راحة

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

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

لتحسين الأداء، يمكن استخدام الطرق التي تُرجع عددًا كبيرًا من النتائج (مثل سردها) إلى تقسيم الاستجابة إلى صفحات. الحد الأقصى لعدد النتائج في كل يتم تحديد الصفحة بواسطة المعلمة 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 تم استخدامه سابقًا في طلبك.