สถานะรายงาน

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

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

หากไม่มี Report State เมื่อมีไฟจากผู้ให้บริการหลายรายใน ห้องนั่งเล่น คำสั่ง Ok Google เปิดไฟในห้องนั่งเล่น จะต้องมีการ แก้ปัญหา Intent 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
• สร้างคีย์บัญชีบริการ
• เรียกใช้ API

เปิดใช้ Google HomeGraph API

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

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

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

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

1. ใน Google Cloud Console ให้ไปที่หน้าบัญชีบริการ

   ไปที่หน้าบัญชีบริการ

   คุณอาจต้องเลือกโปรเจ็กต์ก่อนที่จะไปที่หน้าบัญชีบริการ

2. คลิก addสร้างบัญชีบริการ

3. ป้อนชื่อในช่องชื่อบัญชีบริการ

4. ป้อนรหัสในช่องรหัสบัญชีบริการ

5. ป้อนคำอธิบายในช่องคำอธิบายบัญชีบริการ

6. คลิกสร้างและต่อไป

7. จากเมนูแบบเลื่อนลงบทบาท ให้เลือกบัญชีบริการ > ผู้สร้างโทเค็นรหัสประจำตัว OpenID Connect ของบัญชีบริการ

8. คลิกต่อไป

9. คลิกเสร็จสิ้น

10. เลือกบัญชีบริการที่คุณเพิ่งสร้างจากรายการบัญชีบริการ และ เลือก จัดการคีย์ จากเมนู more_vert การดำเนินการ

11. เลือกเพิ่มคีย์ > สร้างคีย์ใหม่

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

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

เรียกใช้ API

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

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
          }
        }
      }
    }
  }
});
    

  // 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).execute();
}
    

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

คุณต้องทดสอบ Report State เพื่อให้การผสานรวม Cloud-to-cloud พร้อมสำหรับการรับรอง

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

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

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

ข้อกำหนดเบื้องต้น

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

ติดตั้งใช้งานแดชบอร์ดสถานะรายงาน

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

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

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

ในแดชบอร์ด ให้ทำดังนี้

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

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

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

ข้อมูลสถานะรายงานไม่ตรงกัน

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

ตัวอย่างบันทึกข้อมูลสถานะรายงานไม่ตรงกัน มีดังนี้

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

คำจำกัดความของช่องบันทึกข้อมูลสถานะรายงานไม่ตรงกัน

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

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

400 คำขอไม่ถูกต้อง

เซิร์ฟเวอร์ประมวลผลคำขอที่ไคลเอ็นต์ส่งมาไม่ได้เนื่องจาก ไวยากรณ์ไม่ถูกต้อง สาเหตุที่พบบ่อย ได้แก่ JSON มีรูปแบบไม่ถูกต้องหรือใช้ null แทน "" สำหรับค่าสตริง

404 ไม่พบ

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

เมื่อการเรียกใช้ ReportState ล้มเหลวโดยมีข้อผิดพลาด 404 NOT_FOUND แสดงว่ามีการซิงค์ไม่ตรงกันระหว่างคลาวด์กับ Home Graph ข้อผิดพลาดนี้อาจเกิดขึ้นหากนำอุปกรณ์ออกจาก Home Graph หรือหาก ผู้ใช้ยกเลิกการลิงก์บัญชี

หากต้องการจัดการข้อผิดพลาด 404 จากสถานะรายงาน ให้ทำตามขั้นตอนต่อไปนี้

1. ตรวจสอบสถานะบัญชีผู้ใช้: เรียกใช้ devices.sync สำหรับ agentUserId ที่แสดงข้อผิดพลาด 404 ซึ่งจะช่วยระบุว่าข้อผิดพลาดเกิดขึ้นกับบัญชีผู้ใช้ทั้งหมดหรืออุปกรณ์ที่เฉพาะเจาะจง
   • หาก SYNC แสดงข้อผิดพลาด 404 แสดงว่าบัญชีผู้ใช้ไม่ได้ลิงก์กับ Google อีกต่อไป หยุดส่งสถานะรายงานและขอซิงค์สำหรับอุปกรณ์ของผู้ใช้รายนี้
   • หาก SYNC แสดง 200 OK แสดงว่าบัญชีผู้ใช้ยังคงลิงก์อยู่ ซึ่งหมายความว่าข้อผิดพลาด 404 เกิดขึ้นกับอุปกรณ์ที่เฉพาะเจาะจง
2. เปรียบเทียบรายการอุปกรณ์: หาก SYNC แสดง 200 OK คุณต้อง ระบุอุปกรณ์ที่ Google ไม่รู้จักอีกต่อไป เราขอแนะนำให้คุณเปรียบเทียบรายการอุปกรณ์ที่ Google มีสำหรับผู้ใช้กับฐานข้อมูลอุปกรณ์ของคุณ และระบุอุปกรณ์ในระบบที่ไม่มีอยู่ในรายการของ Google หากควรซิงค์อุปกรณ์กับ Google แต่ยังไม่ได้ แชร์กับ Google ให้ใช้ SYNC เพื่อตรวจสอบว่าอุปกรณ์ซิงค์กับ Google แล้ว หากควรยกเลิกการลิงก์อุปกรณ์จาก Google ให้หยุดรายงานสถานะสำหรับอุปกรณ์ที่เฉพาะเจาะจงนั้น และรายงานสถานะสำหรับอุปกรณ์อื่นๆ ที่ถูกต้องภายใต้ agentUserId นั้นต่อไป

การรายงานสถานะออนไลน์และออฟไลน์

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }