ขอการซิงค์

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

คุณต้องเรียกใช้คำขอ SYNC

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

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

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

Node.js

ไคลเอ็นต์ Google APIs Node.js มีการผูกสำหรับ 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 ตรงกับค่าที่ระบุไว้ในการตอบสนองการซิงค์ และคุณกำลังจัดการ Intent ยกเลิกการเชื่อมต่ออย่างถูกต้อง
  • 429 Too Many Requests - เกินจำนวนคำขอซิงค์พร้อมกันสูงสุดสำหรับ agentUserId ที่ระบุแล้ว ผู้โทรจะส่งคำขอซิงค์พร้อมกันได้เพียง 1 ครั้งเท่านั้น เว้นแต่จะตั้งค่าแฟล็ก async เป็น "จริง"