การซิงค์คำขอจะทริกเกอร์คำขอ SYNC
ไปยัง Fulfillment ของคุณสำหรับผู้ใช้ Google ที่มีอุปกรณ์ซึ่งมี agentUserId
ที่ระบุเชื่อมโยงอยู่ (ซึ่งคุณส่งในคำขอ SYNC เดิม) วิธีนี้ช่วยให้คุณอัปเดตอุปกรณ์ของผู้ใช้ได้โดยไม่ต้องยกเลิกการลิงก์หรือลิงก์บัญชีอีกครั้ง ผู้ใช้ทั้งหมดที่ลิงก์กับตัวระบุนี้จะได้รับคำขอ SYNC
คุณต้องเรียกใช้คำขอ SYNC
- หากผู้ใช้เพิ่มอุปกรณ์ใหม่
- หากผู้ใช้นำอุปกรณ์ที่มีอยู่ออก
- หากผู้ใช้เปลี่ยนชื่ออุปกรณ์ที่มีอยู่
- หากคุณใช้ประเภทอุปกรณ์ ลักษณะ หรือเพิ่มฟีเจอร์ใหม่ของอุปกรณ์
เริ่มต้นใช้งาน
หากต้องการใช้งาน Request Sync ให้ทำตามขั้นตอนต่อไปนี้
เปิดใช้ Google HomeGraph API
-
ใน Google Cloud Console ให้ไปที่หน้า HomeGraph API
ไปที่หน้า HomeGraph API - เลือกโปรเจ็กต์ที่ตรงกับรหัสโปรเจ็กต์ smart home ของคุณ
- คลิกเปิดใช้
สร้างคีย์บัญชีบริการ
ทำตามวิธีการต่อไปนี้เพื่อสร้างคีย์บัญชีบริการจาก Google Cloud Console
-
ในGoogle Cloud Console ให้ไปที่หน้าสร้างคีย์บัญชีบริการ
ไปที่หน้าสร้างคีย์บัญชีบริการ - จากรายการบัญชีบริการ ให้เลือกบัญชีบริการใหม่
- ป้อนชื่อในช่องชื่อบัญชีบริการ
- ป้อนรหัสในช่องรหัสบัญชีบริการ
จากรายการบทบาท ให้เลือกบัญชีบริการ > ผู้สร้างโทเค็นบัญชีบริการ
สำหรับประเภทคีย์ ให้เลือกตัวเลือก JSON
- คลิกสร้าง ไฟล์ JSON ที่มีคีย์ที่ดาวน์โหลดลงในคอมพิวเตอร์
เรียกใช้ API
HTTP
Home Graph API มีปลายทาง HTTP
- ใช้ไฟล์ JSON ของบัญชีบริการที่ดาวน์โหลดเพื่อสร้างโทเค็นเว็บ JSON (JWT) ดูข้อมูลเพิ่มเติมได้ที่ การตรวจสอบสิทธิ์โดยใช้บัญชีบริการ
- รับโทเค็นเพื่อการเข้าถึง OAuth 2.0 ที่มีขอบเขต
https://www.googleapis.com/auth/homegraph
โดยใช้ oauth2l: - สร้างคำขอ JSON ด้วย
agentUserId
ต่อไปนี้คือตัวอย่างคำขอ JSON สำหรับการซิงค์คำขอ - รวม JSON ของ Request Sync และโทเค็นในคำขอ HTTP POST กับจุดสิ้นสุดของ Google Home Graph ตัวอย่างวิธีส่งคำขอในบรรทัดคำสั่งโดยใช้
curl
เพื่อเป็นการทดสอบมีดังนี้
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "agentUserId": "user-123" }
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
- ดูคำจำกัดความของบริการบัฟเฟอร์โปรโตคอลสำหรับ Home Graph API
- ทำตามเอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์ gRPC เพื่อสร้างสตับไคลเอ็นต์สำหรับภาษาที่รองรับ
- เรียกเมธอด RequestSync
Node.js
ไคลเอ็นต์ Google APIs Node.js มีการผูกสำหรับ Home Graph API
- เริ่มต้นบริการ
google.homegraph
โดยใช้ข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชัน - เรียกใช้เมธอด
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
- เริ่มต้น
HomeGraphApiService
โดยใช้ ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน - เรียกเมธอด
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
เป็น "จริง"