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

محدوده مجوز مورد نیاز

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

محدوده photoslibrary.readonly امکان دسترسی به تمام موارد رسانه ای در کتابخانه کاربر را فراهم می کند. محدوده photoslibrary.readonly.appcreateddata فقط به موارد رسانه ای که توسط برنامه ایجاد شده اند دسترسی داشته باشید. برای اطلاعات بیشتر، به محدوده مجوز مراجعه کنید.

بررسی اجمالی

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

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

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

جاوا

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 به طور پیش فرض روی 0 تنظیم شده اند و از پاسخ 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 خود اضافه کرده است نیز در تماس آلبوم‌های فهرست شده برگردانده می‌شوند. برای فهرست کردن آلبوم‌های مشترک از طریق کتابخانه 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 تنظیم شده است در تماس‌های زیر فهرست کنید:

• albums.list
• sharedAlbums.list

باقی مانده

در اینجا یک درخواست 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 ، اندازه صفحه پیش‌فرض 25 مورد است. ما این اندازه صفحه را توصیه می کنیم زیرا تعادلی بین اندازه پاسخ و نرخ پر شدن ایجاد می کند. حداکثر اندازه صفحه برای جستجوی آیتم های رسانه ای و درخواست های فهرست 100 مورد است.

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

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

توجه: پارامتر pageSize حداکثر است - ممکن است نتایج کمتری نسبت به درخواستی بازگردانده شود.

مثال

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

درخواست شماره 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 وجود داشته باشد، می توانید پس از درخواست اولیه خود، درخواستی برای نتایج بیشتر ارسال کنید.