واجهة برمجة تطبيقات الأذونات

قبل استخدام أي من واجهات برمجة التطبيقات Home APIs، يجب أن يكون لدى التطبيق إذن بالوصول إلى الأجهزة في منزل المستخدم، والتي يُشار إليها في واجهة برمجة التطبيقات باسم البنية.

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

يتضمن استخدام Permissions API عددًا من الخطوات في تطبيقك وGoogle Cloud وGoogle Home Developer Console:

1. إعداد OAuth في Google Cloud
   1. توقيع التطبيق
   2. إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth
   3. تسجيل التطبيق وإنشاء بيانات الاعتماد
2. دمج واجهة برمجة التطبيقات Permissions API
   1. التحقّق من الأذونات
   2. طلب الأذونات
3. منح الأذونات
   1. تغيير الأذونات
   2. إبطال الأذونات

إعداد OAuth في Google Cloud

إذا كان لديك عميل OAuth تم إثبات ملكيته، يمكنك استخدام هذا العميل بدون إعداد عميل جديد. لمزيد من المعلومات، يُرجى الاطّلاع على في حال توفّر عميل OAuth حالي.

توقيع التطبيق

1. أنشئ مفتاح OAuth من خلال تشغيل التطبيق في Android Studio. عند تشغيل تطبيق أو تصحيح أخطاءه في Android Studio، يتم إنشاء مفتاح OAuth تلقائيًا مخصّص للتطوير وتصحيح الأخطاء. اطّلِع على Android Studio: توقيع إصدار debugging للحصول على شرح كامل.

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

   للحصول على تعليمات أكثر تفصيلاً، يُرجى الاطّلاع على مقالة تشغيل التطبيقات على جهاز برمجي على موقع "مطوّرو تطبيقات Android" الإلكتروني.

   الآن أوقِف التطبيق الذي يعمل.

2. احصل على الملف المرجعي SHA-1 لشهادة OAuth من خلال اتّباع التعليمات المفصّلة في مقالة إعداد OAuth 2.0 / التطبيقات الأصلية / Android على موقع مساعدة Google Cloud Console الإلكتروني.

إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

1. في Google Cloud Console، انتقِل إلى لوحة بيانات أداة اختيار المشاريع وحدِّد المشروع الذي تريد استخدامه لإنشاء بيانات اعتماد OAuth.
2. انتقِل إلى صفحة واجهات برمجة التطبيقات والخدمات، وانقر على بيانات الاعتماد في قائمة التنقّل.

3. إذا لم تكن قد ضبطت شاشة طلب الموافقة لهذا مشروع على Google Cloud، سيظهر الزر ضبط شاشة طلب الموافقة. في هذه الحالة، يمكنك ضبط شاشة طلب الموافقة باستخدام الإجراء التالي. بخلاف ذلك، انتقِل إلى القسم التالي.

   1. انقر على ضبط شاشة الموافقة. تظهر صفحة شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth.
   2. استنادًا إلى حالة الاستخدام، اختَر داخلي أو خارجي، ثم انقر على إنشاء. تظهر لوحة شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth.
   3. أدخِل المعلومات في صفحة معلومات التطبيق وفقًا للتعليمات الظاهرة على الشاشة، ثم انقر على حفظ ومتابعة. يتم عرض لوحة النطاقات.
   4. لست بحاجة إلى إضافة أي نطاقات، لذا انقر على حفظ ومتابعة. تظهر لوحة المستخدمون التجريبيون.
   5. إذا كنت تريد إضافة مستخدمين لاختبار إمكانية الوصول إلى تطبيقك، انقر على إضافة مستخدمين. تظهر لوحة إضافة مستخدمين. يحصل المستخدمون التجريبيون على امتياز منح الأذونات في تطبيقك.
   6. في الحقل الفارغ، أضِف عنوان بريد إلكتروني واحدًا أو أكثر لحساب Google، ثم انقر على إضافة.
   7. انقر على حفظ ومتابعة. تظهر لوحة الملخّص.
   8. راجِع معلومات شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth، ثم انقر على الرجوع إلى لوحة البيانات.

اطّلِع على مقالة إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth على موقع مركز مساعدة Google Cloud Console الإلكتروني للحصول على التفاصيل الكاملة.

تسجيل التطبيق وإنشاء بيانات الاعتماد

لتسجيل التطبيق في OAuth 2.0 وإنشاء بيانات اعتماد OAuth، اتّبِع التعليمات الواردة في إعداد OAuth 2.0. عليك تحديد نوع التطبيق، وهو تطبيق أصلي/تطبيق Android.

