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

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

جریان API محیطی

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

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

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

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

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

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

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

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

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

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

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

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

ملاحظات مهم

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

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

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

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

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

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

مراحل بعدی