مرحبًا بك في "مركز مطوّري برامج Google Home"، وجهتك الجديدة لتعلّم كيفية تطوير إجراءات منزلية ذكية. ملاحظة: ستواصل إنشاء الإجراءات في وحدة تحكم الإجراءات.

طلب المزامنة

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
في YouTube، يمكنك

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

يجب تشغيل طلب SYNC:

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

البدء

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

تفعيل Google HomeGraph API

  1. في Google Cloud Platform Console , go to the HomeGraph API page.

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

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

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

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

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

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

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

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

HTTP

توفر واجهة برمجة التطبيقات للرسم البياني الرئيسي نقطة نهاية 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. في ما يلي مثال على كيفية إجراء الطلب في سطر الأوامر باستخدام 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

توفر واجهة برمجة التطبيقات للرسم البياني الرئيسي نقطة نهاية gRPC

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

Node.js

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

  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 للغة جافا روابط إلى واجهة برمجة تطبيقات 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.