نطاقات التفويض المطلوبة
تحتوي واجهة برمجة التطبيقات لمكتبة "صور Google" على نطاقات متعددة تُستخدم للوصول إلى ملفات الوسائط والألبومات. تختلف عناصر الوسائط التي يتم عرضها من الاتصالات المختلفة بناءً على النطاقات التي طلبها المطوّر.
يسمح نطاق photoslibrary.readonly
بالوصول إلى جميع عناصر الوسائط في مكتبة المستخدم. يتيح نطاق photoslibrary.readonly.appcreateddata
الوصول فقط إلى عناصر الوسائط التي أنشأها التطبيق. لمزيد من المعلومات، يمكنك الاطّلاع على نطاقات التفويض.
نظرة عامة
من الاستخدامات المهمة لواجهة برمجة التطبيقات إدراج عناصر الوسائط التي احتفظ المستخدم بنسخة احتياطية منها في "صور Google". يمكن إدراج العناصر الموجودة في ألبوم معين أو من مكتبة المستخدم بالكامل (طريقة العرض الافتراضية في تطبيق صور Google).
يمكنك استخدام الفلاتر لاختيار الصور التي تتطابق مع تاريخ معيّن أو فئة محتوى أو نوع وسائط محدّد عند إدراج عناصر من مكتبة المستخدم. لا تتوفر هذه الميزة عند إدراج عناصر من الألبومات.
يؤدي إدراج محتوى المكتبة والألبوم إلى إرجاع قائمة بعناصر الوسائط.
ولا يتم تضمين التحسينات التي تشكّل جزءًا من الألبوم. تصف عناصر الوسائط صورة أو فيديو أو وسائط أخرى. تتضمن السمة 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" }
Java
try { // Make a request to list all albums in the user's library // Iterate over all the albums in this list // Pagination is handled automatically ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(); for (Album album : response.iterateAll()) { // Get some properties of an album String id = album.getId(); String title = album.getTitle(); String productUrl = album.getProductUrl(); String coverPhotoBaseUrl = album.getCoverPhotoBaseUrl(); // The cover photo media item id field may be empty String coverPhotoMediaItemId = album.getCoverPhotoMediaItemId(); boolean isWritable = album.getIsWriteable(); long mediaItemsCount = album.getMediaItemsCount(); } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all albums in the user's library // Iterate over all the albums in this list // Pagination is handled automatically $response = $photosLibraryClient->listAlbums(); foreach ($response->iterateAllElements() as $album) { // Get some properties of an album $albumId = $album->getId(); $title = $album->getTitle(); $productUrl = $album->getProductUrl(); $coverPhotoBaseUrl = $album->getCoverPhotoBaseUrl(); // The cover photo media item id field may be empty $coverPhotoMediaItemId = $album->getCoverPhotoMediaItemId(); $isWriteable = $album->getIsWriteable(); $totalMediaItems = $album->getTotalMediaItems(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
لكل ألبوم يتم عرضه معرّف يمكن استخدامه لاسترداد محتوياته كما هو موضح في إدراج محتوى الألبوم. كما تتضمن العنوان وعدد عناصر الوسائط التي تحتوي عليها.
وتشير السمة productUrl
إلى الألبوم في "صور Google" الذي يمكن للمستخدم فتحه.
تحتوي coverPhotoMediaItemId
على معرّف عنصر الوسائط الذي
يمثل صورة غلاف هذا الألبوم. للوصول إلى صورة الغلاف هذه، يمكنك استخدام
coverPhotoBaseUrl
. يجب عدم استخدام coverPhotoBaseUrl
مباشرةً بدون
تحديد معلَمات
إضافية.
تتضمّن الألبومات التي أُنشئت في حساب المستخدم أو تمت إضافتها إلى
حساب المستخدم والتي تمت مشاركتها في تطبيقك خاصية إضافية على shareInfo
.
لمزيد من التفاصيل، يُرجى الاطّلاع على مشاركة الوسائط.
قد تحتوي الألبومات أيضًا على علامة isWriteable
للإشارة إلى ما إذا كان بإمكانك إنشاء عناصر وسائط في الألبوم. يتم ضبط هذه العلامة تلقائيًا على false
في حال عدم عرضها. يعتمد ذلك على الوصول الممنوح إلى التطبيق، بما في ذلك ما يلي:
- من أنشأ الألبوم؟
- ما إذا تمت مشاركته أم لا
- النطاقات التي وافق عليها المستخدم
وقد تتغير هذه العلامة في حال تغيير أي من هذه المعايير. لمزيد من التفاصيل، يُرجى الاطّلاع على
إنشاء ألبومات. يحتوي الرد أيضًا على nextPageToken
. لمزيد من المعلومات، راجِع تقسيم النتائج على عدّة صفحات.
تختلف استجابة الألبومات الفارغة من حيث أنّه يتم ضبط mediaItemsCount
وcoverPhotoMediaItemId
على 0 تلقائيًا ويتم حذفهما من استجابة REST. يُرجى العلم أيضًا أنّ السمة coverPhotoBaseUrl
تشير إلى صورة عنصر نائب تلقائي.
محتوى مكتبة البيانات
يمكنك إدراج كل ملفات الوسائط من مكتبة "صور Google" الخاصة بالمستخدم. ويستثني هذا العمود العناصر المؤرشفة والمحذوفة. يمكنك إدراج عناصر الوسائط استنادًا إلى المحتوى والتاريخ والخصائص الأخرى من خلال تطبيق الفلاتر. إذا لم يضيف المستخدم عنصرًا إلى علامة التبويب المشاركة في "صور 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" }
Java
try { // Make a request to list all media items in the user's library // Iterate over all the retrieved media items // Pagination is handled automatically ListMediaItemsPagedResponse response = photosLibraryClient.listMediaItems(); for (MediaItem item : response.iterateAll()) { // Get some properties of a media item String id = item.getId(); String description = item.getDescription(); String mimeType = item.getMimeType(); String productUrl = item.getProductUrl(); String filename = item.getFilename(); } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all media items in the user's library // Iterate over all the retrieved media items // Pagination is handled automatically $response = $photosLibraryClient->listMediaItems(); foreach ($response->iterateAllElements() as $item) { // Get some properties of a media item /* @var $item \Google\Photos\Library\V1\MediaItem */ $id = $item->getId(); $description = $item->getDescription(); $mimeType = $item->getMimeType(); $productUrl = $item->getProductUrl(); $filename = $item->getFilename(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
يتضمّن الردّ قائمة بعناصر الوسائط، مرتّبة من الأحدث إلى الأقل.
لمزيد من المعلومات، يُرجى الاطّلاع على
mediaItems
. وتحتوي أيضًا
على nextPageToken
، والتي يتم توضيحها بمزيد من التفصيل في
تقسيم النتائج على عدّة صفحات.
إدراج محتوى الألبوم
لإدراج كل عناصر الوسائط في ألبوم، أضِف الحقل albumId
إلى طلب البحث. لمزيد من المعلومات حول albumId
، يمكنك الاطّلاع على إدراج
الألبومات وإدراج الألبومات المشتركة. إذا كانت قيمة albumId
غير صالحة، يتم عرض الخطأ Bad Request
. إذا كان المعرّف صالحًا، ولكن الألبوم غير موجود للمستخدم الذي تمت المصادقة عليه، يتم عرض خطأ Not Found
. لمزيد من التفاصيل بخصوص معالجة الأخطاء، يُرجى الاطّلاع على نصائح الأداء وأفضل الممارسات.
راحة
في ما يلي نموذج طلب:
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" }
Java
try { // Make a request to list all media items in an album // Provide the ID of the album as a parameter in the searchMediaItems call // Iterate over all the retrieved media items SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(albumId); for (MediaItem item : response.iterateAll()) { // ... } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all media items in an album // Provide the ID of the album as a parameter in the searchMediaItems call // Iterate over all the retrieved media items $response = $photosLibraryClient->searchMediaItems(['albumId' => $albumId]); foreach ($response->iterateAllElements() as $item) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
يحتوي الردّ على nextPageToken
وقائمة بعناصر الوسائط. وبخلاف ذلك عند إدراج محتويات المكتبة، يتم إرجاع عناصر الوسائط حسب ترتيبها في الألبوم. لمزيد من التفاصيل، راجِع
mediaItems
وتقسيم النتائج على عدّة صفحات. يمكن للمستخدم تعديل الترتيب في
واجهة "صور Google".
في حال ضبط السياسة albumId
، لن تتمكّن من تطبيق فلتر عند إدراج محتوى الألبوم.
يؤدي ذلك إلى ظهور خطأ Bad Request
.
عرض الألبومات المشتركة
يمكنك استرداد قائمة بجميع الألبومات التي شاركها المستخدم أو التي تمت مشاركتها معه. هذا مشابه لعلامة تبويب "المشاركة" في تطبيق صور Google.
يتم أيضًا عرض الألبومات المشتركة التي أضافها المستخدم إلى مكتبة "صور Google" في طلب إدراج الألبومات. عليك إجراء الطلب التالي لعرض الألبومات المشتركة من خلال Library API:
راحة
في ما يلي نموذج طلب:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums
يعرض الطلب النتيجة التالية:
{ "sharedAlbums": [...] "nextPageToken": "token-for-pagination" }
Java
try { // Make a request to list all albums that have been shared by the user // Iterate over all the albums in this list // Pagination is handled automatically ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums(); for (Album album : response.iterateAll()) { // .. } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all albums that have been shared by the user // Iterate over all the albums in this list // Pagination is handled automatically $response = $photosLibraryClient->listSharedAlbums(); foreach ($response->iterateAllElements() as $album) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
يتم تضمين قائمة بالألبومات في sharedAlbums
. لمزيد من المعلومات، يمكنك الاطّلاع على
إدراج الألبومات. يتضمّن الردّ أيضًا nextPageToken
.
لمزيد من المعلومات، يُرجى الاطّلاع على تقسيم النتائج على عدّة صفحات.
تشتمل الألبومات التي أنشأها تطبيقك وشاركها على موقع shareInfo
إضافي. لمزيد من التفاصيل، يمكنك الاطّلاع على مشاركة الوسائط.
الاطّلاع على الألبومات التي تم إنشاؤها باستخدام تطبيق
يمكنك إدراج الألبومات التي أنشأها تطبيقك باستخدام
excludeNonAppCreatedData
التي تم ضبطها على true
في المكالمات التالية:
راحة
إليك طلب GET يُدرج جميع الألبومات من مكتبة صور Google الخاصة بالمستخدم والتي تم إنشاؤها بواسطة تطبيقك فقط:
GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
إليك طلب GET يُدرج جميع الألبومات المشتركة من مكتبة "صور Google" الخاصة بالمستخدم والتي تم إنشاؤها بواسطة تطبيقك فقط:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
Java
try { // Make a request to list all albums that have been created by your app boolean excludeNonAppCreatedData = true; // Iterate over all the albums in this list // Pagination is handled automatically ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(excludeNonAppCreatedData); for (Album album : response.iterateAll()) { // .. } } catch (ApiException e) { // Handle error } try { // Make a request to list all shared albums that have been created by your app boolean excludeNonAppCreatedData = true; // Iterate over all the albums in this list // Pagination is handled automatically ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums(excludeNonAppCreatedData); for (Album album : response.iterateAll()) { // .. } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all albums that have been created by your app $response = $photosLibraryClient->listAlbums(['excludeNonAppCreatedData' => true]); // Iterate over all the albums in this list // Pagination is handled automatically foreach ($response->iterateAllElements() as $album) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error } try { // Make a request to list all shared albums that have been created by your app $response = $photosLibraryClient->listSharedAlbums(['excludeNonAppCreatedData' => true]); // Iterate over all the albums in this list // Pagination is handled automatically foreach ($response->iterateAllElements() as $album) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
تقسيم النتائج على عدّة صفحات في 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" }
الرد الثاني
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
واصِل تنفيذ هذا النمط حتى تختفي عناصر nextPageToken
الأخرى.
لا يصلح nextPageToken
إلا للطلب نفسه. في حال تغيير أي مَعلمات، يجب عدم استخدام سمة nextPageToken
مستخدَمة سابقًا في الطلب نفسه.