API مجوزها

قبل از استفاده از هر یک از APIهای Home، برنامه باید مجوز دسترسی به دستگاه‌های موجود در خانه کاربر را داشته باشد که در API به آن ساختار گفته می‌شود.

APIهای Home از OAuth 2.0 برای اعطای دسترسی به دستگاه‌های موجود در ساختار استفاده می‌کنند. OAuth به کاربر اجازه می‌دهد تا بدون افشای اعتبار ورود به سیستم، به یک برنامه یا سرویس مجوز دهد. با استفاده از Permissions API، کاربر می‌تواند با استفاده از حساب Google خود، به برنامه‌های Home APIs اجازه دسترسی به دستگاه‌های موجود در خانه خود را بدهد.

استفاده از Permissions API شامل چندین مرحله در برنامه شما، Google Cloud و Google Home Developer Console است:

1. OAuth را در Google Cloud راه اندازی کنید
   1. برنامه را امضا کنید
   2. صفحه رضایت OAuth را تنظیم کنید
   3. برنامه را ثبت کنید و اعتبار ایجاد کنید
2. Permissions API را یکپارچه کنید
   1. مجوزها را بررسی کنید
   2. درخواست مجوزها
3. اعطای مجوز
   1. مجوزها را تغییر دهید
   2. لغو مجوزها

OAuth را در Google Cloud راه اندازی کنید

اگر قبلاً یک کلاینت تأیید شده OAuth دارید، می‌توانید بدون راه‌اندازی مشتری جدید از آن مشتری استفاده کنید. برای اطلاعات بیشتر، به اگر مشتری OAuth موجود دارید مراجعه کنید.

برنامه را امضا کنید

1. با اجرای برنامه در Android Studio یک کلید OAuth ایجاد کنید. وقتی برنامه‌ای را در Android Studio اجرا یا اشکال‌زدایی می‌کنید، به‌طور خودکار یک کلید OAuth ایجاد می‌کند که برای توسعه و اشکال‌زدایی در نظر گرفته شده است. برای توضیح کامل به Android Studio مراجعه کنید: بیلد اشکال زدایی خود را امضا کنید .

   دستگاه تلفن همراه خود را به دستگاه محلی خود وصل کنید. Android Studio دستگاه های متصل شما را بر اساس شماره مدل فهرست می کند. دستگاه خود را از لیست انتخاب کنید، سپس روی اجرای پروژه کلیک کنید. این برنامه نمونه برنامه را روی دستگاه تلفن همراه شما ساخته و نصب می کند.

   برای دستورالعمل‌های دقیق‌تر، به اجرای برنامه‌ها در دستگاه سخت‌افزاری در سایت Android Developers مراجعه کنید.

   اکنون برنامه در حال اجرا را متوقف کنید.

2. با دنبال کردن دستورالعمل‌های مشروح در راه‌اندازی OAuth 2.0 / Native applications / Android در سایت راهنمای Google Cloud Console، اثرانگشت SHA-1 گواهی OAuth را دریافت کنید.

صفحه رضایت OAuth را تنظیم کنید

1. در کنسول Google Cloud، به داشبورد انتخابگر پروژه بروید و پروژه ای را که می خواهید برای ایجاد اعتبار OAuth استفاده کنید، انتخاب کنید.
2. به صفحه APIs and Services بروید و روی Credentials در منوی پیمایش کلیک کنید.

