فهرست کردن محتوای کتابخانه، آلبوم‌ها، و فایل‌های رسانه‌ای

گستره‌های مجوز لازم

‫Google Photos Library API شامل چندین دامنه است که برای دسترسی به فایل‌های رسانه‌ای و آلبوم‌ها استفاده می‌شود. فایل‌های رسانه‌ای که از تماس‌های مختلف برگردانده می‌شوند براساس اینکه توسعه‌دهنده کدام دامنه‌ها را درخواست کرده است متفاوت هستند.

photoslibrary.readonly scope allows access to all media items in the user's library. گستره photoslibrary.readonly.appcreateddata فقط به فایل‌های رسانه‌ای که توسط برنامه ایجاد شده‌اند اجازه دسترسی می‌دهد. برای اطلاعات بیشتر، گستره‌های مجوز را ببینید.

نمای کلی

یکی از کاربردهای مهم میانای برنامه‌سازی کاربردی، فهرست کردن فایل‌های رسانه‌ای است که کاربر در Google Photos پشتیبان‌گیری کرده است. موارد موجود در آلبومی خاص یا از کل کتابخانه کاربر (نمای پیش‌فرض در برنامه Google Photos) را می‌توان فهرست کرد.

می‌توانید از فیلترها برای انتخاب عکس‌هایی استفاده کنید که با تاریخ، دسته محتوا، یا نوع رسانه مشخصی مطابقت دارند، وقتی که موارد را از کتابخانه کاربر فهرست می‌کنید. وقتی موارد را از آلبوم‌ها فهرست می‌کنید، این ویژگی پشتیبانی نمی‌شود.

فهرست کردن محتوای کتابخانه و آلبوم، فهرستی از فایل‌های رسانه‌ای را برمی‌گرداند. غنی‌سازی‌هایی که بخشی از آلبوم هستند گنجانده نمی‌شوند. مورد رسانه‌ای عکس، ویدیو، یا رسانه دیگری را توصیف می‌کند. ‫A mediaItem شامل پیوند مستقیم به مورد، پیوند به مورد در Google Photos، و فراداده‌های مرتبط دیگر است. برای اطلاعات بیشتر، دسترسی به فایل‌های رسانه‌ای و 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"
}

جاوا

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 Photos اشاره می‌کند که کاربر می‌تواند آن را باز کند.

coverPhotoMediaItemId حاوی شناسه فایل رسانه‌ای است که عکس روی جلد این آلبوم را نشان می‌دهد. برای دسترسی به این تصویر جلد، از coverPhotoBaseUrl استفاده کنید. نباید از coverPhotoBaseUrl مستقیماً بدون مشخص کردن پارامترهای اضافی استفاده کنید.

آلبوم‌هایی که در حساب کاربر ایجاد شده‌اند یا به حساب کاربر اضافه شده‌اند و برنامه‌تان آن‌ها را هم‌رسانی کرده است، شامل ویژگی shareInfo اضافی هستند. برای جزئیات بیشتر، به هم‌رسانی رسانه مراجعه کنید.

آلبوم‌ها ممکن است پرچم isWriteable هم داشته باشند که نشان می‌دهد می‌توانید در آلبوم فایل رسانه‌ای ایجاد کنید یا نه. اگر این پرچم برگردانده نشود، به‌طور پیش‌فرض روی false تنظیم می‌شود. این موضوع به دسترسی اعطاشده به برنامه شما بستگی دارد، ازجمله موارد زیر:

  • چه کسی آلبوم را ایجاد کرده است.
  • هم‌رسانی شده است یا نه.
  • کاربر چه گستره‌هایی را تأیید کرده است.

اگر هرکدام از این معیارها تغییر کند، ممکن است این پرچم تغییر کند. برای جزئیات بیشتر، ایجاد آلبوم را ببینید. پاسخ همچنین حاوی nextPageToken است. برای اطلاعات بیشتر، به صفحه‌بندی مراجعه کنید.

