สถานะรายงาน

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

Report State จะรายงานสถานะของอุปกรณ์ของผู้ใช้ ที่มี agentUserId ที่ระบุซึ่งเชื่อมโยงกับอุปกรณ์นั้นๆ (ส่งในคำขอ SYNC เดิม) ไปยัง Google เมื่อ 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

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

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

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

แดชบอร์ด Report State

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

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

ติดตั้งใช้งานแดชบอร์ด Report State

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

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

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

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

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

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

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

ข้อมูลที่ไม่ตรงกันของ Report State

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

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

{
  "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

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

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

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

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

404 ไม่พบ

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

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

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

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": {},
        }
      }
    }