طلب المزامنة

Cloud-to-cloud

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

يجب إرسال طلب SYNC في الحالات التالية:

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

البدء

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

تفعيل Google HomeGraph API

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

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

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

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

ملاحظة: تأكَّد من استخدام مشروع Google Cloud الصحيح عند تنفيذ هذه الخطوات. هذا هو المشروع الذي يتطابق مع رقم تعريف مشروعك smart home.

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

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

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

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

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

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

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

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

  7. من القائمة المنسدلة الدور ، اختَر حسابات الخدمة > منشئ رموز تعريف اتصال OpenID لحساب الخدمة.

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

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

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

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

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

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

للحصول على تعليمات مفصّلة ومعلومات حول إنشاء مفاتيح حسابات الخدمة، يُرجى الاطّلاع على مقالة إنشاء مفاتيح حسابات الخدمة وحذفها على موقع مساعدة Google Cloud Console الإلكتروني.

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

HTTP

توفر Home Graph API نقطة نهاية 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
  3. أنشِئ طلب JSON باستخدام agentUserId. في ما يلي نموذج لطلب JSON لميزة "طلب المزامنة":
    4. {
  "agentUserId": "user-123"
}
  4. اجمع بين JSON الخاص بميزة "طلب المزامنة" والرمز المميّز في طلب HTTP POST إلى نقطة نهاية Google Home Graph. في ما يلي مثال على كيفية إرسال الطلب في سطر الأوامر باستخدام curl، كاختبار:
    5. 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 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
  }
});

جافا

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