تفويض حساب

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

للاطّلاع على الهياكل والأجهزة، عليك ربط حساب Google بمشروعك على Device Access باستخدام وحدة التحكّم في حدود الحساب. تسمح خدمة PCM لـ user بمنح الإذن لخدمات allow 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 هي وحدة التحكّم في حدود الحساب نفسها. يمكنك هنا منح أذونات الهيكل والجهاز. فعِّل الأذونات لمنزلك (الخطوة 1) وأي أجهزة في ذلك المنزل متوافقة مع واجهة برمجة التطبيقات SDM API (الخطوة 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.

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

تم رفض الوصول

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

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

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

لم تُثبت شركة Google ملكية هذا التطبيق.

تستخدم واجهة برمجة التطبيقات SDM API نطاقًا محظورًا، ما يعني أنّ أي تطبيقات تستخدم هذا النطاق أثناء التفويض ستكون "غير مؤكَّدة" ما لم يتم إكمال التحقّق من واجهة برمجة التطبيقات OAuth API. عند استخدام 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) لإعادة التوجيه

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

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

لتعديل الأذونات الممنوحة Device Access لمشروع أو إلغاء ربطه تمامًا، انتقِل إلى "مركز عملائي":

https://nestservices.google.com/partnerconnections

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

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

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

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

مرجع سريع

استخدِم هذا المرجع لتنفيذ خطوات تفويض 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 رمز الدخول

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

افتح وحدة طرفية ونفِّذ الأمر 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 رمز مميّز لإعادة التحميل

تكون رموز الوصول إلى واجهة برمجة التطبيقات لمجموعة أدوات SDM válida لمدة ساعة واحدة فقط، كما هو موضّح في المَعلمة 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. استخدام واجهة برمجة التطبيقات