عمومی
س: زیرساخت تکمیل سفارش ابری به ابری خود را کجا و با چه زبانی باید پیادهسازی کنیم؟
الف) تا زمانی که از SSL مدرن (TLS) و OAuth 2.0 پشتیبانی کند، میتوانید زیرساخت خود را روی هر پلتفرم و به هر زبانی که انتخاب میکنید پیادهسازی کنید. توصیه میکنیم تا حد امکان نزدیک به بقیه زیرساخت خود مستقر شوید تا قابلیت اطمینان بهبود یابد و تأخیر اجرا در دستگاههای کاربر واقعی کاهش یابد.
س: آیا شناسههای دستگاه باید منحصر به فرد باشند؟
الف) شناسهها باید منحصر به فرد باشند. اگر شناسههای منحصر به فردی در سراسر سرویس خود ندارید، باید حداقل در سطح هر کاربر منحصر به فرد باشند. کاربری را تصور کنید که چندین خانه دارد و هر دو خانه با یک کاربر یکپارچه شدهاند. درخواست روشن کردن چراغ در یک خانه نباید چراغی با شناسه مشابه در خانه دیگر را روشن کند.
س: آیا نام دستگاهها باید منحصر به فرد باشد؟
الف) نامها لازم نیست منحصر به فرد باشند، اگرچه با گذشت زمان ممکن است افراد را تشویق کنیم که پس از راهاندازی، برای بهبود تجربه کاربری، نامگذاریهای نامناسب را اصلاح کنند.
در اینجا یک راهنمای سریع برای نامگذاری آورده شده است:
- نامها باید چیزهایی باشند که مردم واقعاً بتوانند بگویند.
- ما زیرمجموعههای رشتهها را تشخیص میدهیم، بنابراین اگر شما «acme color light» داشته باشید، ما به «acme light» نیز پاسخ خواهیم داد.
- ما هم یک نام توصیفی برای محصول و هم یک یا چند نام تعریفشده توسط کاربر را توصیه میکنیم.
- کاربران نیازی به نامگذاری اتاقهای روشنایی ندارند، زیرا ما اتاقهایی برای این کار داریم؛ آنها باید برای هر اتاق نامهای منحصر به فردی داشته باشند، اما همیشه میتوانند از جمع برای فرمان دادن به همه چیز استفاده کنند (برای مثال، دو لامپ در دیوارکوبهای دفتر «نور شمال» و «نور شرق» هستند، اما میتوانند فقط به عنوان «چراغها» فرمان داده شوند).
س: وضعیت دستگاه چند وقت یکبار بهروزرسانی میشود؟
الف) حالت گذرا (Ephemeral state) یا با اجرای کوئری (QUERY) یا اجرا (EXECUTE) بازیابی میشود، که هر دو اعمالی هستند که توسط کاربر آغاز میشوند. اگر کاربر بپرسد «آیا چراغ روشن است؟» یا بخواهد چراغی را روشن کند، برای فهمیدن حالت فعلی باید یک کوئری انجام دهیم.
س: آیا میتوان Home Graph را مستقیماً با وضعیت فعلی دستگاه بهروزرسانی کرد؟
پاسخ: بله، از فراخوانی API Report State استفاده کنید.
پیوند حساب و OAuth
س: آیا لازم است حساب کاربری را لینک کنیم؟
پاسخ: بله، برای اتصال دستگاههای کاربر به سرویسهای ابری ارائهدهنده، اتصال حساب کاربری الزامی است.
س: برای OAuth، ما هر ۱۵.۲۱۳ ساعت یکبار توکنهای دسترسی را منقضی میکنیم، آیا این اشکالی ندارد؟
الف) بله، اما لطفاً با یک زمان انقضای نسبتاً کوتاه، مثلاً ۱۰ تا ۲۰ دقیقه، آزمایش کنید. کلاینت OAuth ما باید در صورت نیاز توکنها را بهروزرسانی کند و آزمایش با یک زمان انقضای کوتاه، ثابت خواهد کرد که این روش کار میکند.
اهداف
س: چه زمانی SYNC اتفاق میافتد؟
پاسخ: همگامسازی بلافاصله پس از تکمیل OAuth و پس از برقراری درخواست همگامسازی (Request Sync) ، اتفاق میافتد.
س: چرا SYNC کار نمیکند؟
الف) دلایل رایج زیادی برای عدم موفقیت این روش وجود دارد.
شما نوع دستگاه اشتباهی را ارسال میکنید.
- برای مثال، ما انتظار
action.devices.types.LIGHTداریم، اما شماaction.devices.types.Lightرا ارسال میکنید.
- برای مثال، ما انتظار
شما در حال ارسال انواع دستگاههای پشتیبانی نشده هستید.
- برای مثال، شما
action.devices.types.FLASHLIGHTرا ارسال میکنید - این چیزی نیست که ما پشتیبانی کنیم.
- برای مثال، شما
شما فیلدهای نامعتبر/پشتیبانی نشده ارسال میکنید.
- برای مثال، شما فیلدی دارید که در مشخصات ما نیست.
مشکل قالببندی دیگری در پاسخ SYNC شما وجود دارد.
- براکتهایتان را بررسی کنید!
شما با مشکل لینک کردن حساب کاربری مواجه هستید.
- لطفاً تأیید کنید که یک توکن دسترسی معتبر در سربرگ Auth درخواست SYNC دریافت میکنید.
پاسخ به درخواست همگامسازی (SYNC) خیلی طول میکشد.
- لطفاً تأیید کنید که ظرف 5 ثانیه به درخواست همگامسازی (SYNC) پاسخ میدهید.
س: آیا پاسخ «در انتظار» قابل قبول است؟
الف) اگر دستگاههای شما به صورت بلادرنگ در دسترس باشند، ما قویاً پاسخ موفقیت/شکست را به پاسخ در حال انتظار ترجیح میدهیم. اگر احساس میکنید به پاسخ «در حال انتظار» نیاز دارید، لطفاً با ما تماس بگیرید -- ما میدانیم که برخی از دستگاههای کممصرف و غیر بلادرنگ ممکن است به پاسخ در حال انتظار و مدل اجرای ناهمزمان نیاز داشته باشند.
آزمایش و ارسال
س: آیا میتوانیم یک محیط ابری توسعه راهاندازی کنیم؟
الف) بله، شما میتوانید یک محیط ابری راهاندازی نشده و پیکربندی آن را آزمایش کنید.
س: اقدام من در بخش کنترل خانه برنامه Google Home قابل مشاهده نیست. چه اتفاقی میافتد؟
الف) تأیید کنید که شما توسعهدهنده این پروژه هستید.
گزارش ایالت
س: آیا پیشنیازهایی برای اجرای Report State وجود دارد؟
الف) این پروژه باید از رابط برنامهنویسی کاربردی خانه هوشمند (Smart Home API) استفاده کند، از OAuth2 پشتیبانی کند و ویژگیهایی داشته باشد که حالت(هایی) برای گزارش داشته باشند.
س: چند وقت یکبار نیاز به گزارش وضعیت (State) در یک دستگاه داریم؟
الف) گوگل به گذار و وضعیت نهایی علاقهمند است. با این حال، اگر تغییرات وضعیت زیادی در مدت زمان کوتاهی رخ دهد (مثلاً کاربر در یک دقیقه سه بار یخچال را باز و بسته کند یا یک دیمر را حرکت دهد)، ما فقط به وضعیت نهایی گزارش شده نیاز داریم.
س: آیا هنگام برقراری تماسهای Report State، باید وضعیت کامل دستگاه ارسال شود؟
الف) بهروزرسانیهای جزئی وضعیت پشتیبانی نمیشوند، بنابراین فراخوانیهای Report State باید همیشه شامل تمام دادههای مربوط به یک ویژگی خاص که بهروزرسانی شده است، باشد. اگر دو ویژگی باعث ایجاد ناسازگاری شوند، باید با هم گزارش شوند.
س: آیا گوگل میتواند از دستگاه من برای دریافت وضعیت آن پرسوجو کند (یعنی از دستگاه نظرسنجی کند)؟
الف) این یک مکانیزم پشتیبان است که ما توصیه نمیکنیم. اگر نیاز باشد که مرتباً برای آن کاربران به نظرسنجی از یک دستگاه برگردیم، نمیتوانیم تضمین کنیم که بار اضافی چقدر خواهد بود. این نیاز از سطوح بصری جدید ناشی میشود. علاوه بر مشکل بار ناشناخته، این یک تجربه کاربری ضعیف خواهد بود. ما احساس میکنیم که Report State برای پلتفرم بسیار مهم است.
س: چه ویژگیهایی در حال حاضر از Report State پشتیبانی میکنند؟
الف) تمام ویژگیهای عمومی که وضعیتهای مرتبط دارند پشتیبانی میشوند. هرگونه تغییر در وضعیت آنلاین دستگاه نیز باید گزارش شود.
توجه داشته باشید که صحنهها وضعیت ندارند. با این حال، ممکن است منجر به تغییر وضعیت دستگاه(ها) شوند. اگر هر دستگاهی در Google Home Graph وضعیت تغییر یافتهای داشته باشد، باید گزارش شود.
س: آیا گزارش وضعیت نیاز به ارسال مهر زمانی دارد؟
الف) ما به مهر زمانی نیاز نداریم؛ آخرین وضعیت ارسال شده، فراخوانیهای قبلی را لغو میکند.
س: آیا اگر قبلاً وضعیت را در Query و/یا Execute ارسال کردهام، باید وضعیت را جداگانه گزارش کنم؟
الف) Home Graph فقط حالتی را که از طریق Report State ارسال میشود، ذخیره میکند. حالتی که به عنوان پاسخ به EXECUTE و QUERY intents برگردانده میشود، فقط برای پاسخهای صوتی به کاربر استفاده میشود و ذخیره نمیشود. در نتیجه، Report State باید فراخوانی شود، حتی اگر وضعیت جدید دستگاه قبلاً به عنوان پاسخ به EXECUTE یا QUERY intents برگردانده شده باشد.
س: عواقب عدم اجرای کامل گزارش وضعیت در مهلت تعیین شده چیست؟
الف) این امر منجر به کاهش تجربه کاربری، به عنوان مثال در Google Home app (GHA) و سطوح بصری خواهد شد. این به این معنی است که بسیاری از اهداف QUERY برای نظرسنجی وضعیت ارسال میشوند و ما نمیتوانیم تضمین کنیم که این امر با بار اضافی روی ابر شریک مطابقت خواهد داشت.
س: چگونه میتوانم پیادهسازی Report State خود را آزمایش کنم؟
الف) از نمایشگر نمودار خانگی استفاده کنید - یک ابزار تست سلف سرویس که وضعیت فعلی دستگاه شما را که در Home Graph ذخیره شده است، نشان میدهد.
س: آیا میتوانیم از یک requestId تصادفی برای Report State استفاده کنیم؟
الف) توصیه میکنیم شرکا در صورتی که Report State توسط درخواست EXECUTE فعال شده باشد، از همان requestId دریافتی از درخواست EXECUTE استفاده کنند، در غیر این صورت میتوانید از یک requestId تصادفی استفاده کنید.
س: اگر کاربری چندین دستگاه داشته باشد و وضعیت یکی از آنها تغییر کند، آیا باید آخرین وضعیت همه دستگاهها را گزارش دهیم؟
الف) خیر. شما فقط باید وضعیت آن دستگاه خاص را گزارش دهید.
بهترین شیوهها
س: چه نوع تأخیری قابل قبول است؟
الف) کمتر از ۲۰۰ میلیثانیه ایدهآل است، بین ۲ تا ۵ ثانیه هم مناسب است. اگر تأخیر شما حدود ۵ ثانیه است، با ما تماس بگیرید.
س: چگونه میتوانم بلندگوی صوتی خود را طوری تنظیم کنم که وقتی آفلاین است، به درستی پاسخ دهد؟
الف) وضعیت آفلاین را برای دستگاههای آفلاین برمیگرداند. ما برای این خطا عبارت «در حال حاضر در دسترس نیست» را به عنوان TTS برمیگردانیم. برای اطلاعات بیشتر، به بخش خطاها و استثنائات مراجعه کنید.