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

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

قبل از شروع

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

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

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

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

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

زمانی که 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 های پایه

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

برای API انتخابگر:

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

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

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

URL های پایه به مدت ۶۰ دقیقه فعال باقی می‌مانند.

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

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

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

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

پارامتر
w , h

توضیحات

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

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

مثال‌ها:

base-url=wmax-width-hmax-height

در اینجا مثالی برای نمایش یک آیتم رسانه‌ای با عرض نه بیشتر از ۲۰۴۸ پیکسل و ارتفاع نه بیشتر از ۱۰۲۴ پیکسل آورده شده است:

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

توضیحات

پارامتر c ، کراپ.

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

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

مثال‌ها:

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

در این مثال، برنامه یک آیتم رسانه‌ای را نمایش می‌دهد که دقیقاً ۲۵۶ پیکسل عرض و ۲۵۶ پیکسل ارتفاع دارد، مانند یک تصویر بندانگشتی:

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 های پایه ویدیو استفاده کنید، آمده است:

پارامتر
dv

توضیحات

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

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

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

قبل از استفاده از این پارامتر، بررسی کنید که فیلد 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

مثال زیر یک تصویر کوچک ویدیویی را نمایش می‌دهد که دقیقاً ۱۲۸۰ پیکسل عرض و ۷۲۰ پیکسل ارتفاع دارد و شامل دکمه پخش نمی‌شود: 

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

آدرس‌های اینترنتی پایه عکس‌های متحرک

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

پارامتر
dv

توضیحات

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

w ، h ، c و d

توضیحات

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

سیاست محتوا و فیلترینگ

گوگل فوتوز به طور پیش‌فرض فیلتر محتوای استاندارد را برای تصاویر و ویدیوهای نمایش داده شده در یک دستگاه مشترک مانند تلویزیون یا نمایشگر دیجیتال اعمال می‌کند. این فیلتر برای بهینه‌سازی تجربه مشاهده با حذف محتوایی مانند موارد زیر طراحی شده است:

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

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

مراحل بعدی

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