يؤدي طلب المزامنة إلى تشغيل طلب SYNC
لتنفيذ أي مستخدم Google
لديه أجهزة تتضمن
agentUserId
المحددة المرتبطة بها (والذي
أرسلته في طلب المزامنة الأصلي). يتيح لك ذلك تحديث أجهزة المستخدمين
بدون إلغاء ربط حساباتهم وإعادة ربطها. سيتلقّى جميع المستخدمين المرتبطين
بهذا المعرّف طلب SYNC
.
يجب تنفيذ طلب SYNC
:
- إذا أضاف المستخدم جهازًا جديدًا.
- إذا أزال المستخدم جهازًا حاليًا.
- إذا أعاد المستخدم تسمية جهاز حالي.
- في حال تنفيذ نوع جهاز جديد أو سمة أو إضافة ميزة جديدة للجهاز.
البدء
لتنفيذ "طلب المزامنة"، يُرجى اتّباع الخطوات التالية:
تفعيل Google HomeGraph API
-
في Google Cloud Console، انتقِل إلى صفحة HomeGraph API.
الانتقال إلى صفحة HomeGraph API - اختَر المشروع الذي يتطابق مع رقم تعريف مشروع smart home.
- انقر على تفعيل.
إنشاء مفتاح لحساب الخدمة
اتّبِع هذه التعليمات لإنشاء مفتاح حساب خدمة من Google Cloud Console:
-
في Google Cloud Console، انتقِل إلى صفحة إنشاء مفتاح حساب الخدمة.
الانتقال إلى صفحة "إنشاء مفتاح حساب الخدمة" - من قائمة حساب الخدمة، اختَر حساب خدمة جديد.
- في الحقل اسم حساب الخدمة، أدخِل اسمًا.
- في الحقل رقم تعريف حساب الخدمة، أدخِل معرِّفًا.
من قائمة الدور، اختَر حسابات الخدمة > منشئ الرمز المميَّز لحساب الخدمة.
بالنسبة إلى نوع المفتاح، حدِّد الخيار JSON.
- انقر على إنشاء. ملف JSON يحتوي على المفتاح الذي يتم تنزيله على جهاز الكمبيوتر.
استدعاء واجهة برمجة التطبيقات
HTTP
توفّر Home Graph API نقطة نهاية HTTP.
- يمكنك استخدام ملف JSON لحساب الخدمة الذي تم تنزيله لإنشاء رمز JSON المميّز للويب (JWT). ولمزيد من المعلومات، يُرجى الاطّلاع على المصادقة باستخدام حساب الخدمة.
- يمكنك الحصول على رمز دخول OAuth 2.0 من خلال
نطاق
https://www.googleapis.com/auth/homegraph
باستخدام oauth2l: - أنشِئ طلب JSON باستخدام
agentUserId
. في ما يلي نموذج لطلب JSON لطلب المزامنة: - يمكنك دمج بيانات JSON والرمز المميّز في طلب HTTP POST مع نقطة نهاية Google Home Graph. في ما يلي مثال على كيفية إنشاء الطلب في سطر الأوامر باستخدام
curl
كاختبار:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "agentUserId": "user-123" }
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).
- يمكنك الحصول على تعريف خدمة المخازن المؤقتة للبروتوكول لواجهة برمجة التطبيقات Home Graph.
- اتّبِع مستندات المطوِّر الخاصة بـ gRPC لإنشاء رموز برمجية للعميل لإحدى اللغات المعتمَدة.
- عليك استدعاء الإجراء RequestSync.
Node.js
يوفّر عميل Node.js من Google APIs روابط لواجهة برمجة التطبيقات Home Graph.
- اضبط خدمة
google.homegraph
باستخدام بيانات الاعتماد التلقائية للتطبيق. - استدعِ الطريقة
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.
- اضبط
HomeGraphApiService
باستخدام بيانات الاعتماد التلقائية للتطبيق. - عليك استدعاء طريقة
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
على "صحيح".