ขอการซิงค์

Cloud-to-cloud

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

คุณต้องทริกเกอร์คำขอ SYNC ดังนี้

  • หากผู้ใช้เพิ่มอุปกรณ์ใหม่
  • หากผู้ใช้นำอุปกรณ์ที่มีอยู่ออก
  • หากผู้ใช้เปลี่ยนชื่ออุปกรณ์ที่มีอยู่
  • หากคุณใช้ประเภทอุปกรณ์ ลักษณะ หรือเพิ่มฟีเจอร์ใหม่ของอุปกรณ์

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

หากต้องการใช้การซิงค์คำขอ ให้ทำตามขั้นตอนต่อไปนี้

เปิดใช้ 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 API มีปลายทาง 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. {
      "agentUserId": "user-123"
    }
  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:requestSync"
    

gRPC

Home Graph API มีปลายทาง gRPC

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

Node.js

ไคลเอ็นต์ Node.js ของ Google APIs มีการเชื่อมโยงสำหรับ Home Graph API

  1. เริ่มต้นบริการ google.homegraph โดยใช้ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน
  2. เรียกใช้เมธอด requestSync ด้วย RequestSyncDevicesRequest โดยจะแสดงผล Promise ที่มี RequestSyncDevicesResponse ที่ว่างเปล่า
const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.requestSync({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    async: false
  }
});
    

Java

ไลบรารีของไคลเอ็นต์ HomeGraph API สำหรับ Java มีการเชื่อมโยงสำหรับ Home Graph API

  1. เริ่มต้น HomeGraphApiService โดยใช้ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน
  2. เรียกใช้เมธอด requestSync ด้วย RequestSyncDevicesRequest โดยจะแสดงผล 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();

// Request sync.
RequestSyncDevicesRequest request =
    new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false);
homegraphService.devices().requestSync(request);
    

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

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

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