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

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

إنشاء الأجهزة

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

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

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

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

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

لمزيد من التفاصيل والمثال، يُرجى الاطّلاع على دليل مسار المصادقة المبسّط ل واجهة برمجة التطبيقات 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 للحصول على مزيد من المعلومات.
• المستندات المرجعية: راجِع الموسوعة الشاملة للمستندات المرجعية حول الأجهزة للحصول على معلومات مفصّلة حول جميع الطرق المتاحة ومعلمات الطلب والرد ورموز الأخطاء.
• إدراج عناصر الوسائط واستردادها: بعد إنشاء أجهزتك وإدارتها، تعرَّف على كيفية إدراج عناصر الوسائط واستردادها لعرضها عليها.