API สิทธิ์

ก่อนใช้ Home API แอปต้องมีสิทธิ์เข้าถึงอุปกรณ์ในบ้านของผู้ใช้ ซึ่งใน API เรียกว่าโครงสร้าง

Home API ใช้ OAuth 2.0 เพื่อมอบสิทธิ์เข้าถึงอุปกรณ์ในโครงสร้างพื้นฐาน OAuth ช่วยให้ผู้ใช้สามารถให้สิทธิ์แก่แอปหรือบริการได้โดยไม่ต้องเปิดเผยข้อมูลเข้าสู่ระบบ Permissions API ช่วยให้ผู้ใช้สามารถให้สิทธิ์แอป Home API เข้าถึงอุปกรณ์ในบ้านได้โดยใช้บัญชี Google

การใช้ 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. สร้างคีย์ OAuth โดยเรียกใช้แอปใน Android Studio เมื่อคุณเรียกใช้หรือแก้ไขข้อบกพร่องของแอปใน Android Studio ระบบจะสร้างคีย์ OAuth ขึ้นโดยอัตโนมัติเพื่อการพัฒนาและการแก้ไขข้อบกพร่อง ดูคำอธิบายทั้งหมดได้ที่ Android Studio: ลงชื่อบิลด์แก้ไขข้อบกพร่อง

    เชื่อมต่ออุปกรณ์เคลื่อนที่กับเครื่องคอมพิวเตอร์ Android Studio จะแสดงรายการอุปกรณ์ที่เชื่อมต่อตามหมายเลขรุ่น เลือกอุปกรณ์จากรายการ แล้วคลิกเรียกใช้โปรเจ็กต์ ซึ่งจะสร้างและติดตั้งแอปตัวอย่างในอุปกรณ์เคลื่อนที่

    ดูวิธีการโดยละเอียดได้ที่เรียกใช้แอปในอุปกรณ์ฮาร์ดแวร์ในเว็บไซต์ของนักพัฒนาแอป Android

    จากนั้นให้หยุดแอปที่ทำงานอยู่

  2. รับลายนิ้วมือ SHA-1 ของใบรับรอง OAuth โดยทําตามวิธีการที่ระบุไว้อย่างละเอียดในการตั้งค่า OAuth 2.0 / แอปพลิเคชันเนทีฟ / Android ในเว็บไซต์ความช่วยเหลือของ Google Cloud Console

  1. ในคอนโซล Google Cloud ให้ไปที่แดชบอร์ดเครื่องมือเลือกโปรเจ็กต์ แล้วเลือกโปรเจ็กต์ที่ต้องการใช้สร้างข้อมูลเข้าสู่ระบบ OAuth
  2. ไปที่หน้า API และบริการ แล้วคลิกข้อมูลเข้าสู่ระบบในเมนูการนำทาง
  3. หากยังไม่ได้กําหนดค่าหน้าจอขอความยินยอมสําหรับโปรเจ็กต์ Google Cloud นี้ ปุ่มกําหนดค่าหน้าจอขอความยินยอมจะปรากฏขึ้น ในกรณีนี้ ให้กําหนดค่าหน้าจอความยินยอมโดยใช้ขั้นตอนต่อไปนี้ ไม่เช่นนั้น ให้ไปที่ส่วนถัดไป

    1. คลิกกําหนดค่าหน้าจอความยินยอม หน้าหน้าจอขอความยินยอม OAuth จะปรากฏขึ้น
    2. เลือกภายในหรือภายนอก โดยขึ้นอยู่กับกรณีการใช้งาน แล้วคลิกสร้าง แผงหน้าจอขอความยินยอม OAuth จะปรากฏขึ้น
    3. ป้อนข้อมูลในหน้าข้อมูลแอปตามวิธีการบนหน้าจอ แล้วคลิกบันทึกและดำเนินการต่อ แผงขอบเขตจะปรากฏขึ้น
    4. คุณไม่จําเป็นต้องเพิ่มขอบเขตใดๆ ให้คลิกบันทึกและต่อไป แผงผู้ใช้ทดสอบจะปรากฏขึ้น
    5. หากต้องการเพิ่มผู้ใช้เพื่อทดสอบสิทธิ์เข้าถึงแอป ให้คลิกเพิ่มผู้ใช้ แผงเพิ่มผู้ใช้จะปรากฏขึ้น ผู้ใช้ทดสอบมีสิทธิ์ให้สิทธิ์ในแอป
    6. ในช่องว่าง ให้เพิ่มอีเมลของบัญชี Google อย่างน้อย 1 รายการ แล้วคลิกเพิ่ม
    7. คลิกบันทึกและต่อไป บานหน้าต่างสรุปจะปรากฏขึ้น
    8. ตรวจสอบข้อมูลหน้าจอขอความยินยอม OAuth แล้วคลิกกลับไปยังแดชบอร์ด

ดูรายละเอียดทั้งหมดได้ที่การตั้งค่าหน้าจอขอความยินยอม OAuth ในเว็บไซต์ความช่วยเหลือของ Google Cloud Console

ลงทะเบียนแอปและสร้างข้อมูลเข้าสู่ระบบ

หากต้องการลงทะเบียนแอปสำหรับ OAuth 2.0 และสร้างข้อมูลเข้าสู่ระบบ OAuth ให้ทำตามวิธีการที่ระบุไว้ในการตั้งค่า OAuth 2.0 คุณจะต้องระบุประเภทแอป ซึ่งก็คือแอปเนทีฟ/Android

เพิ่มลายนิ้วมือ SHA-1 ที่คุณได้รับจากการรับรองแอปลงในไคลเอ็นต์ OAuth ที่คุณตั้งค่าไว้ในคอนโซล Google Cloud โดยทําตามวิธีการในหัวข้อการตั้งค่า OAuth 2.0 / แอปพลิเคชันเนทีฟในเว็บไซต์ความช่วยเหลือของคอนโซล Google Cloud

เมื่ออุปกรณ์เคลื่อนที่เชื่อมต่อกับเครื่องแล้ว ให้เลือกอุปกรณ์จากรายการ แล้วคลิกเรียกใช้โปรเจ็กต์อีกครั้งเพื่อเรียกใช้ ดูวิธีการโดยละเอียดได้ที่หัวข้อเรียกใช้แอปในอุปกรณ์ฮาร์ดแวร์ในเว็บไซต์ของนักพัฒนาแอป Android

ผสานรวม Permissions API

ผู้ใช้ต้องให้สิทธิ์แก่แอปของคุณจึงจะเข้าถึงอุปกรณ์ภายในโครงสร้างที่กำหนดได้ ในการเริ่มต้น ให้ตรวจสอบว่าคุณได้เริ่มต้น Home API แล้ว ระบบจะใช้อินสแตนซ์ homeManager จากขั้นตอนนั้นในตัวอย่างสิทธิ์ทั้งหมดที่นี่

ก่อนอื่น ให้ลงทะเบียน ActivityResultCaller กับ SDK ตัวอย่างเช่น แอปตัวอย่างจัดการเหตุการณ์นี้ดังนี้

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

ตรวจสอบสิทธิ์

ก่อนขอสิทธิ์ เราขอแนะนำให้คุณตรวจสอบว่าผู้ใช้แอปให้ความยินยอมแล้วหรือยัง โดยเรียกใช้เมธอด hasPermissions() ของอินสแตนซ์ Home เพื่อรับ 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) แล้ว และคุณควรขอสิทธิ์ มิเช่นนั้นผู้ใช้ควรมีสิทธิ์เข้าถึงอยู่แล้ว

ขอสิทธิ์

คุณต้องให้สิทธิ์แก่แอปเพื่อเข้าถึงโครงสร้างและอุปกรณ์ภายในโครงสร้างหนึ่งๆ

หากผู้ใช้ยังไม่ได้ให้สิทธิ์ ให้ใช้เมธอด requestPermissions() ของอินสแตนซ์ Home เพื่อเปิด 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 สําหรับแอปแล้วเพื่อให้ UI สิทธิ์เปิดขึ้นอย่างถูกต้อง

ให้สิทธิ์

ตอนนี้คุณควรเรียกใช้แอปและมีสิทธิ์ที่ผู้ใช้ให้แล้ว ประเภทผู้ใช้ที่สามารถให้สิทธิ์ และประเภทอุปกรณ์ที่พร้อมให้สิทธิ์จะแตกต่างกันไป ขึ้นอยู่กับว่าคุณได้ลงทะเบียนแอปใน Developer Console หรือไม่

คุณต้องลงทะเบียน Developer Console เพื่อเผยแพร่แอปโดยใช้ Home API คุณไม่จำเป็นต้องทดสอบและใช้ Home API หากต้องการเข้าถึงฟีเจอร์การลงทะเบียนคอนโซล โปรดติดต่อ Technical Account Manager (TAM) ของ Google

หากแอปไม่ได้จดทะเบียนใน Developer Console แอปจะอยู่ในสถานะไม่ได้รับการยืนยัน เราขอแนะนําให้ใช้วิธีนี้เพื่อทดสอบการใช้ Home API

  • เฉพาะผู้ใช้ที่ลงทะเบียนเป็นผู้ใช้ทดสอบในคอนโซล OAuth เท่านั้นที่จะให้สิทธิ์แก่แอปได้ โดยแอปที่ยังไม่ได้รับการยืนยันจะมีผู้ใช้ทดสอบได้สูงสุด 100 ราย

  • แอปที่ไม่ได้รับการยืนยันจะมีสิทธิ์เข้าถึงอุปกรณ์ประเภทใดก็ได้ที่ OAuth รองรับสำหรับ Home API (รายการประเภทอุปกรณ์ใน Developer Console) โดยระบบจะให้สิทธิ์เข้าถึงอุปกรณ์ทั้งหมดในโครงสร้าง

หากแอปลงทะเบียนใน Developer Console และได้รับอนุมัติให้เข้าถึงอุปกรณ์อย่างน้อย 1 ประเภท และการตรวจสอบแบรนด์สำหรับ OAuth เสร็จสมบูรณ์แล้ว แอปจะอยู่ในสถานะยืนยันแล้ว สถานะนี้จําเป็นสําหรับการเปิดตัวแอปเป็นเวอร์ชันที่ใช้งานจริง

  • ขีดจํากัดของผู้ใช้ทดสอบจะไม่มีผลอีกต่อไป ผู้ใช้ทุกคนสามารถให้สิทธิ์แก่แอปได้
  • ผู้ใช้จะให้สิทธิ์ได้เฉพาะกับอุปกรณ์ประเภทที่ได้รับอนุมัติในDeveloper Consoleเท่านั้น

เมื่อตั้งค่า OAuth แล้ว การเรียกใช้ requestPermissions() ของแอปจะทริกเกอร์กล่องโต้ตอบต่อไปนี้

  1. ระบบจะแจ้งให้ผู้ใช้เลือกบัญชี Google ที่ต้องการใช้
  2. ระบบจะแจ้งให้ผู้ใช้เลือกโครงสร้างที่ต้องการให้สิทธิ์เข้าถึงแก่แอป
    1. สําหรับแอปที่ยังไม่ได้รับการยืนยัน แอปจะใช้อุปกรณ์ทุกประเภทที่ Home API รองรับได้
    2. สําหรับแอปที่ยืนยันแล้ว ผู้ใช้จะให้สิทธิ์ได้เฉพาะอุปกรณ์ประเภทที่อนุมัติใน Developer Console
    3. สําหรับอุปกรณ์ประเภทที่มีความละเอียดอ่อนซึ่งแอปมีสิทธิ์เข้าถึงเพื่อจัดการ ผู้ใช้สามารถจํากัดการเข้าถึงในแต่ละอุปกรณ์ได้ ตัวอย่างเช่น หากผู้ใช้มีล็อก 3 ตัว ผู้ใช้จะให้สิทธิ์เข้าถึงได้เพียงล็อกเดียวเท่านั้น
  • ความยินยอม OAuth - เลือกบัญชี
  • OAuth consent - link devices 01
  • OAuth consent - link device 02
  • OAuth consent - devices granted
รูปที่ 1: ตัวอย่างขั้นตอนความยินยอม OAuth

เมื่อได้รับสิทธิ์แล้ว แอปจะใช้ Home API เพื่ออ่านสถานะและควบคุมอุปกรณ์ในโครงสร้างได้ หากผู้ใช้ไม่ให้สิทธิ์แก่แอปสำหรับอุปกรณ์บางประเภทหรืออุปกรณ์ที่มีความละเอียดอ่อน แอปจะใช้ Home API เพื่อเข้าถึง ควบคุม หรือทํางานอัตโนมัติไม่ได้

เปลี่ยนแปลงสิทธิ์

หากต้องการให้สิทธิ์เข้าถึงอุปกรณ์ในโครงสร้างอื่น ให้เปิดเครื่องมือเลือกบัญชีเพื่อให้ผู้ใช้เลือกบัญชี Google และโครงสร้างที่จะเปลี่ยนไปใช้ ในระหว่างกระบวนการนี้ ผู้ใช้จะเห็นหน้าจอขอความยินยอมอีกครั้ง แม้ว่าก่อนหน้านี้ผู้ใช้จะให้ความยินยอมแล้วก็ตาม

ซึ่งทำได้ด้วยการเรียกใช้ requestPermissions() อีกครั้งโดยตั้งค่า Flag forceLaunchเป็น true

homeManager.requestPermissions(forceLaunch=true)

เพิกถอนสิทธิ์

ผู้ใช้สามารถเพิกถอนสิทธิ์เข้าถึงที่มอบไว้ก่อนหน้านี้ได้ ดังนี้

  1. ผ่านหน้า Google MyAccount > ข้อมูลและความเป็นส่วนตัว > แอปและบริการของบุคคลที่สาม ซึ่งจะเป็นการเพิกถอนโทเค็น OAuth ที่ออกเมื่อผู้ใช้ให้ความยินยอมครั้งแรก และเพิกถอนสิทธิ์เข้าถึงอินสแตนซ์ของแอปที่ผู้ใช้ใช้อยู่ในแพลตฟอร์ม (โทรศัพท์) และโครงสร้างทั้งหมด

  2. ผ่านหน้า GHA > การตั้งค่า > แอปที่ลิงก์ การคลิก ใน GHA จะนําคุณไปยังหน้าการตั้งค่า จากตรงนั้น ให้คลิกการ์ดแอปที่ลิงก์ ซึ่งจะนำคุณไปยังหน้าที่มีลักษณะคล้ายกับหน้าจอขอความยินยอม จากหน้านี้ ผู้ใช้จะนำสิทธิ์เข้าถึงแอปออกได้ ผู้ใช้สามารถใช้หน้าเดียวกันนี้เพื่อเปลี่ยนประเภทอุปกรณ์หรืออุปกรณ์ที่ละเอียดอ่อนที่เฉพาะเจาะจงซึ่งแอปเข้าถึงได้

  3. ผ่านหน้าแอปที่ลิงก์ไว้ในเว็บโดยตรง

หากคุณมีไคลเอ็นต์ OAuth อยู่แล้ว

หากมีไคลเอ็นต์ OAuth ที่ตรวจสอบแล้วสําหรับแอปที่เผยแพร่แล้ว คุณจะใช้ไคลเอ็นต์ OAuth ที่มีอยู่เพื่อทดสอบ Home API ได้

คุณไม่จำเป็นต้องลงทะเบียน Developer Console เพื่อทดสอบและใช้ Home API อย่างไรก็ตาม คุณยังคงต้องลงทะเบียนDeveloper Consoleที่ได้รับอนุมัติเพื่อเผยแพร่แอป แม้ว่าจะมีไคลเอ็นต์ OAuth ที่ยืนยันแล้วจากการผสานรวมอื่นก็ตาม

