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

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

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

يسمح نطاق 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" أيضًا في استدعاء ألبومات البيانات. إعداد المكالمة التالية لإدراج الألبومات المشتركة من خلال واجهة برمجة تطبيقات المكتبة:

راحة

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

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"
}

الرد رقم 2

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

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

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

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