أضِف الملف المرجعي SHA-1 الذي حصلت عليه من توقيع التطبيق إلى عميل OAuth الذي أعددته على Google Cloud Console باتّباع التعليمات الواردة في مقالة إعداد OAuth 2.0 / التطبيقات الأصلية على موقع مساعدة Google Cloud Console الإلكتروني.

مع توصيل جهازك الجوّال بجهاز الكمبيوتر، اختَر جهازك من القائمة، ثم انقر على تشغيل المشروع مرة أخرى لتشغيله. للحصول على تعليمات أكثر تفصيلاً، يُرجى الاطّلاع على مقالة تشغيل التطبيقات على جهاز أجهزة على موقع "مطوّرو تطبيقات Android" الإلكتروني.

دمج واجهة برمجة التطبيقات Permissions API

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

أولاً، سجِّل ActivityResultCaller باستخدام حزمة تطوير البرامج (SDK). على سبيل المثال، في ما يلي كيفية تعامل التطبيق النموذجي مع ذلك:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

التحقّق من الأذونات

قبل طلب الأذونات، ننصحك بالتحقّق ممّا إذا كان مستخدم التطبيق قد منح الموافقة من قبل. لإجراء ذلك، استخدِم الأسلوب hasPermissions() لمثيل Home للحصول على Flow من قيم PermissionsState:

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
        println("Permissions state unavailable, request permissions")
      PermissionsState.NOT_GRANTED ->
        println("OAuth permission is enabled but not granted yet, request permissions")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

إذا أظهر الفحص PermissionsState من NOT_GRANTED أو PERMISSIONS_STATE_UNAVAILABLE، عليك طلب الأذونات. إذا أظهرت عملية التحقّق PermissionsState من GRANTED ولكن لم تُظهر أيّ بنية في المكالمة اللاحقة إلى structures()، يعني ذلك أنّ المستخدم ألغى إذن الوصول إلى التطبيق من خلال صفحة إعدادات Google Home app (GHA)، وعليك طلب الأذونات. بخلاف ذلك، من المفترض أن يكون لدى المستخدم إذن الوصول.

طلب الأذونات

يجب منح تطبيقك الإذن بالوصول إلى الهياكل وال devices ضمن بنية معيّنة.

إذا لم يمنح المستخدم الأذونات، استخدِم الأسلوب requestPermissions() لمثيل Home لتشغيل واجهة مستخدم "الأذونات" ومعالجة النتيجة:

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

لكي يتم تشغيل واجهة مستخدم "الأذونات" بشكلٍ صحيح، يجب أن تكون قد أعددت بروتوكول OAuth لتطبيقك.

منح الأذونات

من المفترض أن يكون بإمكانك الآن تشغيل تطبيقك وأن يمنح المستخدم أذونات. يختلف نوع المستخدمين الذين يمكنهم منح الإذن وأنواع الأجهزة التي يمكن منح الأذونات لها، وذلك حسب ما إذا كنت قد سجّلت تطبيقك في Developer Console.

يجب تسجيل Developer Console لنشر تطبيق باستخدام واجهات برمجة تطبيقات Home. ليس من الضروري اختبار واجهات برمجة التطبيقات Home API واستخدامها. للوصول إلى ميزة تسجيل وحدة التحكّم، يُرجى التواصل مع فريق Google Technical Account Manager (TAM).

إذا لم يكن التطبيق مسجَّلاً في Developer Console، ستكون حالته غير تم التحقّق منه. ننصحك بإجراء ما يلي لاختبار استخدام واجهات برمجة التطبيقات في Home:

• يمكن فقط للمستخدمين المسجَّلين كمستخدمين اختباريين في وحدة تحكّم OAuth منح الأذونات للتطبيق. ويمكن إضافة 100 مستخدم اختباري كحد أقصى لتطبيق لم يتم إثبات ملكيته.

• سيتمكّن تطبيق لم يتم إثبات ملكيته من الوصول إلى الأجهزة من أي أنواع أجهزة متوافقة مع OAuth لواجهات برمجة التطبيقات في Home (قائمة أنواع الأجهزة في Developer Console). سيتم منح جميع الأجهزة في بنية معيّنة.

إذا تم تسجيل تطبيق في Developer Console و تمت الموافقة على وصوله إلى نوع جهاز واحد أو أكثر، وتم إكمال عملية التحقّق من العلامة التجارية لبروتوكول OAuth، سيكون التطبيق في حالة تم التحقّق منه. يجب أن تكون هذه الحالة مطلوبة لإطلاق تطبيق في مرحلة الإصدار العلني:

• لم تعُد الحدود المفروضة على المستخدمين التجريبيين سارية. يمكن لأي مستخدم منح الإذن للتطبيق.
• لا يمكن للمستخدم منح الإذن إلا لأنواع الأجهزة التي تمت الموافقة عليها في Developer Console.

