فهرست و بازیابی آیتم های رسانه ای

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

قبل از شروع

نظرسنجی برای mediaSourcesSet

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

به طور دوره ای متد devices.get برای deviceId خاص فراخوانی کنید. قسمت mediaSourcesSet را در پاسخ AmbientDevice نظارت کنید. در ابتدا false خواهد بود. هنگامی که کاربر با موفقیت منابع رسانه ای را انتخاب کرد، این قسمت به true تغییر می کند.

پاسخ AmbientDevice شامل pollingConfig با pollInterval است که باید به عنوان یک دستورالعمل برای فرکانس نظرسنجی خود استفاده کنید.

فهرست موارد رسانه

هنگامی که mediaSourcesSet برای یک دستگاه true است، می توانید واکشی آیتم های رسانه انتخاب شده توسط کاربر را شروع کنید.

  1. از نقطه پایانی mediaItems.list استفاده کنید: یک درخواست GET به https://photosambient.googleapis.com/v1/mediaItems ارائه دهید و deviceId در مسیر ارائه دهید.

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

  3. پردازش آیتم های رسانه: پاسخ شامل آرایه ای از اشیاء AmbientMediaItem خواهد بود که هر کدام یک آیتم رسانه انتخاب شده را نشان می دهد. این اشیاء شامل جزئیات ضروری مانند:

    • id : شناسه منحصر به فرد مورد رسانه.
    • creationTime : مهر زمانی که آیتم رسانه ایجاد شد.
    • mediaFile : یک شی حاوی جزئیات برای دسترسی به محتوای واقعی.

فیلد mediaFile شامل baseUrl است. این baseUrl همان چیزی است که برای ساختن URL ها برای دسترسی به محتوای آیتم رسانه در وضوح یا فرمت های مختلف استفاده می کنید.

URL های پایه

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

برای Picker API:

همه اشیاء PickedMediaItem.mediaFile شامل یک baseUrl هستند.

URL های پایه به مدت 60 دقیقه فعال می مانند، اما اگر کاربر مجوزهای برنامه شما را از طریق تنظیمات حساب Google خود لغو کند، زودتر منقضی می شود.

برای کتابخانه API:

URL های پایه به مدت 60 دقیقه فعال می مانند.

URL های پایه مختلف عبارتند از:

  • baseUrl : مستقیماً به عکس، تصویر کوچک یک ویدیو یا دانلود بایت های ویدیو دسترسی داشته باشید.
  • coverPhotoBaseUrl : مستقیماً به عکس روی جلد آلبوم دسترسی پیدا کنید.
  • profilePictureBaseUrl : مستقیماً به عکس نمایه صاحب یک mediaItem دسترسی پیدا کنید.

URL های پایه تصویر

در اینجا لیستی از گزینه هایی است که می توانید با URL های پایه تصویر استفاده کنید:

پارامتر
w , h

توضیحات

پارامترهای عرض، w و ارتفاع، h .

برای دسترسی به یک آیتم رسانه تصویر، مانند یک عکس یا یک تصویر کوچک برای یک ویدیو، باید ابعادی را که قصد دارید در برنامه خود نمایش دهید را مشخص کنید (تا با حفظ نسبت ابعاد، تصویر را به این ابعاد تغییر دهید). برای انجام این کار، همانطور که در مثال ها نشان داده شده است، URL پایه را با ابعاد مورد نیاز خود به هم متصل کنید.

مثال ها:

base-url=wmax-width-hmax-height

در اینجا یک مثال برای نمایش یک آیتم رسانه ای نه بیشتر از 2048 پیکسل و نه بلندتر از 1024 پیکسل وجود دارد:

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

توضیحات

پارامتر crop، c .

اگر می خواهید تصویر را به ابعاد دقیق عرض و ارتفاعی که مشخص کرده اید برش دهید، URL پایه را با پارامتر اختیاری -c به همراه پارامترهای اجباری w و h به هم بپیوندید.

اندازه (بر حسب پیکسل) باید در محدوده [1، 16383] باشد. اگر عرض یا ارتفاع تصویر از اندازه درخواستی بیشتر شود، تصویر کوچک شده و برش داده می شود (با حفظ نسبت تصویر).

