تفويض حساب

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

لعرض المباني والأجهزة، يجب ربط حساب Google بمشروعDevice Access باستخدام PCM. يتيح PCM لـ user منح الإذن لـ developerبالوصول إلى بيانات المباني والأجهزة.

في هذا الدليل، ستكون أنت user و developer.

  1. افتح الرابط التالي في متصفّح ويب، مع استبدال ما يلي:

    1. project-id باستخدام Device Access Project معرّفك
    2. oauth2-client-id مع معرّف عميل OAuth2 من بيانات اعتماد Google Cloud
    https://nestservices.google.com/partnerconnections/project-id/auth?redirect_uri=https://www.google.com&access_type=offline&prompt=consent&client_id=oauth2-client-id&response_type=code&scope=https://www.googleapis.com/auth/sdm.service
  2. إذا سجّلت الدخول إلى Google باستخدام حسابات متعددة مؤخرًا، قد تظهر لك شاشة اختيار حساب أولية تتضمّن قائمة بحساباتك على Google. في هذه الحالة، اختَر حساب Google المرتبط بالأجهزة التي تريد منحها إذن الوصول إلى Device Access.
  3. شاشة أذونات Google Nest هي أداة إدارة الوصول إلى الأجهزة والمنزل (PCM) نفسها. يمكنك هنا منح أذونات الوصول إلى المنزل والأجهزة. فعِّل الأذونات لمنزلك (الخطوة 1) وأي أجهزة في هذا المنزل متوافقة مع واجهة برمجة التطبيقات SDM (الخطوة 2)، ثم انقر على التالي.
  4. في شاشة اختيار حساب لمواصلة استخدام اسم المشروع، حيث اسم المشروع هو اسم مشروعك على Google Cloud، اختَر حساب Google الذي تريد منحه إذن الوصول إلى واجهة برمجة التطبيقات SDM API. استخدِم حساب Google نفسه الذي استخدمته من قبل.
  5. بعد اختيار حساب، قد تظهر لك شاشة تحذيرية تفيد بأنّ Google لم تتحقّق من هذا التطبيق. في هذه الحالة، انقر على خيار خيارات متقدمة ثم على الانتقال إلى اسم المشروع (غير آمن). يمكنك الاطّلاع على لم تتحقّق Google من هذا التطبيق للحصول على مزيد من المعلومات.
  6. في شاشة منح إذن اسم المشروع، انقر على السماح لمنح المشروع إذن الوصول إلى حسابك على Google.
  7. في شاشة تأكيد اختياراتك، تأكَّد من وضع علامة في مربّع الأذونات التي تريد منحها، ثم انقر على السماح للتأكيد.

  8. من المفترض أن تتم إعادة توجيهك إلى https://www.google.com. يتم عرض رمز التفويض كالمَعلمة code في عنوان URL، ويجب أن يكون بالتنسيق التالي:

    https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service
  9. انسخ رمز التفويض.

الحصول على رمز الدخول

استخدِم رمز التفويض لاسترداد رمز دخول يمكنك استخدامه لاستدعاء واجهة برمجة التطبيقات SDM API.

  1. افتح وحدة طرفية ونفِّذ الأمر التالي curl مع استبدال:

    1. oauth2-client-id وoauth2-client-secret باستخدام معرّف العميل وسر العميل في OAuth2 من بيانات اعتماد Google Cloud
    2. authorization-code باستخدام الرمز الذي تلقّيته في الخطوة السابقة
    curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&code=authorization-code&grant_type=authorization_code&redirect_uri=https://www.google.com'

  2. تعرض خدمة Google OAuth رمزين مميزين، وهما رمز دخول ورمز مميز لإعادة التحميل.

    {
  "access_token": "access-token",
  "expires_in": 3599,
  "refresh_token": "refresh-token",
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}
     انسخ هاتَين القيمتَين. يُستخدَم رمز الدخول لاستدعاء واجهة برمجة التطبيقات SDM، ويُستخدَم الرمز المميز لإعادة التحميل للحصول على رمز دخول جديد.

إجراء مكالمة إلى قائمة أجهزة

لن تكتمل عملية التفويض إلا بعد إجراء مكالمة devices.list الأولى باستخدام رمز الدخول الجديد. تُنهي هذه المكالمة الأولية عملية منح الإذن وتفعّل الأحداث إذا سبق لك إعداد اشتراك في Pub/Sub.

