تهدف رسائل RTU في المقام الأول إلى إرسال آخر المعلومات التي لا يمكنك توقّعها، مثل عمليات الإغلاق في حالات الطوارئ أو البيانات الوصفية التي تتغيّر بشكل دوري (مثل أوقات الوصول المقدَّرة). إذا لم يكن التغيير بحاجة إلى أن يظهر على الفور، يمكنك استخدام عملية نقل الخلاصة المجمّعة بدلاً من ذلك. تتم معالجة التعديلات في الوقت الفعلي في غضون خمس دقائق كحد أقصى.
إعداد Google Cloud Platform
- إعداد مشروع على Google Cloud Platform يجب إنشاء مشروع على Google Cloud Platform للوصول إلى واجهة برمجة التطبيقات RTU API.
- منح إذن الوصول إلى المحرِّر food-support@google.com
- أطلِع جهة التواصل المعيّنة لك في Google على رقم مشروع GCP.يجب أن يكون مشروعك على GCP مرتبطًا بحسابك على "مركز الإجراءات" لكي تعمل ميزة "التعديلات في الوقت الفعلي".
- تفعيل Maps Booking API:
- في Google Cloud Platform، انتقِل إلى APIs & Services (واجهات برمجة التطبيقات والخدمات) > Library (المكتبة).
- ابحث عن "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 كتنسيق وانقر على إنشاء.
- بعد إنشاء زوج المفتاح العام/الخاص الجديد، نزِّله على جهازك.
العمل مع واجهة برمجة التطبيقات
تتيح واجهة برمجة التطبيقات Real-time updates API نوعَين من العمليات: التعديل والحذف. لا تتوفّر إمكانية إضافة كيانات جديدة من خلال واجهة برمجة التطبيقات لتعديل البيانات في الوقت الفعلي. يمكن تجميع التعديلات في الوقت الفعلي إذا أدرجت تعديلات متعددة في طلب واحد من واجهة برمجة التطبيقات. يمكنك تجميع ما يصل إلى 1,000 تعديل في طلب بيانات واحد من واجهة برمجة التطبيقات. ننصحك باستخدام نهج يستند إلى عامل تشغيل لإرسال التعديلات عبر RTU (أي عند حدوث تغيير في البيانات في نظامك، يتم تشغيل تعديل في الوقت الفعلي إلى Google) بدلاً من نهج يستند إلى معدّل تكرار (أي كل X دقيقة يتم فحص نظامك بحثًا عن التغييرات) إذا أمكن.
تعمل واجهة برمجة التطبيقات لميزة "التعديلات في الوقت الفعلي" في كلّ من بيئة المحاكاة وبيئة الإنتاج. تُستخدَم بيئة الاختبار التجريبي لاختبار طلبات واجهة برمجة التطبيقات وبيئة الإنتاج لتعديل المحتوى المرئي لمستخدمي ميزة "الطلب من خلال تجربة سلسة".
- وضع الحماية -
partnerdev-mapsbooking.googleapis.com - الإنتاج -
mapsbooking.googleapis.com
نقاط النهاية
تعرِض واجهة برمجة التطبيقات "التعديلات في الوقت الفعلي" نقطتَي نهاية لمعالجة الطلبات الواردة لتعديل المستودع:
- تعديل -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - حذف -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
يمكن العثور على المَعلمة PARTNER_ID في مركز الإجراءات في صفحة الحساب والمستخدِمون، كما هو موضّح في لقطة الشاشة أدناه.
على سبيل المثال، من لقطة الشاشة أعلاه، إذا كانت قيمة PARTNER_ID هي 10000001، ستظهر عناوين URL الكاملة لإرسال طلبات واجهة برمجة التطبيقات في وضع المحاكاة ووضع الإنتاج على النحو الموضّح في الأمثلة أدناه.
تعديل وضع الحماية
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Sandbox DELETE
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 في طلب POST عبر بروتوكول HTTP. يجب أن يتضمّن كل طلب 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 دقائق.