تفويض حساب

من خلال مشاريع Google Cloud وDevice Access التي تم إنشاؤها، يمكنك منح الإذن لحساب Google باستخدام جهاز Google Nest متوافق مع SDM API.

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

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

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

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

تم رفض الوصول

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

خطأ في مدير اتصالات الشركاء (PCM)

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

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

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

إذا لم تعرض تقنية 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 الأولى باستخدام رمز الدخول الجديد. تنتهي هذه المكالمة الأولية من عملية منح الإذن وتفعِّل الأحداث إذا سبق لك إعداد اشتراك في النشر/الاشتراك.

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

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 صالحة لمدة ساعة واحدة فقط، كما هو موضّح في المَعلمة 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. استخدام واجهة برمجة التطبيقات