สถานะรายงาน

Report State เป็นฟีเจอร์สำคัญที่ช่วยให้การดำเนินการ 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

  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. สำหรับประเภทคีย์ ให้เลือกตัวเลือก JSON

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

เรียกใช้ API

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

HTTP

Home Graph มอบปลายทาง HTTP

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

Node.js

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

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

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

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

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

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

ทำให้หน้าแดชบอร์ดสถานะรายงานใช้งานได้

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

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

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

ดำเนินการต่อไปนี้ในหน้าแดชบอร์ด

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

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

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

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

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

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