ממשק API להרשאות

לפני שמשתמשים באחד מממשקי ה-API של Home, צריכה להיות לאפליקציה הרשאה לגשת למכשירים בבית של המשתמש, שנקראים ב-API המבנה.

ממשקי Home API משתמשים ב-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: חתימה על build לניפוי באגים.

   מחברים את המכשיר הנייד למחשב המקומי. Android Studio תציג את המכשירים המקושרים לפי מספר הדגם. בוחרים את המכשיר מהרשימה ולוחצים על הפעלת הפרויקט. הפקודה הזו יוצרת ומתקינה את אפליקציית הדוגמה במכשיר הנייד.

   הוראות מפורטות יותר זמינות במאמר הרצת אפליקציות במכשיר חומרה באתר למפתחי Android.

   עכשיו עוצרים את האפליקציה שפועלת.

2. כדי לקבל את טביעת האצבע של SHA-1 של אישור ה-OAuth, פועלים לפי ההוראות שמפורטות במאמר הגדרת OAuth 2.0 / אפליקציות מקוריות / Android באתר העזרה של מסוף Google Cloud.

הגדרת מסך ההסכמה ל-OAuth

1. במסוף Google Cloud, עוברים אל לוח הבקרה לבחירת פרויקט ובוחרים את הפרויקט שבו רוצים להשתמש כדי ליצור פרטי כניסה ל-OAuth.
2. עוברים לדף APIs and Services ולוחצים על Credentials בתפריט הניווט.

3. אם עדיין לא הגדרתם את מסך ההסכמה לפרויקט הזה ב-Google Cloud, יופיע הלחצן Configure consent screen (הגדרת מסך ההסכמה). במקרה כזה, צריך להגדיר את מסך ההסכמה לפי התהליך הבא. אחרת, עוברים לקטע הבא.

   1. לוחצים על Configure consent screen (הגדרת מסך ההסכמה). הדף מסך ההסכמה ל-OAuth יוצג.
   2. בהתאם לתרחיש לדוגמה, בוחרים באפשרות פנימי או חיצוני ולוחצים על Create. החלונית מסך ההסכמה של OAuth תוצג.
   3. מזינים את הפרטים בדף פרטי האפליקציה לפי ההוראות במסך, ולוחצים על שמירה והמשך. החלונית Scopes תוצג.
   4. אין צורך להוסיף היקפי גישה, לכן לוחצים על Save and continue (שמירה והמשך). החלונית משתמשי בדיקה תוצג.
   5. אם רוצים להוסיף משתמשים כדי לבדוק את הגישה לאפליקציה, לוחצים על הוספת משתמשים. החלונית Add users תופיע. למשתמשים לבדיקה יש הרשאה להעניק הרשאות באפליקציה.
   6. בשדה הריק, מוסיפים כתובת אימייל אחת או יותר של חשבון Google ולוחצים על Add.
   7. לוחצים על שמירה והמשך. החלונית Summary תופיע.
   8. בודקים את המידע במסך ההסכמה ל-OAuth ולוחצים על Back to dashboard.

פרטים מלאים זמינים במאמר הגדרת מסך הסכמה ל-OAuth באתר העזרה של מסוף Google Cloud.

רישום האפליקציה ויצירת פרטי כניסה

כדי לרשום את האפליקציה ל-OAuth 2.0 וליצור פרטי כניסה ל-OAuth, פועלים לפי ההוראות שמפורטות במאמר הגדרת OAuth 2.0. צריך לציין את סוג האפליקציה, שהוא אפליקציה מקורית/ל-Android.

מוסיפים את טביעת האצבע מסוג SHA-1 שקיבלתם מחתימה על האפליקציה ללקוח OAuth שהגדרתם במסוף Google Cloud. לשם כך, פועלים לפי ההוראות במאמר הגדרת OAuth 2.0 / אפליקציות מקוריות באתר העזרה של מסוף Google Cloud.

כשהמכשיר הנייד מחובר למחשב המקומי, בוחרים את המכשיר מהרשימה ולוחצים שוב על הפעלת הפרויקט כדי להפעיל אותו. להוראות מפורטות יותר, אפשר לעיין במאמר הרצת אפליקציות במכשיר חומרה באתר למפתחי Android.

