با Ambient API شروع کنید

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

جریان API Ambient

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

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

  2. مجوز OAuth 2.0 را شروع کنید (و به صورت اختیاری دستگاه ایجاد کنید): با درخواست کد مجوز، جریان OAuth 2.0 برای تلویزیون و دستگاه های ورودی محدود را شروع کنید.

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

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

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

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

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

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

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

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

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

ملاحظات مهم

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

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

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

کار با آیتم های رسانه ای:

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

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

مراحل بعدی