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

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

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

نمای کلی

کتابخانه API به شما امکان می دهد موارد رسانه ای را که برنامه شما ایجاد کرده است فهرست کنید و به آنها دسترسی پیدا کنید.

برخی از ویژگی‌های کلیدی فهرست‌بندی آیتم‌های رسانه شامل موارد زیر است:

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

هر آلبوم برگشتی دارای شناسه ای است که می تواند برای بازیابی محتویات آلبوم همانطور که در فهرست محتوای آلبوم نشان داده شده است استفاده شود. همچنین شامل عنوان و تعداد آیتم های رسانه ای است که در آن وجود دارد.

productUrl به آلبومی در Google Photos اشاره می کند که می تواند توسط کاربر باز شود.

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

پاسخ همچنین حاوی nextPageToken است. برای اطلاعات بیشتر، صفحه بندی را ببینید.

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

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

می‌توانید همه موارد رسانه‌ای را از کتابخانه 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"
}

پاسخ شامل فهرستی از آیتم های رسانه ای است که از بیشتر به جدیدترین آنها مرتب شده است. برای اطلاعات بیشتر، به 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"
}

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

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

صفحه بندی برای REST

برای بهبود عملکرد، روش‌هایی که تعداد زیادی نتیجه را برمی‌گردانند (مانند روش‌های فهرست) ممکن است پاسخ را صفحه‌بندی کنند. حداکثر تعداد نتایج در هر صفحه با پارامتر pageSize داده می شود.

برای تماس با mediaItems.search و mediaItems.list ، اندازه صفحه پیش‌فرض 25 مورد است. ما این اندازه صفحه را توصیه می کنیم زیرا تعادلی بین اندازه پاسخ و نرخ پر شدن ایجاد می کند. حداکثر اندازه صفحه برای جستجوی آیتم های رسانه ای و درخواست های فهرست 100 مورد است.

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

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

مثال

همانطور که در مثال زیر نشان داده شده است، باید 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 قبلاً استفاده شده نباید در همان درخواست استفاده شود.