שילוב של Permissions API

המשתמשים צריכים להעניק לאפליקציה הרשאות כדי לגשת למכשירים במסגרת מבנה נתון. לפני שמתחילים, חשוב לוודא שפעלתם לפי ההוראות להפעלת ממשקי ה-API של Home. המכונה homeManager מהשלב הזה משמשת בכל הדוגמאות של ההרשאות שמפורטות כאן.

קודם כול צריך לרשום ActivityResultCaller ב-SDK. לדוגמה, כך האפליקציה לדוגמה מטפלת בכך:

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

בדיקת ההרשאות

לפני ששולחים בקשות להרשאות, מומלץ לבדוק אם משתמש האפליקציה כבר הביע הסכמה. כדי לעשות זאת, צריך לבצע קריאה ל-method‏ hasPermissions() של מופע הבית כדי לקבל Flow של ערכים של 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 של GRANTED אבל קריאה חוזרת ל-structures() לא מחזירה מבנים, סימן שהמשתמש ביטל את הגישה לאפליקציה דרך דף ההגדרות של Google Home app (GHA), וצריך לבקש הרשאות. אחרת, למשתמש כבר אמורה להיות גישה.

בקשת הרשאות

צריך להעניק לאפליקציה הרשאה כדי שתהיה לה גישה למבנים ולמכשירים במבנה נתון.

אם המשתמש עדיין לא העניק הרשאות, משתמשים ב-method‏ requestPermissions() של המכונה הראשית כדי להפעיל את ממשק המשתמש של ההרשאות ולעבד את התוצאה:

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.

כדי לפרסם אפליקציה באמצעות ממשקי ה-API של Home, נדרש רישום Developer Console. אין צורך לבדוק את ממשקי ה-API של Home ולהשתמש בהם. כדי לקבל גישה לתכונה של רישום במסוף, צריך לפנות לTechnical Account Manager (TAM) של Google.

אם אפליקציה לא רשומה ב-Developer Console, היא תהיה במצב לא מאומת. מומלץ להשתמש באפשרות הזו כדי לבדוק את השימוש בממשקי ה-API של Home:

• רק משתמשים שנרשמו כמשתמשי בדיקה במסוף OAuth יכולים להקצות הרשאות לאפליקציה. יש מגבלה של 100 משתמשי בדיקה לאפליקציה לא מאומתת.

• לאפליקציה לא מאומתת תהיה גישה למכשירים מכל סוגי המכשירים שנתמכים על ידי OAuth ל-Home APIs (רשימת סוגי המכשירים מופיעה ב-Developer Console). כל המכשירים במבנה יקבלו גישה.

אם אפליקציה רשומה ב-Developer Console וניתנה לה גישה לסוג מכשיר אחד או יותר, והושלם אימות המותג ל-OAuth, היא תהיה במצב מאומת. המצב הזה נדרש כדי להשיק אפליקציה בסביבת הייצור:

• מגבלות על משתמשי בדיקה לא חלות יותר. כל משתמש יכול להעניק הרשאה לאפליקציה.
• המשתמש יכול להעניק הרשאה רק לסוגי המכשירים שאושרו ב-Developer Console.

עכשיו, אחרי שהגדרתם את OAuth, הקריאה של האפליקציה ל-requestPermissions() מפעילה את תיבת הדו-שיח הבאה:

1. המשתמש מתבקש לבחור את חשבון Google שבו הוא רוצה להשתמש.
2. המשתמש מתבקש לבחור את המבנה שאליו הוא רוצה להעניק לאפליקציה גישה.
   1. באפליקציה לא מאומתת, כל סוגי המכשירים שנתמכים ב-Home APIs זמינים לאפליקציה.
   2. באפליקציה מאומתת, המשתמש יכול להעניק הרשאה רק לסוגי המכשירים שאושרו ב-Developer Console.
   3. לגבי סוגי מכשירים רגישים שיש לאפליקציה גישה לניהול שלהם, המשתמש יכול להגביל את הגישה לפי מכשיר. לדוגמה, אם למשתמש יש שלוש נעילות, הוא יכול להעניק גישה רק לאחת מהן.

