สถานะรายงาน

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. คลิก addCreate service account

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 ยังคงใช้งานได้ แต่เลิกใช้งานแล้วและไม่รองรับอีกต่อไป

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

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

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

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

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

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

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

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

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

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

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

รายงานความคลาดเคลื่อนของสถานะ

ความแม่นยำของสถานะรายงานตามการค้นหาวัดว่าสถานะรายงานล่าสุดของอุปกรณ์ตรงกับสถานะของอุปกรณ์เมื่อผู้ใช้ค้นหาได้ดีเพียงใด ค่านี้คาดว่าจะอยู่ที่ 99.5% ดูรายละเอียดเพิ่มเติมเกี่ยวกับสถานะปัจจุบันของความถูกต้องของ Report State ของโปรเจ็กต์ได้ที่ประสิทธิภาพการทำงานของอุปกรณ์ - ความถูกต้องของสถานะ นอกจากนี้ คุณยังดูรายละเอียดของบันทึกความคลาดเคลื่อนของสถานะรายงานได้จาก 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 Not Found

ไม่พบทรัพยากรที่ขอ แต่อาจพร้อมใช้งานในอนาคต โดยปกติแล้ว ข้อผิดพลาดนี้หมายความว่าเราไม่พบอุปกรณ์ที่ขอ นอกจากนี้ยังอาจหมายความว่าบัญชีผู้ใช้ไม่ได้ลิงก์กับ 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": {},
        }
      }
    }