مجوز یک حساب

با ایجاد پروژه‌های Google Cloud و Device Access، می‌توانید یک حساب Google را با یک دستگاه Google Nest پشتیبانی‌شده برای SDM API تأیید کنید.

حساب خود را پیوند دهید

برای مشاهده ساختارها و دستگاه‌ها، باید یک حساب گوگل به حساب خود متصل کنید.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. اگر اخیراً با چندین حساب کاربری وارد گوگل شده‌اید، ممکن است صفحه اولیه «انتخاب حساب کاربری» با لیستی از حساب‌های کاربری گوگل شما نمایش داده شود. در این صورت، حساب کاربری گوگل مرتبط با دستگاه (یا دستگاه‌هایی) را که می‌خواهید برای آنها مجوز صادر کنید، انتخاب کنید. Device Access.
3. صفحه مجوزهای Google Nest خود PCM است. در اینجا می‌توانید مجوزهای ساختار و دستگاه را اعطا کنید. مجوزهای مربوط به خانه خود (مرحله 1) و هر دستگاهی در آن خانه که توسط SDM API پشتیبانی می‌شود (مرحله 2) را فعال کنید، سپس روی Next کلیک کنید.
4. در صفحه «انتخاب یک حساب کاربری برای ادامه به نام پروژه» ، که در آن «نام پروژه » نام پروژه Google Cloud شماست، حساب گوگلی را که می‌خواهید برای SDM API مجاز کنید، انتخاب کنید. از همان حساب گوگل قبلی استفاده کنید.
5. پس از انتخاب حساب کاربری، ممکن است با صفحه هشداری مواجه شوید که می‌گوید گوگل این برنامه را تأیید نکرده است . در این صورت، برای ادامه، روی گزینه پیشرفته کلیک کنید و سپس روی «برو به نام پروژه (ناامن)» کلیک کنید. برای اطلاعات بیشتر به «گوگل این برنامه را تأیید نکرده است» مراجعه کنید.
6. در صفحه مجوز «نام پروژه اعطا شده» ، روی «مجاز» کلیک کنید تا به پروژه اجازه دسترسی به حساب گوگل شما داده شود.
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 Client ID و Client Secret از اعتبارنامه‌های 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"
        }
      ]
    }
  ]
}

نحوه استفاده از توکن رفرش

همانطور که در پارامتر expires_in برگردانده شده توسط Google OAuth ذکر شده است، توکن‌های دسترسی برای SDM API فقط به مدت ۱ ساعت معتبر هستند. اگر توکن دسترسی شما منقضی شد، از توکن refresh برای دریافت توکن جدید استفاده کنید.

این دستور مشابه دستور access token است، با این تفاوت که از grant_type متفاوتی استفاده می‌کنید.

1. یک ترمینال باز کنید و دستور curl زیر را اجرا کنید، و جایگزین کنید:

   1. oauth2-client-id و oauth2-client-secret به همراه OAuth2 Client ID و Client Secret از اعتبارنامه‌های Google Cloud شما
   2. refresh-token با کدی که هنگام دریافت اولیه‌ی access 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 برای دسترسی به APIهای گوگل» مراجعه کنید.

توکن به‌روزرسانی مدام منقضی می‌شود

اگر شناسه کلاینت تأیید نشود، توکن‌های Refresh می‌توانند پس از ۷ روز از کار بیفتند. این یکی از دلایل احتمالی است. انقضای ۷ روزه توکن ربطی به تأییدیه‌های تجاری یا Sandbox ندارد. یک سرویس یا حساب کاربری برای افزایش طول عمر توکن، باید شناسه کلاینت OAuth 2.0 خود را تأیید و وارد چرخه تولید کند. برای اطلاعات بیشتر به بخش انقضای توکن Refresh مراجعه کنید.

دسترسی رد شد

اگر صفحه رضایت OAuth خود را در Google Cloud تنظیم کرده باشید و نوع کاربر External باشد، در صورت تلاش برای اتصال حساب کاربری با یک حساب گوگل که به عنوان کاربر آزمایشی برای برنامه شما فهرست نشده است، خطای "دسترسی ممنوع" دریافت خواهید کرد. حتماً حساب گوگل را به بخش کاربران آزمایشی در صفحه رضایت OAuth خود اضافه کنید.

خطای مدیر ارتباطات شرکا (PCM)

