تفويض حساب

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

لعرض المباني والأجهزة، يجب ربط حساب Google بDevice Access مشروعك باستخدام "مركز إدارة الشركاء". تتيح 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 API، ويُستخدَم رمز إعادة التحميل للحصول على رمز دخول جديد.

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

لن تكتمل عملية التفويض إلا بعد إجراء مكالمتك الأولى باستخدام رمز الدخول الجديد 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 التي يعرضها بروتوكول Google OAuth. إذا انتهت صلاحية رمز الدخول، استخدِم رمز إعادة التحميل للحصول على رمز جديد.

يشبه الأمر الرمز المميز للوصول، إلا أنّك تستخدم 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 أيام بموافقات Commercial أو Sandbox. يجب الموافقة على معرّف عميل OAuth 2.0 لحساب الخدمة أو حساب المستخدم وطرحه في مرحلة الإنتاج للحصول على فترات صلاحية أطول للرموز المميزة. يمكنك الاطّلاع على إعادة تحميل انتهاء صلاحية الرمز المميّز لمزيد من المعلومات.

تم رفض الوصول

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

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

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

لم تُثبت شركة 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) الخاص بإعادة التوجيه

عند إجراء عملية التفويض، قد تواجه الخطأ "Redirect uri mismatch" (عنوان 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 رمز المصادقة

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

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

‫3 Access Token

استخدِم رمز التفويض لاسترداد رمز دخول يمكنك استخدامه لاستدعاء واجهة برمجة التطبيقات 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 التي يعرضها بروتوكول Google OAuth. إذا انتهت صلاحية رمز الدخول، استخدِم رمز إعادة التحميل للحصول على رمز جديد.

افتح وحدة طرفية ونفِّذ الأمر 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. استخدام واجهة برمجة التطبيقات