عرض محتوى المكتبة والألبومات وعناصر الوسائط

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

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

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

نظرة عامة

من الاستخدامات المهمة لواجهة برمجة التطبيقات إدراج عناصر الوسائط التي احتفظ المستخدم بنسخة احتياطية منها في "صور Google". يمكن إدراج العناصر الموجودة في ألبوم معين أو من مكتبة المستخدم بالكامل (طريقة العرض الافتراضية في تطبيق صور Google).

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

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

تنبيه: لا تخزِّن صور المستخدمين وفيديوهاتهم مؤقتًا. بدلاً من ذلك، يمكنك تخزين ملف الوسائط id وطلب تفاصيله مرة أخرى عند الحاجة إليها. قد تتغير الصور، وتنتهي صلاحية الوصول المباشر عبر baseUrl بعد 60 دقيقة. لمزيد من المعلومات، يُرجى الاطّلاع على المقالة الوصول إلى عناصر الوسائط.

ألبومات البيانات

يمكنك استرداد قائمة بألبومات المستخدم باستخدام 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 في المكالمات التالية:

• albums.list
• sharedAlbums.list

راحة

إليك طلب 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، ما يشير إلى أنّ هناك المزيد من النتائج التي يمكن جلبها من الخادم.

ملاحظة: تُعدّ مَعلمة pageSize كحدّ أقصى، لأنّه قد يتم عرض نتائج أقل مما هو مطلوب.

مثال

ويجب إلحاق 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 مستخدَمة سابقًا في الطلب نفسه.

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