ایجاد و مدیریت دستگاه‌ها

این راهنما نحوه ایجاد، مدیریت، و حذف دستگاه‌ها را پوشش می‌دهد. مدیریت صحیح دستگاه به ایجاد تجربه کاربری روان و استفاده کارآمد از 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 و فراخوانی devices.create با requestId منطبق، می‌توانید فرایند ایجاد دستگاه را مستقیماً به جریان ورود به سیستم کاربر پیوند دهید و با کاهش تعداد رمزینه‌های پاسخ‌سریع موردنیاز برای اسکن کردن، تجربه کاربر را ساده‌تر کنید.

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

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

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

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

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

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

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

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

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

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

حذف دستگاه‌ها

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

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

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

ملاحظات مهم و روال‌های مطلوب

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

مراحل بعدی

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