شروع به کار با Ambient API

Ambient API به برنامه شما امکان می‌دهد دستگاه‌های محیطی را به حساب Google Photos کاربر متصل کند و عکس‌های انتخابی او را نمایش دهد.

جریان Ambient API

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

  1. بررسی وجود دستگاه (توصیه می‌شود): قبل‌از ایجاد دستگاه جدید، توصیه می‌شود بررسی کنید که آیا دستگاهی برای کاربر فعلی وجود دارد یا نه. برنامه شما باید نگاشتی بین کاربر داخلی شما و deviceId ارائه‌شده توسط Google برای هر دستگاهی که ازطریق برنامه شما ایجاد می‌کند، حفظ کند. اگر deviceId برای کاربر پیدا شد، می‌توانید به بازآوری کردن کد مجازسازی او (درصورت نیاز) ادامه دهید.

  2. آغاز مجوز OAuth 2.0: با درخواست کد مجوز، جریان OAuth 2.0 برای تلویزیون و دستگاه‌های ورودی محدود را آغاز کنید.

  3. ایجاد دستگاه جدید: برنامه شما با فراخوانی CreateDevice و ارائه UUID نسخه ۴ معتبر، دستگاهی در حساب Google Photos کاربر ایجاد می‌کند.

    پس‌از ایجاد موفقیت‌آمیز دستگاه، API یک AmbientDevice شیء حاوی deviceId اختصاص‌داده‌شده توسط Google را برمی‌گرداند. بسیار مهم است که برنامه‌تان این deviceId را ذخیره کند و آن را با کاربرانتان مرتبط کند.

  4. نمایش settingsUri: شیء AmbientDevice شامل settingsUri است. این شناسه منبع یکسان را به کاربر ارائه دهید، معمولاً به‌صورت رمزینه پاسخ‌سریع، که کاربر می‌تواند آن را بااستفاده از دستگاه همراهش اسکن کند. این نشانی وب کاربر را به برنامه Google Photos هدایت می‌کند که در آن می‌تواند منابع رسانه‌ای (برای نمونه، آلبوم‌ها) را که می‌خواهد در دستگاه محیطی‌اش نمایش داده شود پیکربندی کند.

  5. نظرسنجی برای mediaSourcesSet: برنامه شما باید به‌طور دوره‌ای روش GetDevice را فراخوانی کند و deviceId را ارائه دهد تا وضعیت دستگاه محیطی را بررسی کند. فیلد mediaSourcesSet را در AmbientDevice پاسخ پایش کنید. در ابتدا نادرست خواهد بود.

    وقتی کاربر باموفقیت منابع رسانه را در برنامه Google Photos انتخاب کرد، این فیلد به true تغییر می‌کند.

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

  6. بازیابی موارد رسانه‌ای: وقتی mediaSourcesSet مقدار true را برمی‌گرداند، برنامه شما می‌تواند واکشی موارد رسانه‌ای انتخاب‌شده توسط کاربر را شروع کند.

    روش ListMediaItems را فراخوانی کنید و deviceId را ارائه دهید. این «میانای برنامه‌سازی کاربردی» ListMediaItemsResponse حاوی فهرستی از AmbientMediaItem اشیا را برمی‌گرداند. هر AmbientMediaItem شامل جزئیاتی مانند id، createTime، و یک شیء MediaFile با فراداده‌های اضافی است. MediaFile حاوی baseUrl است که می‌توانید از آن برای واکشی کردن بایت‌های واقعی یک عنصر رسانه‌ای استفاده کنید. برای جزئیات مربوط به پارامترهای تکمیلی baseUrl، راهنمای فهرست کردن و بازیابی عناصر رسانه‌ای را مرور کنید.

  7. نمایش موارد رسانه‌ای: از baseUrl از MediaFile برای بارگیری و نمایش محتوای رسانه‌ای در دستگاه محیطی استفاده کنید.

ملاحظات مهم

محدودیت و مدیریت دستگاه:

  • محدودیت‌های دستگاه: از محدودیت ۱۰۰ دستگاه برای هر کاربر برنامه خود آگاه باشید.
  • فعالیت دستگاه و نشان‌ها: باید چرخه حیات دستگاه‌ها و نشان‌های مجوز کاربر را مدیریت کنید. درنظر بگیرید که دستگاه‌ها چه مدت فعال می‌مانند و اگر دستگاهی غیرفعال شود یا توکن منقضی شود، چگونه بازآوری توکن یا بازصدور مجوز را مدیریت خواهید کرد.

راهنمای ایجاد و مدیریت دستگاه‌ها جزئیات بیشتری دارد.

کار با فایل‌های رسانه‌ای:

  • استفاده از عنصر رسانه‌ای: نحوه واکشی و مدیریت صحیح محتوای عنصر رسانه‌ای بااستفاده از baseUrl، ازجمله هرگونه اصالت‌سنجی یا پارامترهای لازم را درک کنید.
  • مدیریت خطا: مدیریت خطای قدرتمندی برای تماس‌های API پیاده‌سازی کنید، ازجمله سناریوهایی مثل NOT_FOUND برای دستگاه‌ها، FAILED_PRECONDITION اگر منابع رسانه تنظیم نشده باشند، و RESOURCE_EXHAUSTED اگر به محدودیت‌های دستگاه رسیده باشید.

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

مراحل بعدی