طلب المزامنة

يؤدي طلب المزامنة إلى إرسال طلب SYNC إلى عملية التنفيذ لأي مستخدم على Google لديه أجهزة مرتبطة بـ agentUserId المحدّد (الذي أرسلته في طلب المزامنة الأصلي). يتيح لك ذلك تحديث أجهزة المستخدمين بدون إلغاء ربط حساباتهم وإعادة ربطها. سيتلقّى جميع المستخدمين المرتبطين بهذا المعرّف طلبًا من "SYNC".

يجب إرسال طلب SYNC:

• إذا أضاف المستخدم جهازًا جديدًا
• إذا أزال المستخدم جهازًا حاليًا
• إذا أعاد المستخدم تسمية جهاز حالي
• إذا نفّذت نوع جهاز أو سمة جديدة أو أضفت ميزة جديدة إلى الجهاز

البدء

لتنفيذ ميزة "طلب المزامنة"، اتّبِع الخطوات التالية:

• تفعيل Google HomeGraph API
• إنشاء مفتاح حساب خدمة
• استدعاء واجهة برمجة التطبيقات

تفعيل Google HomeGraph API

1. في Google Cloud Console، انتقِل إلى صفحة HomeGraph API.

   الانتقال إلى صفحة HomeGraph API
2. اختَر المشروع الذي يتطابق مع رقم تعريف مشروعك على smart home.
3. انقر على تفعيل.

إنشاء مفتاح حساب خدمة

اتّبِع هذه التعليمات لإنشاء مفتاح حساب خدمة من Google Cloud Console:

1. في Google Cloud Console، انتقِل إلى صفحة حسابات الخدمة.

   انتقِل إلى صفحة "حسابات الخدمة".

   قد تحتاج إلى اختيار مشروع قبل الانتقال إلى صفحة "حسابات الخدمة".

2. انقر على addإنشاء حساب خدمة.

3. في حقل اسم حساب الخدمة، أدخِل اسمًا.

4. في حقل رقم تعريف حساب الخدمة، أدخِل رقم تعريف.

5. في حقل وصف حساب الخدمة، أدخِل وصفًا.

6. انقر على إنشاء ومتابعة.

7. من القائمة المنسدلة الدور، اختَر حسابات الخدمة > أداة إنشاء الرمز المميّز لهوية OpenID Connect لحساب الخدمة.

8. انقر على متابعة.

9. انقر على تم.

10. اختَر حساب الخدمة الذي أنشأته للتو من قائمة حسابات الخدمة، ثم اختَر إدارة المفاتيح من قائمة more_vert الإجراءات.

11. انقر على إضافة مفتاح > إنشاء مفتاح جديد.

12. بالنسبة إلى نوع المفتاح، اختَر JSON.

13. انقر على إنشاء. يتم تنزيل ملف JSON يحتوي على مفتاحك على جهاز الكمبيوتر.

استدعاء واجهة برمجة التطبيقات

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
  }
});
    

// 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، ومن أنّك تتعامل بشكل صحيح مع طلبات DISCONNECT.
• 429 Too Many Requests - تم تجاوز الحد الأقصى لعدد طلبات المزامنة المتزامنة لـ agentUserId المحددة. يمكن للمتصل إصدار طلب مزامنة متزامن واحد فقط ما لم يتم ضبط العلامة async على "صحيح".