สถานะรายงาน

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

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

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

หลังจาก SYNC เริ่มต้นสำหรับอุปกรณ์ แพลตฟอร์มจะส่งเจตนา 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 ให้พร้อมสำหรับการรับรอง

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

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

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

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

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

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

เมื่อคุณมีคีย์บัญชีบริการและรหัสผู้ใช้ตัวแทนสำหรับโปรเจ็กต์แล้ว ให้ดาวน์โหลดและติดตั้งใช้งานเวอร์ชันล่าสุดจาก 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 และคุณจัดการเจตนา DISCONNECT อย่างถูกต้อง

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

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

1. ตรวจสอบสถานะบัญชีผู้ใช้: โทรหา devices.sync สำหรับ agentUserId ที่แสดงข้อผิดพลาด 404 ซึ่งจะช่วยระบุ ว่าข้อผิดพลาดเกิดขึ้นกับบัญชีผู้ใช้ทั้งหมดหรืออุปกรณ์ที่เฉพาะเจาะจง
   • หาก SYNC แสดงข้อผิดพลาด 404 แสดงว่าระบบไม่ได้ลิงก์บัญชีผู้ใช้กับ Google อีกต่อไป หยุดส่ง Report State และ Request Sync สำหรับอุปกรณ์ของผู้ใช้รายนี้
   • หาก 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": {},
        }
      }
    }