ยินดีต้อนรับสู่ศูนย์นักพัฒนาซอฟต์แวร์ Google Home ซึ่งเป็นจุดหมายใหม่เกี่ยวกับวิธีพัฒนาการดําเนินการสําหรับบ้านอัจฉริยะ หมายเหตุ: คุณจะสร้างการดําเนินการต่างๆ ต่อไปในคอนโซลการดําเนินการ

สถานะรายงาน

Report State เป็นฟีเจอร์สําคัญที่ช่วยให้การดําเนินการ Home มีสถานะล่าสุดของอุปกรณ์ของผู้ใช้กลับไปเป็น Google Home Graph แทนการต้องรอ Intent ของ QUERY

Report State รายงานสถานะอุปกรณ์ของผู้ใช้ให้ Google ทราบโดยใช้agentUserIdที่เกี่ยวข้อง (ส่งในคําขอ SYNC เดิม) เมื่อ Google Assistant ต้องการการดําเนินการที่ต้องอาศัยการทําความเข้าใจสถานะปัจจุบันของอุปกรณ์ เพียงค้นหาข้อมูลสถานะใน Home Graph แทนการออก Intent QUERY ไปยังระบบคลาวด์ของบุคคลที่สามหลายเครื่องก่อนที่จะออก Intent ของ EXECUTE

หากไม่มี Report State จากผู้ให้บริการหลายๆ รายในห้องนั่งเล่น คําสั่ง Ok Google เพิ่มความสว่างให้ห้องนั่งเล่นของฉัน ทําให้ต้องแก้ปัญหาความตั้งใจ QUERY หลายรายการที่ส่งไปยังระบบคลาวด์หลายรายการ แทนที่จะต้องค้นหาค่าความสว่างปัจจุบันตามสิ่งที่รายงานไปก่อนหน้านี้ เพื่อประสบการณ์ของผู้ใช้ที่ดีที่สุด Assistant ต้องมีสถานะปัจจุบันของอุปกรณ์ โดยไม่ต้องเปลี่ยนอุปกรณ์

หลังจาก SYNC แรกสําหรับอุปกรณ์ แพลตฟอร์มจะส่ง Intent ของ QUERY ที่รวบรวมสถานะของอุปกรณ์เพื่อเติมค่า Home Graph หลังจากเวลานั้น Home Graph จะจัดเก็บเฉพาะสถานะที่ส่งด้วย Report State

เมื่อเรียกใช้ Report State โปรดระบุข้อมูลรัฐให้ครบถ้วนสําหรับลักษณะหนึ่งๆ Home Graph จะอัปเดตสถานะตามเกณฑ์และเขียนทับข้อมูลทั้งหมดสําหรับลักษณะนั้นเมื่อเรียกใช้ Report State ตัวอย่างเช่น หากคุณกําลังรายงานสถานะของ StartStop เพย์โหลดจะต้องมีค่าสําหรับทั้ง isRunning และ isPaused

เริ่มต้นใช้งาน

ในการใช้งาน Report State โปรดทําตามขั้นตอนต่อไปนี้

เปิดใช้ Google HomeGraph API

  1. ใน Google Cloud Console ให้ไปที่หน้า HomeGraph API

    ไปที่หน้า HomeGraph API
  2. เลือกโปรเจ็กต์ที่ตรงกับรหัสโปรเจ็กต์ smart home
  3. คลิกเปิดใช้

สร้างคีย์บัญชีบริการ

ทําตามวิธีการต่อไปนี้เพื่อสร้างคีย์บัญชีบริการจาก Google Cloud Console

หมายเหตุ: ตรวจสอบว่าคุณใช้โปรเจ็กต์ GCP ที่ถูกต้องเมื่อดําเนินการขั้นตอนเหล่านี้ นี่คือโปรเจ็กต์ที่ตรงกับรหัสโปรเจ็กต์ smart home ของคุณ
  1. ไปที่หน้าสร้างคีย์ของบัญชีบริการในGoogle Cloud Console

    ไปที่หน้าสร้างคีย์บัญชีบริการ
  2. เลือกบัญชีบริการใหม่จากรายการบัญชีบริการ
  3. ป้อนชื่อลงในช่องชื่อบัญชีบริการ
  4. ป้อนรหัสในช่องรหัสบัญชีบริการ
  5. จากรายการบทบาท ให้เลือกบัญชีบริการ > ผู้สร้างโทเค็นบัญชีบริการ

  6. สําหรับประเภทคีย์ ให้เลือกตัวเลือก JSON

  7. คลิกสร้าง ไฟล์ JSON ที่มีการดาวน์โหลดคีย์ลงในคอมพิวเตอร์

เรียกใช้ API

เลือกตัวเลือกจากแท็บด้านล่าง

HTTP

Home Graph มีปลายทาง HTTP

  1. ใช้ไฟล์ JSON ของบัญชีบริการที่ดาวน์โหลดเพื่อสร้าง JSON Web Token (JWT) ดูข้อมูลเพิ่มเติมได้ใน การตรวจสอบสิทธิ์โดยใช้บัญชีบริการ
  2. รับโทเค็นเพื่อการเข้าถึง OAuth 2.0 ที่มีขอบเขต https://www.googleapis.com/auth/homegraph โดยใช้ oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. สร้างคําขอ JSON ด้วย agentUserId ต่อไปนี้เป็นตัวอย่างคําขอ JSON สําหรับสถานะรายงานและการแจ้งเตือน
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. รวมสถานะรายงานและ JSON การแจ้งเตือนและโทเค็นในคําขอ HTTP POST ของคุณกับปลายทางของ Google Home Graph ต่อไปนี้คือตัวอย่างวิธีส่งคําขอในบรรทัดคําสั่งโดยใช้ curl เป็นการทดสอบ
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

Home Graph มีปลายทาง gRPC

  1. รับคําจํากัดความของบริการบัฟเฟอร์โปรโตคอลสําหรับ Home Graph API
  2. ทําตามเอกสารสําหรับนักพัฒนาซอฟต์แวร์ gRPC เพื่อสร้างต้นขั้วไคลเอ็นต์สําหรับภาษาที่รองรับ
  3. เรียกเมธอด ReportStateAndNotification

Node.js

ไคลเอ็นต์ Google API Node.js มีการเชื่อมโยงสําหรับ Home Graph API

  1. เริ่มต้นบริการ google.homegraph โดยใช้ข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชัน
  2. เรียกเมธอด reportStateAndNotification ด้วย ReportStateAndNotificationRequest ซึ่งจะแสดงผล Promise ที่มี ReportStateAndNotificationResponse
const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        states: {
          "PLACEHOLDER-DEVICE-ID": {
            on: true
          }
        }
      }
    }
  }
});
    

Java

ไลบรารีของไคลเอ็นต์ HomeGraph API สําหรับ Java มีการเชื่อมโยงสําหรับ Home Graph API

  1. เริ่มต้น HomeGraphApiService ด้วยข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชัน
  2. เรียกเมธอด reportStateAndNotification ด้วย ReportStateAndNotificationRequest ซึ่งจะแสดงผล ReportStateAndNotificationResponse
  // Get Application Default credentials.
  GoogleCredentials credentials =
      GoogleCredentials.getApplicationDefault()
          .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

  // Create Home Graph service client.
  HomeGraphService homegraphService =
      new HomeGraphService.Builder(
              GoogleNetHttpTransport.newTrustedTransport(),
              GsonFactory.getDefaultInstance(),
              new HttpCredentialsAdapter(credentials))
          .setApplicationName("HomeGraphExample/1.0")
          .build();

  // Build device state payload.
  Map<?, ?> states = Map.of("on", true);

  // Report device state.
  ReportStateAndNotificationRequest request =
      new ReportStateAndNotificationRequest()
          .setRequestId("PLACEHOLDER-REQUEST-ID")
          .setAgentUserId("PLACEHOLDER-USER-ID")
          .setPayload(
              new StateAndNotificationPayload()
                  .setDevices(
                      new ReportStateAndNotificationDevice()
                          .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states))));
  homegraphService.devices().reportStateAndNotification(request);
}
    

สถานะรายงานการทดสอบ

เครื่องมือที่แนะนําสําหรับงานนี้

คุณต้องทดสอบ Report State เพื่อเตรียมพร้อมสําหรับการรับรอง

ในการดําเนินการดังกล่าว เราขอแนะนําให้ใช้เครื่องมือดู Home Graph ซึ่งเป็นเว็บแอปแบบสแตนด์อโลนที่ไม่ต้องดาวน์โหลดหรือทําให้ใช้งานได้

หน้าแดชบอร์ด Report State จะยังคงใช้งานได้ แต่เลิกใช้งานแล้วและไม่มีการสนับสนุนแล้ว

หน้าแดชบอร์ดสถานะรายงาน

สิ่งที่ต้องดำเนินการก่อน

ก่อนที่จะทดสอบการดําเนินการได้ คุณต้องมีคีย์บัญชีบริการและ agentUserId หากมีคีย์บัญชีบริการอยู่แล้วและ agentUserId โปรดดูใช้งานReport Stateหน้าแดชบอร์ด

ทําให้หน้าแดชบอร์ดสถานะรายงานใช้งานได้

เมื่อมีคีย์บัญชีบริการและ User Agent สําหรับโปรเจ็กต์แล้ว ให้ดาวน์โหลดและติดตั้งเวอร์ชันล่าสุดจาก Report State Dashboard เมื่อดาวน์โหลดเวอร์ชันล่าสุดแล้ว ให้ทําตามวิธีการจากไฟล์ README.MD ที่รวมอยู่

หลังจากที่คุณทําให้หน้าแดชบอร์ด Report State ใช้งานได้แล้ว ให้เข้าถึงหน้าแดชบอร์ดจาก URL ต่อไปนี้ (แทนที่ your_project_id ด้วยรหัสโปรเจ็กต์)

http://<your-project-id>.appspot.com

ในหน้าแดชบอร์ด ให้ดําเนินการต่อไปนี้

  • เลือกไฟล์คีย์บัญชี
  • เพิ่ม agentUserId ของคุณ

จากนั้นคลิกรายการ

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

การตอบกลับข้อผิดพลาด

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

  • 400 Bad Request - เซิร์ฟเวอร์ไม่สามารถประมวลผลคําขอที่ไคลเอ็นต์ส่งไปได้ เนื่องจากไวยากรณ์ไม่ถูกต้อง สาเหตุที่พบบ่อย ได้แก่ JSON มีรูปแบบไม่ถูกต้องหรือใช้ null แทน "" สําหรับค่าสตริง
  • 404 Not Found - ไม่พบทรัพยากรที่ขอ แต่อาจพร้อมใช้งานได้ในอนาคต ซึ่งปกติแล้วหมายความว่า เราไม่พบอุปกรณ์ที่ขอ ซึ่งอาจหมายความว่าบัญชีผู้ใช้ไม่ได้ลิงก์กับ Google หรือเราได้รับ agentUserId ที่ไม่ถูกต้อง ตรวจสอบว่า agentUserId ตรงกับค่าที่ระบุไว้ในการตอบกลับ SYNC และคุณจัดการ Intent ของ DISCONNECT อย่างถูกต้อง