بعد إعداد OAuth، يؤدي طلب التطبيق إلى requestPermissions() إلى بدء مربّعات الحوار التالية:

1. سيُطلَب من المستخدم اختيار حساب Google الذي يريد استخدامه.
2. يُطلَب من المستخدم اختيار البنية التي يريد منح التطبيق إذنًا بالوصول إليها.
   1. بالنسبة إلى التطبيق الذي لم يتم إثبات ملكيته، تصبح جميع أنواع الأجهزة المتوافقة مع واجهات برمجة تطبيقات Home API متاحة للتطبيق.
   2. بالنسبة إلى التطبيق الذي تم التحقّق منه، يمكن للمستخدم منح الإذن لأنواع الأجهزة التي تمت الموافقة عليها في Developer Console فقط.
   3. بالنسبة إلى أنواع الأجهزة الحسّاسة التي يمكن للتطبيق الوصول إليها وإدارتها، يمكن للمستخدم تقييد الوصول على أساس كل جهاز. على سبيل المثال، إذا كان لدى المستخدم ثلاثة أقفال، يمكنه منح إذن الوصول إلى قفل واحد فقط من هذه الأقفال.

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

تغيير الأذونات

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

ويمكن تنفيذ ذلك من خلال استدعاء requestPermissions() مرة أخرى مع ضبط العلامة forceLaunch على true:

homeManager.requestPermissions(forceLaunch=true)

إبطال الأذونات

يمكن للمستخدمين إلغاء الإذن الذي منحته لهم سابقًا:

1. من خلال صفحة"حساباتي " في Google > البيانات والخصوصية > التطبيقات والخدمات التابعة لجهات خارجية. سيؤدي ذلك إلى إبطال رمز OAuth المميّز الذي تم إصداره عند منح الموافقة الأولية، وإبطال إمكانية الوصول إلى أي مثيل من التطبيق كان يستخدمه المستخدم على جميع مساحات العرض (الهواتف) والهياكل.

2. من خلال صفحة GHA > الإعدادات > التطبيقات المرتبطة سيؤدي النقر على settings في GHA إلى نقلك إلى صفحة الإعدادات. من هناك، انقر على مربّع التطبيقات المرتبطة الذي بدوره ينقلك إلى صفحة تشبه شاشة الموافقة. من هذه الصفحة، يمكن للمستخدم إزالة إمكانية الوصول إلى التطبيق. ويمكن للمستخدم استخدام هذه الصفحة نفسها لتغيير أنواع الأجهزة أو الأجهزة الحساسة المحددة التي يمكن للتطبيق الوصول إليها.

3. من خلال صفحة "التطبيقات المرتبطة" على الويب مباشرةً

إذا كان لديك عميل OAuth حالي

إذا كان لديك عميل OAuth تم إثبات ملكيته لتطبيق منشور، يمكنك استخدام عميل OAuth الحالي لاختبار واجهات برمجة تطبيقات Home.

ليس من الضروري تسجيل Developer Console لاختبار واجهات برمجة التطبيقات Home API واستخدامها. ومع ذلك، سيظلّ عليك الحصول على تسجيل Developer Console تمت الموافقة عليه لنشر تطبيقك، حتى إذا كان لديك ملف تعريف عميل OAuth تم التحقّق منه من عملية دمج أخرى.

تنطبق الاعتبارات التالية:

• هناك حد أقصى يبلغ 100 مستخدم عند استخدام ملف شخصي حالي لبروتوكول OAuth. للحصول على معلومات عن إضافة مستخدمين تجريبيين، يُرجى الرجوع إلى مقالة إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth. بغض النظر عن عملية إثبات الهوية باستخدام OAuth، هناك حد أقصى لعدد المستخدمين الذين يمكنهم منح أذونات لتطبيقك، وهو 100 مستخدم، وهو الحد الذي تفرضه Home APIs. يتم رفع هذا القيد عند إكمال عملية تسجيل Developer Console.

• Developer Console تسجيل : يجب إرساله للموافقة عندما تكون مستعدًا لتقييد منح الأذونات لأنواع الأجهزة من خلال OAuth استعدادًا لتعديل تطبيقك باستخدام واجهات برمجة تطبيقات Home.

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

Access blocked: <Project Name> has not completed the Google verification process.

أذونات OkGoogle

إنّ الأمر okGoogle هو أمر على مستوى البنية ويمكن استخدامه لأتمتة أي جهاز في البنية. ومع ذلك، قد لا يتمكّن تطبيق Home APIs من الوصول إلى كل الأجهزة. يوضّح الجدول التالي كيفية تطبيق الأذونات في مثل هذه الحالات.