طلب المزامنة

المحتوى

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

يجب تنفيذ طلب SYNC:

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

البدء

لتنفيذ "طلب المزامنة"، يُرجى اتّباع الخطوات التالية:

تفعيل Google HomeGraph API

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

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

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

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

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

    الانتقال إلى صفحة "إنشاء مفتاح حساب الخدمة"
  2. من قائمة حساب الخدمة، اختَر حساب خدمة جديد.
  3. في الحقل اسم حساب الخدمة، أدخِل اسمًا.
  4. في الحقل رقم تعريف حساب الخدمة، أدخِل معرِّفًا.
  5. من قائمة الدور، اختَر حسابات الخدمة > منشئ الرمز المميَّز لحساب الخدمة.

  6. بالنسبة إلى نوع المفتاح، حدِّد الخيار JSON.

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

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

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
    
  4. أنشِئ طلب JSON باستخدام agentUserId. في ما يلي نموذج لطلب JSON لطلب المزامنة:
  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

توفّر واجهة برمجة التطبيقات Home Graph API نقطة نهاية gRPC (نقطة نهاية gRPC).

  1. يمكنك الحصول على تعريف خدمة المخازن المؤقتة للبروتوكول لواجهة برمجة التطبيقات Home Graph.
  2. اتّبِع مستندات المطوِّر الخاصة بـ gRPC لإنشاء رموز برمجية للعميل لإحدى اللغات المعتمَدة.
  3. عليك استدعاء الإجراء RequestSync.

Node.js

يوفّر عميل Node.js من Google APIs روابط لواجهة برمجة التطبيقات Home Graph.

  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

توفّر مكتبة برامج Home Graph API للغة Java روابط لواجهة برمجة التطبيقات Home Graph.

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