3. اگر هنوز صفحه رضایت خود را برای این پروژه Google Cloud پیکربندی نکرده‌اید، دکمه پیکربندی صفحه رضایت ظاهر می‌شود. در این صورت، صفحه رضایت خود را با استفاده از روش زیر پیکربندی کنید. در غیر این صورت به بخش بعدی بروید.

   1. روی پیکربندی صفحه رضایت کلیک کنید. صفحه رضایت OAuth نمایش داده می شود.
   2. بسته به مورد استفاده خود، Internal یا External را انتخاب کنید و سپس روی ایجاد کلیک کنید. صفحه نمایش رضایت OAuth نمایش داده می شود.
   3. اطلاعات را در صفحه اطلاعات برنامه مطابق دستورالعمل های روی صفحه وارد کنید و سپس روی ذخیره کلیک کنید و ادامه دهید . صفحه Scopes نمایش داده می شود.
   4. نیازی به اضافه کردن هیچ محدوده ای ندارید، بنابراین روی ذخیره کلیک کنید و ادامه دهید . صفحه کاربران تست نمایش داده می شود.
   5. اگر می‌خواهید کاربرانی را برای دسترسی آزمایشی به برنامه خود اضافه کنید، روی افزودن کاربران کلیک کنید. صفحه افزودن کاربران نمایش داده می شود. کاربران آزمایشی این امتیاز را دارند که به برنامه شما مجوز بدهند.
   6. در فیلد خالی، یک یا چند آدرس ایمیل حساب Google اضافه کنید و سپس روی افزودن کلیک کنید.
   7. روی ذخیره کلیک کنید و ادامه دهید . پنجره Summary نمایش داده می شود.
   8. اطلاعات صفحه رضایت OAuth خود را مرور کنید و سپس روی بازگشت به داشبورد کلیک کنید.

برای جزئیات کامل به تنظیم صفحه رضایت OAuth در سایت راهنمای Google Cloud Console مراجعه کنید.

برنامه را ثبت کنید و اعتبار ایجاد کنید

برای ثبت برنامه برای OAuth 2.0 و ایجاد اعتبارنامه OAuth، دستورالعمل های ارائه شده در راه اندازی OAuth 2.0 را دنبال کنید. باید نوع برنامه را که بومی/برنامه اندروید است مشخص کنید.

با دنبال کردن دستورالعمل‌های موجود در راه‌اندازی OAuth 2.0 / برنامه‌های بومی در سایت راهنمای Google Cloud Console، اثر انگشت SHA-1 را که از امضای برنامه دریافت کردید، به مشتری OAuth که در کنسول Google Cloud تنظیم کرده‌اید، اضافه کنید.

هنگامی که دستگاه تلفن همراه خود به دستگاه محلی خود متصل است، دستگاه خود را از لیست انتخاب کنید، سپس دوباره روی اجرای پروژه کلیک کنید تا آن را اجرا کنید. برای دستورالعمل‌های دقیق‌تر، به اجرای برنامه‌ها در دستگاه سخت‌افزاری در سایت Android Developers مراجعه کنید.

Permissions API را یکپارچه کنید

کاربران برای دسترسی به دستگاه‌های موجود در یک ساختار معین باید مجوزهایی را به برنامه شما بدهند. برای شروع، مطمئن شوید که API های اولیه Home را دنبال کرده اید. نمونه homeManager از آن مرحله در تمام مثال‌های Permissions در اینجا استفاده می‌شود.

ابتدا یک ActivityResultCaller را با SDK ثبت کنید. به عنوان مثال، نحوه مدیریت برنامه نمونه به این صورت است:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

مجوزها را بررسی کنید

قبل از درخواست مجوز، توصیه می‌کنیم بررسی کنید که آیا کاربر برنامه قبلاً رضایت داده است یا خیر. برای انجام این کار، متد hasPermissions() نمونه Home را فراخوانی کنید تا یک Flow of PermissionsState به دست آورید:

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
        println("Permissions state unavailable, request permissions")
      PermissionsState.NOT_GRANTED ->
        println("OAuth permission is enabled but not granted yet, request permissions")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

اگر چک یک PermissionsState NOT_GRANTED یا PERMISSIONS_STATE_UNAVAILABLE را برمی گرداند، باید مجوزها را درخواست کنید. اگر چک یک PermissionsState of GRANTED را برگرداند اما یک فراخوان بعدی به structures() هیچ ساختاری را برگرداند، در این صورت کاربر از طریق صفحه تنظیمات Google Home app (GHA) دسترسی به برنامه را لغو کرده است و شما باید مجوزها را درخواست کنید. در غیر این صورت، کاربر از قبل باید دسترسی داشته باشد.