โปรดพิจารณาข้อต่อไปนี้

  • ผู้ใช้มีจำนวนได้สูงสุด 100 คนเมื่อใช้ไคลเอ็นต์ OAuth ที่มีอยู่ ดูข้อมูลเกี่ยวกับการเพิ่มผู้ใช้ทดสอบได้ที่ตั้งค่าหน้าจอขอความยินยอม OAuth นอกเหนือจากการยืนยัน OAuth แล้ว ยังมีขีดจํากัดของผู้ใช้ที่ Home API กำหนดไว้ซึ่งสามารถให้สิทธิ์แก่แอปพลิเคชันของคุณได้สูงสุด 100 คน ข้อจำกัดนี้จะยกเลิกเมื่อลงทะเบียน Developer Console

  • Developer Console registration ควรส่งเพื่อขออนุมัติเมื่อคุณพร้อมที่จะจํากัดการให้สิทธิ์ประเภทอุปกรณ์ผ่าน OAuth เพื่อเตรียมอัปเดตแอปด้วย Home API

สําหรับแอป Google Cloud ที่รอการยืนยัน OAuth อยู่ ผู้ใช้จะทําตามขั้นตอน OAuth ให้เสร็จสมบูรณ์ไม่ได้จนกว่าการยืนยันจะเสร็จสมบูรณ์ การพยายามที่จะให้สิทธิ์จะล้มเหลวโดยแสดงข้อผิดพลาดต่อไปนี้

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

สิทธิ์ OkGoogle

คำสั่ง okGoogle เป็นคำสั่งระดับโครงสร้างและสามารถใช้เพื่อทำให้อุปกรณ์ใดก็ได้ในโครงสร้างทำงานอัตโนมัติ อย่างไรก็ตาม แอป Home API อาจไม่มีสิทธิ์เข้าถึงอุปกรณ์บางเครื่อง ตารางต่อไปนี้อธิบายวิธีบังคับใช้สิทธิ์ในกรณีดังกล่าว

การทำงานอัตโนมัติ ลักษณะ การบังคับใช้สิทธิ์
เวลา 22:00 น. ให้ประกาศว่า "เวลาเข้านอน" บนลำโพงห้องนอน AssistantBroadcastTrait ในอุปกรณ์ การสร้างการทำงานอัตโนมัติ
  • อุปกรณ์ที่ออกอากาศต้องเป็นอุปกรณ์ Assistant
  • แอปและผู้ใช้ต้องมีสิทธิ์เข้าถึงอุปกรณ์ที่มีการออกอากาศ
การดำเนินการอัตโนมัติ:
  • แอปและผู้ใช้ต้องมีสิทธิ์เข้าถึงอุปกรณ์ที่มีการออกอากาศ
เวลา 22:00 น. ประกาศว่า "เข้านอน" ในอุปกรณ์ทั้งหมด AssistantBroadcastTrait เกี่ยวกับโครงสร้าง การสร้างการทำงานอัตโนมัติ
  • ต้องมีอุปกรณ์ Assistant อย่างน้อย 1 เครื่องในโครงสร้างที่แอปและผู้ใช้มีสิทธิ์เข้าถึง
  • แอปและผู้ใช้ต้องมีสิทธิ์เข้าถึงโครงสร้าง
การดำเนินการอัตโนมัติ:
  • แอปและผู้ใช้ต้องมีสิทธิ์เข้าถึงโครงสร้าง
เวลา 22:00 น. "เปิดเพลงหน่อย" AssistantFulfillmentTrait.OkGoogleCommand การสร้างการทำงานอัตโนมัติ
  • แอปและผู้ใช้ต้องมีสิทธิ์เข้าถึงอุปกรณ์ทั้งหมดของผู้ใช้ (ยกเว้นกล้อง)
การดำเนินการอัตโนมัติ:
  • แอปและผู้ใช้ต้องมีสิทธิ์เข้าถึงอุปกรณ์ทั้งหมดที่ดำเนินการ
เมื่อมีคนพูดว่า "เปิดเพลงหน่อย" VoiceStarterTrait.OkGoogleEvent การสร้างการทำงานอัตโนมัติ
  • แอปและผู้ใช้ต้องมีสิทธิ์เข้าถึงโครงสร้างและอุปกรณ์ Assistant อย่างน้อย 1 เครื่อง
การดำเนินการอัตโนมัติ:
  • แอปไม่จําเป็นต้องใช้สิทธิ์เข้าถึงอุปกรณ์ที่เริ่มการทำงานอัตโนมัติ
  • แอปและผู้ใช้ต้องมีสิทธิ์เข้าถึงอุปกรณ์ที่เกิดการดำเนินการ