ยินดีต้อนรับสู่ Google Home Developer Center แหล่งใหม่เรียนรู้วิธีพัฒนาการดําเนินการในบ้านอัจฉริยะ หมายเหตุ: คุณจะสร้างการดําเนินการต่างๆ ต่อไปในคอนโซลการดําเนินการ

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

จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

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

คุณต้องเรียกคําขอ SYNC ดังนี้

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

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

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

เปิดใช้ Google HomeGraph API

  1. ใน Google Cloud Platform Console ให้ไปที่หน้า HomeGraph API

    ไปที่หน้า HomeGraph API
  2. เลือกโปรเจ็กต์ที่ตรงกับรหัสโปรเจ็กต์ smart home
  3. คลิกเปิดใช้

สร้างคีย์บัญชีบริการ

ทําตามวิธีการต่อไปนี้เพื่อสร้างคีย์บัญชีบริการจาก GCP Console

หมายเหตุ: ตรวจสอบว่าคุณใช้โปรเจ็กต์ GCP ที่ถูกต้องขณะทําตามขั้นตอนเหล่านี้ นี่คือโปรเจ็กต์ที่ตรงกับรหัสโปรเจ็กต์ smart home ของคุณ
  1. ในGCP Console ให้ไปที่หน้าสร้างคีย์บัญชีบริการ

    ไปที่หน้าสร้างคีย์บัญชีบริการ
  2. จากรายการบัญชีบริการ ให้เลือกบัญชีบริการใหม่
  3. ป้อนชื่อในช่องชื่อบัญชีบริการ
  4. ป้อนรหัสในช่องรหัสบัญชีบริการ
  5. จากรายการบทบาท ให้เลือกบัญชีบริการ > ผู้สร้างโทเค็นบัญชีบริการ

  6. สําหรับประเภทคีย์ ให้เลือกตัวเลือก JSON

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

เรียก API

HTTP

API ของ Home Graph มีปลายทาง 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 สําหรับ Sync Sync
  5. {
      "agentUserId": "user-123"
    }
    
  6. รวม JSON Sync 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 API Node.js มีการเชื่อมโยงสําหรับ Home Graph API

  1. เริ่มต้นบริการ google.homegraph โดยใช้ข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชัน
  2. เรียกเมธอด requestSync ด้วย RequestSyncDeviceRequest โดยจะแสดงผล Promise ที่มี RequestSyncDeviceResponse ที่ว่างเปล่า
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 เป็น "จริง"