درخواست مجوزها

برای دسترسی به ساختارها و دستگاه‌ها در یک ساختار معین، باید مجوز به برنامه شما داده شود.

اگر کاربر قبلاً مجوزها را اعطا نکرده است، از متد requestPermissions() نمونه Home برای راه‌اندازی Permissions UI و پردازش نتیجه استفاده کنید:

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

برای اینکه رابط کاربری مجوزها به درستی راه اندازی شود، باید قبلاً OAuth را برای برنامه خود تنظیم کرده باشید.

اعطای مجوز

اکنون باید بتوانید برنامه خود را اجرا کنید و از یک کاربر مجوز اعطا کنید. بسته به اینکه آیا برنامه خود را در Developer Console ثبت کرده اید، نوع کاربرانی که می توانند مجوز اعطا کنند، و انواع دستگاه هایی که برای اعطای مجوز در دسترس هستند، متفاوت است.

ثبت نام Developer Console برای انتشار یک برنامه با استفاده از Home API ضروری است. آزمایش و استفاده از APIهای Home الزامی نیست. برای دسترسی به ویژگی ثبت کنسول، با Technical Account Manager (TAM) خود تماس بگیرید.

اگر برنامه‌ای در Developer Console ثبت نشده باشد ، در حالت تأیید نشده قرار می‌گیرد. این برای آزمایش استفاده از APIهای Home توصیه می شود:

• فقط کاربرانی که به عنوان کاربران آزمایشی در کنسول OAuth ثبت نام کرده اند می توانند مجوزهای برنامه را اعطا کنند. محدودیت 100 کاربر آزمایشی برای یک برنامه تایید نشده وجود دارد.

• یک برنامه تأیید نشده به دستگاه‌هایی با هر نوع دستگاهی که توسط OAuth برای APIهای Home پشتیبانی می‌شوند (فهرست انواع دستگاه‌ها در Developer Console ) دسترسی خواهد داشت. تمام دستگاه ها در یک ساختار اعطا خواهند شد.

اگر برنامه ای در Developer Console ثبت شده باشد و برای دسترسی به یک یا چند نوع دستگاه تأیید شده است، و تأیید نام تجاری برای OAuth تکمیل شده است ، در وضعیت تأیید شده خواهد بود. این حالت برای راه اندازی یک برنامه برای تولید لازم است:

• محدودیت های آزمایشی کاربر دیگر اعمال نمی شود. هر کاربری می‌تواند به برنامه اجازه دهد.
• کاربر فقط می‌تواند به انواع دستگاه‌هایی مجوز دهد که در Developer Console تأیید شده‌اند.

اکنون که OAuth راه اندازی شده است، فراخوانی برنامه به requestPermissions() دیالوگ های زیر را راه اندازی می کند:

1. از کاربر خواسته می شود تا حساب Google مورد نظر خود را برای استفاده انتخاب کند.
2. از کاربر خواسته می‌شود ساختاری را که می‌خواهد به برنامه اجازه دسترسی دهد، انتخاب کند.
   1. برای یک برنامه تأیید نشده، همه انواع دستگاه های پشتیبانی شده توسط Home API در دسترس برنامه هستند.
   2. برای یک برنامه تأیید شده، کاربر می‌تواند فقط به انواع دستگاه‌هایی که در Developer Console تأیید شده‌اند مجوز بدهد.
   3. برای انواع دستگاه های حساسی که برنامه به مدیریت آنها دسترسی دارد، کاربر می تواند دسترسی را بر اساس هر دستگاه محدود کند. به عنوان مثال، اگر کاربری سه قفل داشته باشد، می تواند تنها به یکی از آن قفل ها دسترسی داشته باشد.

پس از اعطای مجوز، برنامه می‌تواند از APIهای Home برای خواندن وضعیت و کنترل دستگاه‌های موجود در ساختار استفاده کند. اگر کاربر برای یک نوع دستگاه خاص یا دستگاه حساس به برنامه مجوز اعطا نکند، برنامه نمی‌تواند از APIهای Home برای دسترسی، کنترل یا خودکارسازی آن استفاده کند.