استخدِم curl لإجراء هذه المكالمة لنقطة النهاية devices:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

يعرض طلب ناجح قائمة بالأجهزة المرتبطة بمشروع Device Access. ولكل جهاز قائمة فريدة خاصة به من السمات المتاحة:

{
  "devices": [
    {
      "name": "enterprises/project-id/devices/device-id",
      "type": "sdm.devices.types.device-type",
      "traits": { ... },
      "parentRelations": [
        {
          "parent": "enterprises/project-id/structures/structure-id/rooms/room-id",
          "displayName": "device-room-name"
        }
      ]
    }
  ]
}

كيفية استخدام رمز مميّز لإعادة التحميل

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

يشبه الأمر الرمز المميز للوصول، إلا أنّك تستخدم grant_type مختلفًا.

  1. افتح وحدة طرفية ونفِّذ الأمر curl التالي، مع استبدال:

    1. oauth2-client-id وoauth2-client-secret باستخدام معرّف العميل وسر العميل في OAuth2 من بيانات اعتماد Google Cloud
    2. refresh-token باستخدام الرمز الذي تلقّيته عند الحصول على رمز الدخول في البداية.
    curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&refresh_token=refresh-token&grant_type=refresh_token'

  2. يعرض Google OAuth رمز دخول جديدًا.

    {
  "access_token": "new-access-token",
  "expires_in": 3599,
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}

تحديد المشاكل وحلّها

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

انتهاء صلاحية الرمز المميز لإعادة التحميل بشكل متكرر

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

تم رفض الوصول

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

خطأ في "إدارة إمكانية وصول الشركاء إلى الأجهزة الذكية"

للحصول على مساعدة بشأن أي أخطاء تواجهها عند الوصول إلى إدارة إمكانية وصول الشركاء إلى الأجهزة الذكية (PCM)، يُرجى الاطّلاع على مرجع أخطاء إدارة إمكانية وصول الشركاء إلى الأجهزة الذكية (PCM).

لم تتحقّق Google من هذا التطبيق

تستخدم واجهة برمجة التطبيقات SDM API نطاقًا محدودًا، ما يعني أنّ أي تطبيقات تستخدم هذا النطاق أثناء التفويض سيتم تصنيفها على أنّها "لم يتم التحقّق منها" ما لم يتم إكمال عملية التحقّق من واجهة برمجة تطبيقات OAuth. عند استخدام Device Access لأغراض شخصية، لا يلزم التحقّق من واجهة برمجة التطبيقات عبر OAuth.

قد تظهر لك شاشة "لم تتحقّق Google من هذا التطبيق" أثناء عملية منح الإذن، وتظهر هذه الشاشة إذا لم يتم ضبط النطاق sdm.service على شاشة طلب الموافقة على OAuth في Google Cloud. ويمكن تجاوز هذه الشاشة من خلال النقر على الخيار خيارات متقدمة ثم النقر على الانتقال إلى اسم المشروع (غير آمن).

يُرجى الاطّلاع على شاشة التطبيق الذي لم يتم التحقّق منه لمزيد من المعلومات.

عميل غير صالح

عند محاولة الحصول على رمز دخول أو رمز مميز لإعادة التحميل، سيظهر لك الخطأ "عميل غير صالح" إذا قدّمت سر عميل غير صحيح لبروتوكول OAuth 2.0. تأكَّد من أنّ قيمة client_secret التي تستخدمها في طلبات رموز الدخول ورموز إعادة التحميل هي نفسها قيمة معرّف العميل لبروتوكول OAuth 2.0 المستخدَم، كما هو موضّح في صفحة بيانات اعتماد Google Cloud.

طلب غير صالح، نطاق مطلوب غير متوفّر

بعد منح الأذونات في PCM، قد يظهر لك الخطأ "طلب غير صالح" مع الرسالة "المَعلمة المطلوبة غير متوفّرة: النطاق". تأكَّد من أنّ قيمة scope التي تستخدمها في طلبات منح الأذونات هي نفسها القيمة التي ضبطتها لعميل OAuth 2.0، كما هو موضّح في صفحة بيانات اعتماد Google Cloud.

عدم تطابق معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه

عند إجراء عملية التفويض، قد تواجه الخطأ "عنوان URI لإعادة التوجيه غير متطابق". تأكَّد من أنّ قيمة redirect_uri التي تستخدمها في طلبات التفويض هي نفسها القيمة التي ضبطتها لعميل OAuth 2.0، كما هو موضّح في صفحة بيانات الاعتماد في Google Cloud.

