ยินดีต้อนรับสู่ Google Home Developer Center แหล่งใหม่เรียนรู้วิธีพัฒนาการดําเนินการในบ้านอัจฉริยะ หมายเหตุ: คุณจะสร้างการดําเนินการต่างๆ ต่อไปในคอนโซลการดําเนินการ

สถานะรายงาน

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

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

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

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

หลังจาก SYNC แรกของอุปกรณ์ แพลตฟอร์มจะส่ง Intent ของ QUERY ที่รวบรวมสถานะของอุปกรณ์เพื่อป้อนข้อมูลในแอป Home หลังจากจุดนี้ กราฟหน้าแรกจะจัดเก็บเฉพาะสถานะที่ส่งพร้อมกับสถานะรายงาน

เมื่อเรียกใช้ "สถานะรายงาน" โปรดระบุข้อมูลสถานะที่สมบูรณ์ของลักษณะเฉพาะนั้นๆ กราฟความรู้ของ Google จะอัปเดตสถานะตามลักษณะเฉพาะและเขียนทับข้อมูลทั้งหมดสําหรับลักษณะนั้นเมื่อมีการเรียกใช้สถานะรายงาน ตัวอย่างเช่น หากคุณรายงานสถานะสําหรับลักษณะเฉพาะ StartStop เพย์โหลดจะต้องมีค่าสําหรับทั้ง isRunning และ isPaused

เริ่มต้นใช้งาน

หากต้องการใช้สถานะรายงาน ให้ทําตามขั้นตอนต่อไปนี้

เปิดใช้ Google HomeGraph API

  1. ในคอนโซล Google Cloud Platform ให้ไปที่หน้า HomeGraph API

    ไปที่หน้า HomeGraph API
  2. เลือกโปรเจ็กต์ที่ตรงกับรหัสโปรเจ็กต์สมาร์ทโฮม
  3. คลิกเปิดใช้

สร้างคีย์บัญชีบริการ

ทําตามวิธีการต่อไปนี้เพื่อสร้างคีย์บัญชีบริการจากคอนโซล GCP

หมายเหตุ: ตรวจสอบว่าคุณใช้โปรเจ็กต์ GCP ที่ถูกต้องเมื่อทําตามขั้นตอนเหล่านี้ นี่คือโปรเจ็กต์ที่ตรงกับรหัสโปรเจ็กต์สมาร์ทโฮมของคุณ
  1. ในคอนโซล GCP ให้ไปที่หน้าสร้างคีย์บัญชีบริการ

    ไปที่หน้า "สร้างคีย์บัญชีบริการ"
  2. จากรายการบัญชีบริการ ให้เลือกบัญชีบริการใหม่
  3. ป้อนชื่อลงในช่องชื่อบัญชีบริการ
  4. ป้อนรหัสในช่องรหัสบัญชีบริการ
  5. จากรายการบทบาท ให้เลือกบัญชีบริการ > ผู้สร้างโทเค็นบัญชีบริการ

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

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

เรียกใช้ API

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

HTTP

Home Graph API มีปลายทาง 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 API มีปลายทาง gRPC

  1. รับคําจํากัดความของบริการบัฟเฟอร์โปรโตคอลสําหรับ Home Graph API
  2. โปรดปฏิบัติตามเอกสารสําหรับนักพัฒนาซอฟต์แวร์ gRPC เพื่อสร้างต้นขั้วไคลเอ็นต์สําหรับภาษาที่รองรับ
  3. เรียกเมธอด ReportStateAndNotification

Node.js

ไคลเอ็นต์ Google API 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);
}
    

สถานะรายงานการทดสอบ

คุณต้องทดสอบสถานะรายงานเพื่อเตรียมการดําเนินการให้พร้อมรับใบรับรอง

สิ่งที่ต้องดำเนินการก่อน

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

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

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

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

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

ในหน้าแดชบอร์ด ให้ดําเนินการดังนี้

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

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

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

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

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

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