مجوزها را تغییر دهید

برای اعطای مجوز دسترسی به دستگاه‌هایی در ساختاری دیگر، انتخابگر حساب می‌تواند راه‌اندازی شود تا به کاربر اجازه دهد حساب و ساختار Google را برای تغییر به آن انتخاب کند. در طول این فرآیند، حتی اگر قبلاً رضایت داده شده باشد، دوباره صفحه رضایت به کاربر نمایش داده می‌شود.

این را می توان با فراخوانی requestPermissions() با پرچم forceLaunch روی true انجام داد:

homeManager.requestPermissions(forceLaunch=true)

لغو مجوزها

کاربران می توانند دسترسی قبلاً اعطا شده را لغو کنند:

1. از طریق صفحه Google My Accounts > داده‌ها و حریم خصوصی > برنامه‌ها و سرویس‌های شخص ثالث . با این کار، نشانه OAuth که هنگام اعطای رضایت اولیه صادر شده بود، لغو می‌شود و دسترسی به هر نمونه از برنامه‌ای که کاربر در تمام سطوح (تلفن‌ها) و ساختارها استفاده می‌کرد، لغو می‌شود.

2. از طریق صفحه GHA > تنظیمات > برنامه های مرتبط . با کلیک بر روی settings در GHA به صفحه تنظیمات هدایت می شوید. از آنجا، روی کاشی برنامه های پیوندی کلیک کنید که شما را به صفحه ای می برد که شبیه به صفحه رضایت است. از این صفحه کاربر می تواند دسترسی به برنامه را حذف کند. کاربر می‌تواند از همین صفحه برای تغییر نوع دستگاه یا دستگاه‌های حساس خاص برای برنامه استفاده کند.

3. از طریق صفحه برنامه های پیوندی مستقیماً در وب.

اگر مشتری OAuth موجود دارید

اگر از قبل یک سرویس گیرنده OAuth تأیید شده برای یک برنامه منتشر شده دارید، می توانید از سرویس گیرنده OAuth موجود خود برای آزمایش API های Home استفاده کنید.

ثبت نام Developer Console برای آزمایش و استفاده از Home APIها لازم نیست. با این حال، حتی اگر یک سرویس گیرنده OAuth تأیید شده از ادغام دیگری داشته باشید، همچنان برای انتشار برنامه خود به ثبت نام Developer Console تأیید شده نیاز دارید.

ملاحظات زیر اعمال می شود:

• هنگام استفاده از یک سرویس گیرنده OAuth موجود، یک محدودیت 100 کاربر وجود دارد. برای اطلاعات در مورد افزودن کاربران آزمایشی، به تنظیم صفحه رضایت OAuth مراجعه کنید. مستقل از تأیید OAuth، محدودیت 100 کاربر توسط Home API تحمیل شده است که می توانند به برنامه شما مجوز دهند. این محدودیت با تکمیل ثبت نام Developer Console برداشته می شود.

• ثبت نام Developer Console باید زمانی برای تأیید ارسال شود که برای آماده‌سازی برای به‌روزرسانی برنامه خود با APIهای Home آماده باشید تا کمک هزینه‌های نوع دستگاه را از طریق OAuth محدود کنید.

برای برنامه‌های Google Cloud که هنوز در انتظار تأیید OAuth هستند، کاربران نمی‌توانند جریان OAuth را تکمیل کنند تا اینکه تأیید کامل شود. تلاش برای اعطای مجوز با خطای زیر ناموفق خواهد بود:

Access blocked: <Project Name> has not completed the Google verification process.

مجوزهای OkGoogle

دستور okGoogle یک دستور در سطح ساختار است و می تواند برای خودکار کردن هر دستگاهی در ساختار استفاده شود. با این حال، برنامه Home APIs ممکن است به همه دستگاه‌ها دسترسی نداشته باشد. جدول زیر نحوه اجرای مجوزها در چنین مواردی را توضیح می دهد.