إنشاء الأجهزة وإدارتها

يتناول هذا الدليل كيفية إنشاء الأجهزة وإدارتها وحذفها. تساعد الإدارة السليمة للأجهزة في توفير تجربة سلسة للمستخدمين واستخدام فعّال لواجهة Ambient API.

إنشاء أجهزة

بعد أن تتم مصادقة المستخدم بنجاح باستخدام مسار OAuth 2.0 للتلفزيون وتطبيقات الأجهزة ذات الإدخال المحدود، يمكنك إنشاء جهاز في حسابه على "صور Google".

عندما ينشئ تطبيقك جهازًا بنجاح باستخدام طريقة devices.create، تعرض Ambient API كائن AmbientDevice يتضمّن id من إنشاء Google. يمكنك تخزين id هذا بأمان وربطه بالمستخدمين.

ملاحظة مهمة: احفظ id. في حال عدم حفظ id الذي أنشأته Google، لن تتمكّن من استرداد جهاز أو إدارته لاحقًا. قد يؤدي ذلك إلى ظهور أجهزة معزولة في حسابات المستخدمين على "صور Google"، ولا يمكن لتطبيقك الوصول إليها أو حذف بياناتها.

إنشاء الأجهزة بسهولة باستخدام OAuth

توفّر Ambient API مسارًا مبسّطًا لبروتوكول OAuth. من خلال تمرير المَعلمة الإضافية state في طلب OAuth الأوّلي واستدعاء devices.create باستخدام requestId المطابق، يمكنك ربط عملية إنشاء الجهاز مباشرةً بمسار تسجيل الدخول الخاص بالمستخدم، ما يسهّل تجربة المستخدم من خلال تقليل عدد رموز الاستجابة السريعة التي يحتاج إلى مسحها ضوئيًا.

لمزيد من التفاصيل ومثال، يُرجى الاطّلاع على دليل مسار المصادقة المبسّط لواجهة Ambient API.

الحدود القصوى للأجهزة

يمكن لتطبيقك إنشاء ما يصل إلى 100 جهاز لكل مستخدم. في حال تجاوز هذا الحدّ، ستعرض واجهة برمجة التطبيقات الخطأ RESOURCE_EXHAUSTED.

إدارة الأجهزة

بعد إنشاء جهاز وربطه بحساب المستخدم على "صور Google"، قد تحتاج إلى إدارة دورة حياته.

استرداد الأجهزة

للحصول على معلومات عن جهاز معيّن، استخدِم طريقة devices.get مع id الفريد. ويُعدّ ذلك مفيدًا للتحقّق من حالة الجهاز، مثل ما إذا كانت قيمة mediaSourcesSet صحيحة.

تحديث الأجهزة

يمكنك تعديل بعض خصائص جهاز حالي، مثل الاسم المعروض، باستخدام طريقة devices.patch. يتيح ذلك للمستخدمين تخصيص أجهزتهم ويسهّل التعرّف عليها في "صور Google".

ملاحظة: من الممارسات الجيدة أن تتيح للمستخدم فرصة تسمية جهازه قبل إنشائه. يسهّل ذلك على المستخدم التعرّف على جهازه عند اختيار ملفات الوسائط في حسابه على "صور Google".

حذف الأجهزة

تنفيذ استراتيجية لحذف الأجهزة من أجل إجراء عملية تنظيف مناسبة ومنح المستخدمين إمكانية التحكّم يمكنك حذف جهاز باستخدام الطريقة devices.delete.

إليك السيناريوهات التالية لحذف الأجهزة:

• إلغاء ربط المستخدم: إذا ألغى المستخدم ربط تطبيقك بحسابه على "صور Google"، عليك حذف الجهاز المرتبط.
• الأجهزة غير المرتبطة: إذا فقدت id ولكن لا يزال لديك requestId الذي تم استخدامه أثناء عملية الإنشاء، يمكنك استخدام requestId مع devices.delete لإزالة جهاز غير مرتبط. يساعد ذلك في منع تكرار المحتوى عن طريق الخطأ ويحافظ على نظافة حساب المستخدم.

اعتبارات مهمة وأفضل الممارسات

• مراحل نشاط الجهاز وتفويض المستخدم: ستحتاج إلى إدارة مراحل نشاط الأجهزة ورموز تفويض المستخدم. عليك مراعاة المدة التي تظل فيها الأجهزة نشطة وكيفية التعامل مع عمليات إعادة تحميل الرموز المميزة أو إعادة التفويض إذا أصبح الجهاز غير نشط أو انتهت صلاحية الرمز المميز.
• معالجة الأخطاء: يجب اتّخاذ إجراءات فعالة لمعالجة الأخطاء في جميع طلبات البيانات من واجهة برمجة التطبيقات المتعلّقة بالأجهزة. استعِدّ لسيناريوهات مثل:
  • ‫NOT_FOUND: إذا لم يكن الجهاز متوفّرًا أو لم يكن مملوكًا للمستخدم
  • ‫RESOURCE_EXHAUSTED: إذا تجاوزت الحد الأقصى لعدد الأجهزة
  • ‫ALREADY_EXISTS: إذا حاولت إنشاء جهاز باستخدام requestId موجود مسبقًا

الخطوات التالية

• نموذج التطبيق: يتضمّن نموذج التطبيق مثالاً على إنشاء جهاز والتعامل مع بيانات الاستجابة. يمكنك الاطّلاع على الدالة createDevice لمزيد من المعلومات.
• المستندات المرجعية: راجِع المستندات المرجعية الشاملة حول الأجهزة للحصول على معلومات تفصيلية حول جميع الطرق المتاحة، ومعلَمات الطلب والرد، ورموز الأخطاء.
• عرض ملفات الوسائط واستردادها: بعد إنشاء أجهزتك وإدارتها، تعرَّف على كيفية عرض ملفات الوسائط واستردادها لعرضها على هذه الأجهزة.