ส่งคําขอซิงค์

การใช้งานใน Google [

คําขอซิงค์จะทริกเกอร์คําขอ 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

API ของ Home Graph มีปลายทาง 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 สําหรับ Sync Sync
  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

API ของ Home Graph มีปลายทาง 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);
    

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

คุณอาจได้รับข้อความแจ้งข้อผิดพลาดอย่างใดอย่างหนึ่งต่อไปนี้เมื่อเรียกใช้คําขอซิงค์ การตอบกลับเหล่านี้จะอยู่ในรูปแบบรหัสสถานะ 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 รายการเท่านั้น เว้นแต่จะกําหนดการตั้งค่าสถานะ async เป็น "จริง"