برای راهنمایی در مورد هرگونه خطایی که هنگام دسترسی به PCM با آن مواجه می‌شوید، به مرجع خطای مدیر ارتباطات شرکا (PCM) مراجعه کنید.

گوگل این برنامه را تأیید نکرده است

رابط برنامه‌نویسی کاربردی SDM از یک دامنه محدود استفاده می‌کند، به این معنی که هر برنامه‌ای که در طول فرآیند احراز هویت از این دامنه استفاده کند، «تأیید نشده» خواهد بود، مگر اینکه تأیید رابط برنامه‌نویسی کاربردی OAuth تکمیل شود. هنگام استفاده Device Access برای استفاده شخصی، تأیید API OAuth لازم نیست.

ممکن است در طول فرآیند مجوزدهی، صفحه‌ای با عنوان «Google has not verified this app» مشاهده کنید که اگر محدوده sdm.service در صفحه رضایت OAuth شما در Google Cloud پیکربندی نشده باشد، ظاهر می‌شود. این صفحه را می‌توان با کلیک روی گزینه Advanced و سپس کلیک روی Go to Project Name (unsafe) دور زد.

برای اطلاعات بیشتر به صفحه برنامه تأیید نشده مراجعه کنید.

کلاینت نامعتبر

هنگام تلاش برای دریافت توکن دسترسی یا به‌روزرسانی، در صورت ارائه رمز کلاینت OAuth 2.0 نادرست، خطای "سرویس‌گیرنده نامعتبر" دریافت خواهید کرد. مطمئن شوید که مقدار client_secret که در فراخوانی‌های توکن دسترسی و به‌روزرسانی استفاده می‌کنید، همان مقداری است که برای شناسه کلاینت OAuth 2.0 مورد استفاده قرار می‌گیرد، همانطور که در صفحه اعتبارنامه‌های Google Cloud شما موجود است.

درخواست نامعتبر، محدوده مورد نیاز وجود ندارد

پس از اعطای مجوزها در PCM، ممکن است با خطای «درخواست نامعتبر» با عنوان «پارامتر مورد نیاز موجود نیست: دامنه» مواجه شوید. مطمئن شوید که مقدار scope که در فراخوانی‌های مجوز استفاده می‌کنید، همان مقداری است که برای OAuth 2.0 Client تنظیم کرده‌اید، همانطور که در صفحه اعتبارنامه‌های Google Cloud شما موجود است.

عدم تطابق uri در ریدایرکت

هنگام احراز هویت، ممکن است با خطای "عدم تطابق uri تغییر مسیر" مواجه شوید. مطمئن شوید که مقدار redirect_uri که در فراخوانی‌های احراز هویت استفاده می‌کنید، همان مقداری است که برای کلاینت OAuth 2.0 تنظیم کرده‌اید، همانطور که در صفحه اعتبارنامه‌های Google Cloud شما موجود است.

تغییر مجوزهای حساب کاربری

برای تغییر مجوزهای اعطا شده به یک Device Access پروژه، یا آن را به طور کامل قطع کنید، به PCM بروید:

https://nestservices.google.com/partnerconnections

این صفحه تمام سرویس‌های توسعه‌دهندگان شخص ثالث (Device Access پروژه‌ها) به حساب شما متصل شده‌اند. انتخاب کنید Device Access پروژه‌ای که می‌خواهید تغییر دهید. از صفحه بعدی برای تغییر مجوزها به دلخواه استفاده کنید.

برای لغو مجوزهای خاص برای یک سرویس مجاز ، مجوزهایی را که می‌خواهید لغو کنید، تغییر وضعیت دهید و برای ذخیره، روی پیکان برگشت کلیک کنید.

برای قطع کامل ارتباط یک سرویس مجاز ، روی «لغو ارتباط حساب گوگل» کلیک کنید تا تمام مجوزها و نشانه‌های دسترسی که پروژه برای حساب کاربری اعطا کرده است، لغو شود.

اگر PCM سرویس مورد نظر را نشان نمی‌دهد، ممکن است ابتدا لازم باشد فهرست دستگاه‌ها را فراخوانی کنید .

مرجع سریع

از این مرجع برای پیاده‌سازی سریع مراحل تأیید اعتبار استفاده کنیدuser و حساب گوگل آنها را لینک کنید.

برای استفاده از این مرجع سریع، هر متغیر placeholder را در نمونه‌های کد با مقادیر مربوط به ادغام خاص خود ویرایش کنید و در صورت نیاز کپی و جایگذاری کنید:

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

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

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"
}

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-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'

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