دستگاه ها را ایجاد و مدیریت کنید

این راهنما نحوه ایجاد، مدیریت و حذف دستگاه ها را پوشش می دهد. مدیریت صحیح دستگاه به ایجاد یک تجربه کاربری روان و استفاده کارآمد از Ambient API کمک می کند.

ایجاد دستگاه ها

پس از اینکه کاربر با استفاده از OAuth 2.0 برای جریان برنامه های تلویزیون و دستگاه ورودی محدود با موفقیت احراز هویت کرد، یک دستگاه در حساب Google Photos او ایجاد کنید.

هنگامی که برنامه شما با موفقیت دستگاهی را با استفاده از روش devices.create ایجاد می‌کند، Ambient API یک شی AmbientDevice را برمی‌گرداند که شامل id ایجاد شده توسط Google است. این id ایمن ذخیره کنید و آن را با کاربران خود مرتبط کنید.

مهم: id را ذخیره کنید. اگر id ایجاد شده توسط Google را ذخیره نکنید، بعداً نمی‌توانید دستگاهی را بازیابی یا مدیریت کنید. این می‌تواند منجر به یتیم شدن دستگاه‌هایی در حساب‌های Google Photos کاربران شما شود، که توسط برنامه شما قابل دسترسی یا پاکسازی نیست.

ایجاد دستگاه ساده با OAuth

Ambient API یک جریان OAuth ساده ارائه می دهد که می تواند یک دستگاه را همزمان با احراز هویت کاربر ایجاد کند. با ارسال پارامتر state اضافی در درخواست اولیه OAuth خود، می‌توانید فرآیند ایجاد دستگاه را مستقیماً به جریان ورود به سیستم کاربر مرتبط کنید و با کاهش تعداد کدهای QR که آنها باید اسکن کنند، تجربه کاربر را ساده‌تر می‌کنید.

برای جزئیات بیشتر و یک مثال، به جریان احراز هویت ساده برای راهنمای Ambient API مراجعه کنید.

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

برنامه شما می تواند تا 100 دستگاه برای هر کاربر ایجاد کند. اگر از این حد تجاوز شود، API یک خطای RESOURCE_EXHAUSTED را برمی‌گرداند.

مدیریت دستگاه ها

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

بازیابی دستگاه ها

برای بازیابی اطلاعات یک دستگاه خاص، از روش devices.get با id منحصر به فرد آن استفاده کنید. این برای بررسی وضعیت دستگاه مفید است، مانند اینکه آیا mediaSourcesSet درست است یا خیر.

به روز رسانی دستگاه ها

می‌توانید ویژگی‌های خاصی از یک دستگاه موجود، مانند نام نمایشی آن را با استفاده از روش devices.patch به‌روزرسانی کنید. این به کاربران امکان می‌دهد دستگاه‌های خود را شخصی‌سازی کنند و شناسایی آنها را در Google Photos آسان‌تر می‌کند.

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

دستگاه ها را حذف کنید

برای پاکسازی مناسب و کنترل کاربر، استراتژی حذف دستگاه ها را اجرا کنید. با استفاده از روش devices.delete می توانید یک دستگاه را حذف کنید.

سناریوهای زیر را برای حذف دستگاه ها در نظر بگیرید:

• قطع ارتباط کاربر : اگر کاربری برنامه شما را از حساب Google Photos خود قطع کرد، باید دستگاه مربوطه را حذف کنید.
• دستگاه‌های Orphaned : اگر ردیابی id را گم کردید، اما همچنان requestId مورد استفاده در حین ایجاد را دارید، می‌توانید از requestId با devices.delete برای حذف یک دستگاه یتیم استفاده کنید. این به جلوگیری از تکرارهای تصادفی کمک می کند و حساب کاربر را تمیز نگه می دارد.

ملاحظات مهم و بهترین شیوه ها

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

مراحل بعدی

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