إنّ تحديثات الوقت الفعلي مخصّصة بشكل أساسي للتغييرات التي لا يمكنك توقّعها، مثل عمليات الإغلاق الطارئة أو البيانات الوصفية التي تتغيّر بشكل دوري (مثل الوقت المقدّر للوصول). إذا لم يكن من الضروري أن يظهر التغيير على الفور، يمكنك استخدام ميزة استيعاب الخلاصة المجمّعة بدلاً من ذلك. تتم معالجة التعديلات في الوقت الفعلي في غضون خمس دقائق كحد أقصى.
إعداد Google Cloud Platform
- إعداد مشروع على Google Cloud Platform يجب إنشاء مشروع على Google Cloud Platform للوصول إلى واجهة برمجة التطبيقات RTU API.
- منح إذن الوصول إلى المحرّر food-support@google.com
- أبلِغ جهة الاتصال في Google برقم مشروع Google Cloud Platform.يجب ربط مشروع Google Cloud Platform بحسابك على "مركز الإجراءات" لكي تعمل الإشعارات في الوقت الفعلي.
- فعِّل Maps Booking API:
- في Google Cloud Platform، انتقِل إلى واجهات برمجة التطبيقات والخدمات > المكتبة.
- ابحث عن "Google Maps Booking API".
- ابحث عن مثيل Sandbox ("Google Maps Booking API (Dev)") وانقر على تفعيل.
- ابحث عن مثيل الإنتاج (Google Maps Booking API) وانقر على تفعيل
- أنشِئ حساب خدمة بدور المحرِّر في مشروعك على Google Cloud Platform. لمزيد من التفاصيل، يُرجى الاطّلاع على إعداد حساب الخدمة.
- تأكَّد من تحميل خلاصات مجمّعة إلى البيئة التي تعمل فيها على التعديلات في الوقت الفعلي.
- للمصادقة على واجهة برمجة التطبيقات، ننصح بتثبيت مكتبة Google Client باللغة التي تختارها. استخدِم "https://www.googleapis.com/auth/mapsbooking" كنطاق OAuth. تستخدم نماذج الرموز البرمجية المضمّنة أدناه هذه المكتبات. بخلاف ذلك، عليك التعامل مع عمليات تبادل الرموز المميزة يدويًا كما هو موضّح في استخدام OAuth 2.0 للوصول إلى Google APIs.
إعداد حساب الخدمة
تحتاج إلى حساب خدمة لإرسال طلبات HTTPS مصادَق عليها إلى واجهات برمجة تطبيقات Google، مثل واجهة برمجة تطبيقات التحديثات في الوقت الفعلي.
لإعداد حساب خدمة، اتّبِع الخطوات التالية:
- الوصول إلى وحدة تحكّم Google Cloud Platform
- يتضمّن حسابك على مركز الإجراءات أيضًا مشروعًا على Google Cloud مرتبطًا به. اختَر هذا المشروع إذا لم يكن محدّدًا من قبل.
- انقر على حسابات الخدمة في القائمة اليمنى.
- انقر على إنشاء حساب خدمة.
- أدخِل اسمًا لحساب الخدمة وانقر على إنشاء.
- في اختيار دور، اختَر مشروع > محرر.
- انقر على متابعة.
- اختياري: أضِف مستخدمين لمنحهم إذن الوصول إلى حساب الخدمة، ثم انقر على تم.
- انقر على المزيد > إنشاء مفتاح لحساب الخدمة الذي أنشأته للتو.
- اختَر JSON كتنسيق وانقر على إنشاء.
- بعد إنشاء زوج المفتاح العام/الخاص الجديد، نزِّله على جهازك.
العمل مع واجهة برمجة التطبيقات
تتيح واجهة برمجة التطبيقات "التعديلات في الوقت الفعلي" نوعَين من العمليات: "تعديل" و"حذف". لا يمكن إضافة كيانات جديدة من خلال واجهة برمجة التطبيقات لتعديل المحتوى في الوقت الفعلي. يمكن تجميع التعديلات في الوقت الفعلي إذا أدرجت تعديلات متعددة في طلب واحد من واجهة برمجة التطبيقات. يمكنك تجميع ما يصل إلى 1,000 تحديث في طلب واحد من واجهة برمجة التطبيقات. ننصحك باستخدام أسلوب يستند إلى المشغّلات لإرسال التعديلات من خلال التحديث في الوقت الفعلي (أي عند حدوث تغيير في البيانات في نظامك، يتم تشغيل تحديث في الوقت الفعلي إلى Google)، بدلاً من أسلوب يستند إلى التكرار (أي كل X دقيقة يتم فحص نظامك بحثًا عن التغييرات)، إذا أمكن ذلك.
تعمل واجهة برمجة التطبيقات الخاصة بالتعديلات في الوقت الفعلي في كلّ من بيئة وضع الحماية وبيئة الإنتاج. تُستخدَم بيئة وضع الحماية لاختبار طلبات واجهة برمجة التطبيقات وبيئة الإنتاج لتعديل المحتوى المرئي لمستخدمي ميزة "الطلب من البداية إلى النهاية".
- وضع الحماية -
partnerdev-mapsbooking.googleapis.com - الإنتاج -
mapsbooking.googleapis.com
نقاط النهاية
تعرض واجهة برمجة التطبيقات الخاصة بالتعديلات في الوقت الفعلي نقطتَي نهاية للتعامل مع الطلبات الواردة لتعديلات المخزون:
- تعديل -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - DELETE -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
يمكن العثور على المَعلمة PARTNER_ID في مركز الإجراءات ضمن صفحة الحساب والمستخدِمون، كما هو موضّح في لقطة الشاشة أدناه.
باستخدام 10000001 كقيمة PARTNER_ID كمثال من لقطة الشاشة أعلاه، ستظهر عناوين URL الكاملة لإرسال طلبات واجهة برمجة التطبيقات في بيئة الاختبار وبيئة الإنتاج كما في الأمثلة أدناه.
تحديث وضع الحماية
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
حذف في وضع الحماية
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
آخر الأخبار حول الإنتاج
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
حذف الإصدار العلني
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
تعديل الكيانات
لتعديل الكيانات في مستودعك، استخدِم نقطة النهاية update في طلب HTTP POST. يجب أن يتضمّن كل طلب POST المَعلمة 10000001 بالإضافة إلى حمولة JSON تحتوي على العنصر الذي تريد تعديله.
ملاحظة: تأكَّد من أنّ خلاصات البيانات اليومية تحتوي أيضًا على أي تغييرات تم إرسالها من خلال واجهة برمجة التطبيقات الخاصة بالتعديلات في الوقت الفعلي. وفي حال عدم إجراء ذلك، قد تكون بياناتك قديمة أو غير صالحة.
حمولة طلب التعديل
نص الطلب هو عنصر JSON يتضمّن قائمة بالسجلات. يتطابق كل سجلّ مع كيان يتم تعديله. يتألف من الحقل proto_record وgeneration_timestamp الذي يشير إلى وقت تعديل العنصر:
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}ServiceData PROTO: ترجمة proto أو JSON لكيان ServiceData الذي تعدّله.UPDATE_TIMESTAMP: احرص على تضمين الطابع الزمني لتاريخ إنشاء العنصر في أنظمة الخلفية. في حال عدم تضمين هذا الحقل، سيتم ضبطه على الوقت الذي تتلقّى فيه Google الطلب. عند تعديل كيان من خلال طلبbatchPush، يتم استخدام الحقلgeneration_timestampلتحديد إصدار الكيان. اطّلِع على التنسيق المتوقّع لقيم الوقت في مخطط المستودع العلائقي.
- يجب ألا يتجاوز حجم نص الحمولة 5 ميغابايت.
- إزالة المسافات البيضاء لتقليل الحجم
- يمكن أن يتضمّن طلب
batchPushما يصل إلى 1,000 تعديل.
أمثلة
تعديل إعلان نصي موسّع
لنفترض أنّك بحاجة إلى تعديل الوقت المقدَّر لوصول خدمة توصيل بشكل عاجل من 30-60 دقيقة إلى 60-90 دقيقة. يجب أن يتضمّن التعديل رمز JSON الخاص بكيان الخدمة بأكمله.
لنفترض أنّ لديك كيان خدمة يبدو على النحو التالي:
{ "service": { "service_id": "service/entity002", "service_type": "DELIVERY", "parent_entity_id": "entity002", "lead_time": { "min_lead_time_duration": "600s", "max_lead_time_duration": "1800s" }, "action_link_id": "delivery_link/entity002" } }
في ما يلي التعديل في الوقت الفعلي باستخدام HTTP POST (تمت طباعة نص الطلب بشكل منسّق لتسهيل القراءة):
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "3600" }, "max_lead_time_duration" : { "seconds": "5400" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }] }
تعديل عناصر متعددة
لتعديل كيانات مطاعم متعددة في طلب واحد من واجهة برمجة التطبيقات، أدرِج سجلات متعددة في حقل proto_record الخاص بنص الطلب.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "1800" }, "max_lead_time_duration" : { "seconds": "3600" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee", "fee_type" : "DELIVERY", "fixed_amount" : { "currency_code" : "USD", "units" : "10", "nanos" : "0" }, "service_ids": ["service/entity002"] } }, "generation_timestamp" : "2023-09-13T17:11:10.750Z" }] }
حذف الكيانات
لحذف عناصر من مستودعك، استخدِم نقطة النهاية DELETE في طلب HTTP POST. يجب أن يتضمّن كل طلب POST المَعلمة PARTNER_ID بالإضافة إلى حمولة JSON التي تحتوي على معرّف العنصر الذي تريد حذفه.
ملاحظة: تأكَّد من أنّ خلاصات البيانات اليومية تتضمّن أيضًا أي تغييرات تم إرسالها من خلال واجهة برمجة التطبيقات لتعديل البيانات في الوقت الفعلي. بخلاف ذلك، سيؤدي إدخال البيانات المجمّعة يوميًا إلى استبدال التغييرات في الوقت الفعلي.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery" } }, "delete_time": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee" } }, "delete_time" : "2023-09-13T17:11:10.750Z" }] }
إضافة كيانات
لا تستخدِم التعديلات في الوقت الفعلي لإضافة كيانات جديدة لأنّ ذلك قد يؤدي إلى عدم اتساق البيانات. بدلاً من ذلك، استخدِم خلاصات الدفعات.
التحقّق من الصحة ورموز الاستجابة لواجهة برمجة التطبيقات
هناك نوعان من عمليات التحقّق التي يتم إجراؤها على طلبات البيانات من واجهة برمجة التطبيقات الخاصة بالتحديث في الوقت الفعلي:
- على مستوى الطلب: تتحقّق عمليات التحقّق هذه من أنّ الحمولة تتّبع المخطّط وأنّ كل
proto_recordيحتوي على الحقلَينidوtype. تتم عمليات التحقّق هذه بشكل متزامن، ويتم عرض النتائج في نص الردّ من واجهة برمجة التطبيقات. يشير رمز الاستجابة 200 ونص JSON فارغ{}إلى أنّ عمليات التحقّق هذه قد اجتازت بنجاح وأنّه تم وضع الكيانات في هذا الطلب في قائمة الانتظار لتتم معالجتها. يعني رمز الاستجابة غير 200 أنّه تعذّر إكمال عملية واحدة أو أكثر من عمليات التحقّق هذه، وسيتم رفض الطلب بالكامل (بما في ذلك جميع الكيانات في الحمولة). على سبيل المثال، إذا كانproto_recordلا يتضمّن@type، يتم عرض استجابة الخطأ التالية:
{ "error": { "code": 400, "message": "Record:{...}", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.DebugInfo", "detail": "[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:... The entity type could not be extracted from the entity value." } ] }
- على مستوى الكيان: يتم التحقّق من صحة كل كيان (proto_record) في الحمولة مقارنةً بالمخطط. لا يتم الإبلاغ عن المشاكل التي يتم رصدها في هذه المرحلة من عملية التحقّق في ردّ واجهة برمجة التطبيقات. يتم تسجيلها فقط في لوحة بيانات إعداد التقارير عن انتهاكات السياسة في الوقت الفعلي ضمن "مركز الإجراءات".
ملاحظة: لا يعني رمز الاستجابة 200 أنّه تم استيعاب جميع الكيانات بنجاح.
حصص واجهة برمجة التطبيقات
تبلغ حصة التعديلات في الوقت الفعلي لواجهة برمجة التطبيقات 1,500 طلب كل 60 ثانية، أو 25 طلبًا في الثانية في المتوسط. عند تجاوز الحصة، تردّ Google برسالة الخطأ التالية:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}للتعامل مع هذه المشكلة، أعِد محاولة إجراء المكالمة مرة أخرى على فترات زمنية أكبر بشكل مضاعف إلى أن تنجح. إذا كنت تستنفد الحصة المخصّصة لك بانتظام، ننصحك بتضمين المزيد من العناصر في طلب واحد من طلبات واجهة برمجة التطبيقات. يمكنك تضمين ما يصل إلى 1,000 كيان في طلب واحد من واجهة برمجة التطبيقات.
آخر المعلومات عن مدد المعالجة
تتم معالجة الجهة المعدَّلة من خلال تعديل في الوقت الفعلي خلال 5 دقائق.