אחרי שמאשרים את ההרשאה, האפליקציה יכולה להשתמש ב-Home APIs כדי לקרוא את המצב של המכשירים במבנה ולשלוט בהם. אם המשתמש לא נותן לאפליקציה הרשאה לגשת למכשיר מסוים או למכשיר רגיש, האפליקציה לא תוכל להשתמש בממשקי ה-API של Home כדי לגשת למכשיר, לשלוט בו או לבצע אוטומציה שלו.

שינוי ההרשאות

כדי להעניק הרשאה לגשת למכשירים במבנה אחר, אפשר להפעיל את בורר החשבונות כדי לאפשר למשתמש לבחור את חשבון Google ואת המבנה שאליו הוא רוצה לעבור. במהלך התהליך הזה, המסך של בקשת ההסכמה יוצג שוב למשתמש, גם אם הוא הביע הסכמה בעבר.

כדי לעשות זאת, צריך לבצע קריאה חוזרת ל-requestPermissions() עם הדגל forceLaunch מוגדר ל-true:

homeManager.requestPermissions(forceLaunch=true)

ביטול הרשאות

משתמשים יכולים לבטל גישה שניתנה להם בעבר:

1. דרך הדף 'החשבונות שלי ב-Google' > נתונים ופרטיות > אפליקציות ושירותים של צד שלישי. הפעולה הזו תבטל את אסימון ה-OAuth שהונפק כשהתקבלה ההסכמה הראשונית, ותבטל את הגישה לכל מופע של האפליקציה שהמשתמש השתמש בו בכל המכשירים (טלפונים) והמבנים.

2. בדף GHA > הגדרות > אפליקציות מקושרות. לחיצה על settings ב-GHA תעביר אתכם לדף הגדרות. לאחר מכן, לוחצים על המשבצת אפליקציות מקושרות כדי לעבור לדף שנראה דומה למסך ההסכמה. בדף הזה המשתמש יכול להסיר את הגישה לאפליקציה. הוא יכול להשתמש באותו דף כדי לשנות את סוגי המכשירים או מכשירים רגישים ספציפיים שיש להם גישה לאפליקציה.

3. דרך הדף 'אפליקציות מקושרות' ישירות באינטרנט.

אם יש לכם לקוח OAuth קיים

אם כבר יש לכם לקוח OAuth מאומת לאפליקציה שפורסמה, תוכלו להשתמש בלקוח OAuth הקיים כדי לבדוק את Home APIs.

לא צריך להירשם ל-Developer Console כדי לבדוק את ממשקי ה-API של Home ולהשתמש בהם. עם זאת, עדיין תצטרכו רישום מאושר ב-Developer Console כדי לפרסם את האפליקציה, גם אם יש לכם לקוח OAuth מאומת משילוב אחר.

יש להביא בחשבון את השיקולים הבאים:

• כשמשתמשים בלקוח OAuth קיים, יש מגבלה של 100 משתמשים. מידע נוסף על הוספת משתמשים לצורך בדיקה זמין במאמר הגדרת מסך ההסכמה ל-OAuth. ללא קשר לאימות OAuth, יש מגבלה של 100 משתמשים שיכולים להעניק הרשאות לאפליקציה שלכם, והיא מוגדרת על ידי ממשקי ה-API של Home. ההגבלה הזו תוסר לאחר השלמת הרישום ב-Developer Console.

• Developer Console רישום צריך לשלוח לאישור כשאתם מוכנים להגביל את ההרשאות לפי סוג המכשיר באמצעות OAuth, לקראת עדכון האפליקציה באמצעות ממשקי ה-API של Home.

באפליקציות Google Cloud שעדיין בהמתנה לאימות OAuth, המשתמשים לא יכולים להשלים את תהליך OAuth עד שהאימות יושלם. ניסיונות להקצות הרשאות ייכשלו עם השגיאה הבאה:

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

הרשאות OkGoogle

הפקודה okGoogle היא פקודת ברמת המבנה, וניתן להשתמש בה כדי להפוך כל מכשיר במבנה לאוטומטי. עם זאת, יכול להיות שאפליקציה עם Home APIs לא תהיה לה גישה לכל המכשירים. בטבלה הבאה מוסבר איך מתבצעת אכיפת ההרשאות במקרים כאלה.