تعديل أذونات الحساب

لتعديل الأذونات الممنوحة لمشروع Device Access أو فصله بالكامل، انتقِل إلى "إدارة المشاريع" (PCM):

https://nestservices.google.com/partnerconnections

تعرض هذه الصفحة جميع خدمات المطوّرين التابعة لجهات خارجية (Device Access المشاريع) المرتبطة بحسابك. اختَر Device Access المشروع الذي تريد تغييره، ثم استخدِم الشاشة التالية لتعديل الأذونات حسب الرغبة.

لإبطال أذونات معيّنة فقط لخدمة معتمَدة، فعِّل الأذونات التي تريد إبطالها وانقر على سهم الرجوع للحفظ.

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

إذا لم تعرض "إدارة الاتصالات" الخدمة المطلوبة، قد تحتاج إلى إجراء طلب قائمة الأجهزة أولاً.

مرجع سريع

استخدِم هذا المرجع لتنفيذ الخطوات اللازمة لمنحuser الإذن وربط حسابك على Google بسرعة.

لاستخدام هذا المرجع السريع، عدِّل كل متغيّر عنصر نائب في نماذج الرموز باستخدام قيم عملية الدمج المحدّدة، ثم انسخها والصقها حسب الحاجة:

‫1 PCM

افتح الرابط التالي في متصفّح ويب، مع استبدال ما يلي:

  1. project-id باستخدام Device Access Project معرّفك
  2. oauth2-client-id مع معرّف عميل OAuth2 من بيانات اعتماد Google Cloud
https://nestservices.google.com/partnerconnections/project-id/auth?redirect_uri=https://www.google.com&access_type=offline&prompt=consent&client_id=oauth2-client-id&response_type=code&scope=https://www.googleapis.com/auth/sdm.service

2 Auth Code

من المفترض أن تتم إعادة توجيهك إلى https://www.google.com. يتم عرض رمز التفويض كالمَعلمة code في عنوان URL، ويجب أن يكون بالتنسيق التالي:

https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service

‫3 رمز الدخول

استخدِم رمز التفويض لاسترداد رمز دخول يمكنك استخدامه لاستدعاء واجهة برمجة التطبيقات SDM API.

افتح وحدة طرفية ونفِّذ الأمر التالي curl مع استبدال:

  1. oauth2-client-id وoauth2-client-secret باستخدام معرّف العميل وسر العميل في OAuth2 من بيانات اعتماد Google Cloud
  2. authorization-code باستخدام الرمز الذي تلقّيته في الخطوة السابقة

تعرض خدمة Google OAuth رمزين مميزين، وهما رمز دخول ورمز مميز لإعادة التحميل.

طلب

curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&code=authorization-code&grant_type=authorization_code&redirect_uri=https://www.google.com'

الردّ

{
  "access_token": "access-token",
  "expires_in": 3599,
  "refresh_token": "refresh-token",
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}

‫4 طلب بيانات من واجهة برمجة التطبيقات

لن تكتمل عملية التفويض إلا بعد إجراء مكالمة devices.list الأولى باستخدام رمز الدخول الجديد. تُنهي هذه المكالمة الأولية عملية منح الإذن وتفعّل الأحداث إذا سبق لك إعداد اشتراك في Pub/Sub.

يجب استخدام أحد طلبات البيانات من واجهة برمجة التطبيقات المدرَجة للنطاق المحدّد لإكمال عملية منح الإذن.

sdm.service

الأجهزة

لمزيد من المعلومات، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات devices.list.

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

‫5 Refresh Token

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

افتح وحدة طرفية ونفِّذ الأمر curl التالي، مع استبدال:

  1. oauth2-client-id وoauth2-client-secret باستخدام معرّف العميل وسر العميل في OAuth2 من بيانات اعتماد Google Cloud
  2. refresh-token باستخدام الرمز الذي تلقّيته عند الحصول على رمز الدخول في البداية.

يعرض Google OAuth رمز دخول جديدًا.

طلب

curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&refresh_token=refresh-token&grant_type=refresh_token'

الردّ

{
  "access_token": "new-access-token",
  "expires_in": 3599,
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}
السابق
1- البدء
التالي
3. استخدام واجهة برمجة التطبيقات