طلب المزامنة

يؤدي طلب المزامنة إلى تنفيذ طلب "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 نقطة نهاية 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
  2. اتّبِع مستندات مطوّري برامج gRPC لإنشاء رموز بديلة للعميل لإحدى اللغات المعتمَدة.
  3. عليك استدعاء طريقة RequestSync.

Node.js

يوفّر عميل Node.js API من Google عمليات ربط لواجهة برمجة تطبيقات 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

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