مثال ها:

base-url=wmax-width-hmax-height-c

در این مثال، برنامه یک آیتم رسانه ای را نمایش می دهد که دقیقاً 256 پیکسل عرض در 256 پیکسل ارتفاع دارد، مانند یک تصویر کوچک:

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

توضیحات

دانلود، پارامتر d .

اگر می‌خواهید تصویری را دانلود کنید که تمام ابرداده‌های Exif به جز فراداده مکان را حفظ می‌کند، URL پایه را با پارامتر d پیوند دهید.

مثال ها:

base-url=d

در این مثال، برنامه یک تصویر را با تمام ابرداده ها به جز ابرداده مکان دانلود می کند:

https://lh3.googleusercontent.com/p/Az....XabC=d

URL های پایه ویدیو

در اینجا لیستی از گزینه هایی است که می توانید با URL های پایه ویدیو استفاده کنید:

پارامتر
dv

توضیحات

برای دسترسی به بایت‌های یک mediaItem ویدیویی، آدرس baseUrl با پارامتر dv ویدیوی بارگیری پیوند دهید.

پارامتر dv یک نسخه با کیفیت بالا و رمزگذاری شده از ویدیوی اصلی را درخواست می کند. این پارامتر با پارامترهای w و h سازگار نیست.

نشانی‌های وب پایه برای بارگیری ویدیو ممکن است تا چند ثانیه طول بکشد تا بایت‌ها را بازگردانند.

قبل از استفاده از این پارامتر، بررسی کنید که قسمت mediaMetadata.status اقلام رسانه READY است. در غیر این صورت، اگر پردازش مورد رسانه شما به پایان نرسیده باشد، ممکن است خطایی دریافت کنید.

مثال ها:

base-url=dv

مثال زیر نحوه دانلود بایت های یک ویدیو را به شما نشان می دهد:

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w ، h ، c و d

توضیحات

برای دسترسی به تصویر کوچک ویدیو از هر یک از پارامترهای URL پایه تصویر استفاده کنید.

به‌طور پیش‌فرض، همه ریز عکس‌های ویدیو شامل یک دکمه پخش است. برای حذف این پوشش، پارامتر -no را ببینید.

مثال ها:

برای مثال به جدول URL های پایه تصویر مراجعه کنید.

no

توضیحات

پوشش تصویر کوچک حذف، no پارامتر.

اگر می خواهید تصویر کوچک یک ویدیو را بدون همپوشانی دکمه پخش بازیابی کنید، URL پایه را با پارامتر no به هم متصل کنید.

پارامتر no باید حداقل با یکی از پارامترهای URL پایه تصویر استفاده شود.

مثال ها:

base-url=wmax-width-hmax-height-no

مثال زیر یک تصویر کوچک ویدیویی را نمایش می دهد که دقیقاً 1280 پیکسل عرض در 720 پیکسل ارتفاع دارد و شامل دکمه پخش همپوشانی نمی شود: 

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

URL های پایه عکس متحرک

عکس‌های متحرک شامل عناصر عکس و ویدیو هستند. می‌توانید از پارامترهای URLهای پایه تصویر یا URLهای پایه ویدیو برای درخواست‌های baseUrl عکس متحرک استفاده کنید.

پارامتر
dv

توضیحات

برای بازیابی عنصر ویدیوی یک آیتم رسانه عکس متحرک، از پارامتر dv همانطور که برای دانلود از URL های پایه ویدیو استفاده می کنید استفاده کنید.

w ، h ، c و d

توضیحات

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

مراحل بعدی

  • نمونه برنامه: برنامه نمونه ما شامل نمونه ای از فهرست بندی و بازیابی آیتم های رسانه است. برای اطلاعات بیشتر، توابع checkMediaSourcesSet و fetch_media_item_list را بررسی کنید.
  • مستندات مرجع: برای اطلاعات دقیق در مورد تمام روش‌های موجود، پارامترهای درخواست و پاسخ و کدهای خطا، اسناد مرجع جامع را در مورد موارد رسانه مرور کنید.