ขอการซิงค์

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

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

เรียก 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. รวม Request Sync JSON และโทเค็นในคำขอ HTTP POST ไปยังปลายทาง Graph ของ Google Home ต่อไปนี้เป็นตัวอย่างวิธีส่งคำขอในบรรทัดคำสั่งโดยใช้ 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

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

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

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

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