สถานะรายงาน

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

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

หากไม่มี Report State เมื่อมีหลอดไฟจากผู้ให้บริการหลายรายในห้องนั่งเล่น คำสั่ง Ok Google เพิ่มความสว่างในห้องนั่งเล่นหน่อย จะต้องQUERY แก้ไขความตั้งใจหลายอย่างที่ส่งไปยังระบบคลาวด์หลายระบบ ซึ่งต่างจาก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. คลิกสร้างและต่อไป

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

  8. คลิกต่อไป

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

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

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

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

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

ดูวิธีการโดยละเอียดและข้อมูลเกี่ยวกับการสร้างคีย์บัญชีบริการได้ที่หัวข้อสร้าง และลบคีย์บัญชีบริการในเว็บไซต์ความช่วยเหลือของ Google Cloud Console

เรียก 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. รับคำจำกัดความของบริการ Protocol Buffers สำหรับ Home Graph API
  2. ทำตามเอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์ gRPC เพื่อสร้างต้นขั้วไคลเอ็นต์สำหรับภาษาที่รองรับ
  3. เรียกใช้เมธอด ReportStateAndNotification

Node.js

ไคลเอ็นต์ Node.js ของ Google APIs มีการเชื่อมโยงสำหรับ 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 เพื่อให้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%

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

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

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

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

เมื่ออุปกรณ์ออฟไลน์ คุณควรรายงาน <code{"online": code="" dir="ltr" false}<="" translate="no"> ไปยัง รายงานสถานะ ภายใน 5 นาทีหลังจาก พฤติกรรมของอุปกรณ์ ในทางกลับกัน เมื่ออุปกรณ์กลับมาอยู่ในสถานะออนไลน์ คุณควรรายงาน <code{"online": code="" dir="ltr" translate="no" true}<=""> ไปยังรายงานสถานะภายใน 5 นาทีหลังจากพฤติกรรมของอุปกรณ์ เมื่อใดก็ตามที่อุปกรณ์กลับมาออนไลน์ พาร์ทเนอร์ควรรายงานสถานะปัจจุบันทั้งหมดของอุปกรณ์โดยใช้ reportStateAndNotification API ตัวอย่างนี้แสดงว่าlightประเภทอุปกรณ์ออนไลน์อยู่ และรายงาน สถานะอุปกรณ์ปัจจุบันทั้งหมด
"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }
</code{"online":></code{"online":>