طلب المزامنة

يؤدي طلب المزامنة إلى بدء طلب 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 Platform الصحيح عند تنفيذ هذه الخطوات. هذا هو المشروع الذي يتطابق مع رقم تعريف مشروعك smart home.

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

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

  5. من قائمة الدور، اختَر حسابات الخدمة > صانع رمز مميّز لحساب الخدمة.

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

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

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

HTTP

توفّر Home Graph API نقطة نهاية HTTP.

  1. استخدِم ملف 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. اجمع ملف Request Sync 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
  }
});

Java

توفّر مكتبة عميل HomeGraph API للغة Java عمليات ربط لواجهة برمجة التطبيقات HomeGraph 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 العلامة على true.
السابق
قطع الاتصال
التالي
تنفيذ حالة التقرير