پاسخ برای آلبوم‌های خالی متفاوت است، mediaItemsCount و coverPhotoMediaItemId به‌طور پیش‌فرض روی ۰ تنظیم شده‌اند و از پاسخ REST حذف شده‌اند. همچنین توجه داشته باشید که coverPhotoBaseUrl به تصویر جای‌بان پیش‌فرض اشاره می‌کند.

فهرست کردن محتوای کتابخانه

می‌توانید همه موارد رسانه‌ای را از کتابخانه Google Photos کاربر فهرست کنید. موارد بایگانی‌شده و حذف‌شده را شامل نمی‌شود. می‌توانید با اعمال فیلتر، فایل‌های رسانه‌ای را براساس محتوا، تاریخ، و ویژگی‌های دیگر فهرست کنید. اگر کاربر موردی را که در برگه هم‌رسانی Google Photos او دردسترس است به کتابخانه‌اش اضافه نکرده باشد، آن مورد در این فهرست گنجانده نمی‌شود.

برای بازیابی فایل رسانه‌ای، 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"
}

جاوا

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

جاوا

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 Photos ویرایش کند.

اگر albumId تنظیم شده باشد، نمی‌توانید هنگام فهرست کردن محتوای آلبوم فیلتر اعمال کنید. انجام این کار منجر به خطای Bad Request می‌شود.

درحال فهرست کردن آلبوم‌های مشترک

می‌توانید فهرستی از همه آلبوم‌هایی را که کاربر هم‌رسانی کرده است یا با کاربر هم‌رسانی شده است بازیابی کنید. این ویژگی شبیه به برگه «هم‌رسانی» در برنامه Google Photos است.

آلبوم‌های هم‌رسانی‌شده‌ای که کاربر به کتابخانه Google Photos خود اضافه کرده است نیز در فراخوانی فهرست کردن آلبوم‌ها برگردانده می‌شوند. برای فهرست کردن آلبوم‌های مشترک ازطریق Library API، فراخوانی زیر را انجام دهید:

استراحت

در اینجا یک درخواست نمونه آورده شده است:

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

درخواست نتیجه زیر را برمی‌گرداند:

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

جاوا

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 Photos کاربر که فقط توسط برنامه شما ایجاد شده‌اند، آورده شده است:

GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

در اینجا یک درخواست GET برای فهرست کردن همه آلبوم‌های مشترک از کتابخانه Google Photos کاربر که فقط توسط برنامه شما ایجاد شده‌اند، آورده شده است:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

جاوا

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، اندازه پیش‌فرض صفحه ۲۵ مورد است. این اندازه صفحه را توصیه می‌کنیم چون بین اندازه پاسخ و نرخ تکمیل تعادل برقرار می‌کند. حداکثر اندازه صفحه برای درخواست‌های جستجو و فهرست کردن فایل رسانه‌ای ۱۰۰ مورد است.

اندازه پیش‌فرض و توصیه‌شده صفحه هنگام فهرست کردن آلبوم‌ها ۲۰ آلبوم است، با حداکثر ۵۰ آلبوم.

وقتی تعداد نتایج دردسترس بیشتر از اندازه صفحه باشد، پاسخ شامل nextPageToken است که به برنامه شما نشان می‌دهد نتایج بیشتری برای واکشی از سرور وجود دارد.

مثال

باید nextPageToken را به درخواست‌های بعدی در پارامتر pageToken اضافه کنید، همان‌طور که در مثال زیر نشان داده شده است. pageToken را همراه با پارامترهای دیگر موردنیاز برای عملیات، در بدنه درخواست یا به‌عنوان پارامتر پُرسمان مشخص کنید.

درخواست شماره ۱

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

پاسخ ۱

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

درخواست شماره ۲

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

پاسخ شماره ۲

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

این الگو را ادامه دهید تا دیگر شیء nextPageToken وجود نداشته باشد.

nextPageToken فقط برای همان درخواست معتبر است. اگر پارامتری تغییر کند، نباید از nextPageToken که قبلاً استفاده شده است در همان درخواست استفاده شود.