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

حوزه‌های مجوز لازم

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

نمای کلی

«میانای برنامه‌سازی کاربردی کتابخانه» به شما امکان می‌دهد موارد رسانه‌ای را که برنامه‌تان ایجاد کرده است فهرست کنید و به آن‌ها دسترسی داشته باشید.

برخی‌از ویژگی‌های کلیدی فهرست کردن عناصر رسانه‌ای عبارت‌اند از:

• فهرست کردن عناصر رسانه‌ای از آلبوم‌های ایجادشده توسط برنامه خاص یا کل کتابخانه ایجادشده توسط برنامه

• برای محدود کردن نتایج، هنگام فهرست کردن، فیلترها (تاریخ، دسته محتوا، نوع رسانه) را اعمال کنید

• بازیابی mediaItem شیء با جزئیات ضروری مثل پیوندهای مستقیم و فراداده.

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

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

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

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

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

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

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

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

برای فهرست کردن فایل‌های رسانه‌ای، mediaItems.list را فراخوانی کنید.

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

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

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

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

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

صفحه‌بندی برای 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 که قبلاً استفاده شده است نباید در همان درخواست استفاده شود.