تحديث في الوقت الفعلي

تحديثات في الوقت الفعلي

ويُقصد بقيم RTU في المقام الأول التعديلات التي لا يمكنك توقّعها، مثل حالات الإغلاق الطارئة أو البيانات الوصفية التي تتغيّر بشكلٍ دوري (مثل الوقت المقدر للوصول). إذا لم تكن تريد أن تظهر التغييرات فورًا، يمكنك استخدام ميزة عرض الخلاصة المجمّعة بدلاً من ذلك. لا تتم معالجة التعديلات في الوقت الفعلي خلال أكثر من خمس دقائق.

إعداد Google Cloud Platform

  1. ابدأ إعداد مشروع Google Cloud Platform. يجب توفّر مشروع Google Cloud Platform للوصول إلى RTU API.
    • منح الإذن بتعديل المحتوى food-support@google.com
    • يُرجى إبلاغ جهة التواصل (POC) في Google برقم مشروع Google Cloud Platform.ويجب ربط مشروع Google Cloud Platform بحسابك في "مركز الإجراءات" لكي يتم تفعيل التعديلات في الوقت الفعلي.
    • تمكين واجهة برمجة تطبيقات حجز الخرائط:
      • في Google Cloud Platform، انتقِل إلى واجهات برمجة التطبيقات الخدمات > المكتبة.
      • ابحث عن "Google Maps Booking API".
        تحديد موقع واجهات برمجة تطبيقات الحجز في خرائط Google
      • ابحث عن النسخة الافتراضية من Sandbox ("Google Maps Booking API (Dev)") وانقر على تفعيل.
      • ابحث عن مثيل الإنتاج ("واجهة برمجة تطبيقات الحجز في خرائط Google") وانقر على تفعيل.
        تفعيل واجهة برمجة تطبيقات الحجز في خرائط Google
      • أنشِئ حساب خدمة بدور محرِّر لمشروع Google Cloud Platform. لمزيد من التفاصيل، راجِع إعداد حساب الخدمة.
      • تأكَّد من تحميل خلاصات مجمّعة إلى البيئة التي تعمل فيها على إجراء تعديلات في الوقت الفعلي.
      • بالنسبة إلى مصادقة واجهة برمجة التطبيقات، ننصحك بتثبيت مكتبة برامج Google باللغة التي تختارها. استخدام "https://www.googleapis.com/auth/mapsbooking" كنطاق OAuth. وتستخدم عيّنات التعليمات البرمجية أدناه هذه المكتبات. وبخلاف ذلك، عليك التعامل مع عمليات تبادل الرموز المميّزة يدويًا كما هو موضّح في استخدام OAuth 2.0 للوصول إلى Google APIs.

إعداد حساب الخدمة

يجب أن يكون لديك حساب خدمة لإرسال طلبات HTTPS تمت مصادقتها إلى Google APIs، مثل واجهة برمجة التطبيقات للتحديثات في الوقت الفعلي.

لإعداد حساب خدمة، عليك إجراء ما يلي:

  1. الوصول إلى وحدة تحكّم Google Cloud Platform
  2. يتضمّن حسابك في مركز الإجراءات أيضًا مشروعًا على Google Cloud مرتبطًا به. اختَر المشروع إذا لم يكن سبق لك تحديده.
  3. انقر على حسابات الخدمة في القائمة اليمنى.
  4. انقر على إنشاء حساب الخدمة.
  5. أدخِل اسمًا لحساب الخدمة وانقر على إنشاء.
  6. في تحديد دور، اختَر مشروع >. المحرِّر.
  7. انقر على متابعة.
  8. اختياري: أضِف مستخدمين لمنحهم إذن الوصول إلى حساب الخدمة وانقر على تم.
  9. انقر على المزيد > أنشئ مفتاحًا لحساب الخدمة الذي أنشأته للتو.
  10. اختَر JSON كتنسيق وانقر على إنشاء.
  11. بعد إنشاء زوج المفتاح العام/الخاص، يمكنك تنزيله على جهازك.

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

تتيح واجهة برمجة التطبيقات للتحديثات في الوقت الفعلي نوعين من العمليات: التحديث والحذف. لا يمكن إضافة كيانات جديدة عبر واجهة برمجة التطبيقات الخاصة بالتحديث في الوقت الفعلي. يمكن تجميع التحديثات في الوقت الفعلي في حال تضمين تعديلات متعددة في طلب واجهة برمجة تطبيقات واحد. يمكنك تجميع ما يصل إلى 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 في مركز الإجراءات ضمن صفحة الحساب والمستخدمون، كما هو موضّح في لقطة الشاشة أدناه.

رقم تعريف الشريك على "بوابة الشريك"

استنادًا إلى 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: النسخة الأوّلية أو JSON للكيان ServiceData الذي تعمل على تعديله
  • UPDATE_TIMESTAMP: احرص على تضمين الطابع الزمني لوقت إنشاء الكيان في أنظمتك الخلفية. وفي حال عدم تضمين هذا الحقل، سيتم ضبطه على الوقت الذي تتلقّى فيه Google الطلب. عند تعديل كيان من خلال طلب batchPush، يتم استخدام الحقل generation_timestamp لتحديد نُسخ الكيان. شاهد التنسيق المتوقع للقيم الزمنية في مخطط المستودع العلائقي.
  • يجب ألا يتجاوز حجم نص الحمولة 5 ميغابايت.
  • أزِل المسافات البيضاء لتصغير الحجم.
  • يمكن إدخال ما يصل إلى 1,000 تعديل في طلب batchPush.

أمثلة

تعديل الوقت المقدّر للوصول

لنفترض أنك بحاجة بشكل عاجل إلى تعديل الوقت المقدّر للوصول لخدمة توصيل من 30 إلى 60 دقيقة إلى 60 دقيقة. يجب أن يحتوي التحديث على ملف 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) في الحمولة وفقًا للمخطط. إنّ المشاكل التي تحدث في هذه المرحلة من عملية التحقّق لا تظهر في استجابة واجهة برمجة التطبيقات. ولا يتم تسجيلها إلا في لوحة بيانات إعداد تقارير RTU في "مركز الإجراءات".

ملاحظة: لا يعني رمز الاستجابة 200 أنّه تم نقل بيانات جميع العناصر بنجاح.

حصص واجهة برمجة التطبيقات

تبلغ حصة تحديثات واجهة برمجة التطبيقات في الوقت الفعلي 1,500 طلب كل 60 ثانية، أو 25 طلبًا في الثانية في المتوسط. عند تجاوز إحدى الحصص، تستجيب Google برسالة الخطأ التالية: 

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

لمعالجة هذا الأمر، يمكنك إعادة محاولة الاتصال مرة أخرى على فترات زمنية أكبر بشكل كبير إلى أن ينجح الاتصال. إذا كنت تستنفد الحصة بانتظام، ننصحك بتضمين المزيد من العناصر في طلب بيانات واحد من واجهة برمجة التطبيقات. يمكنك تضمين ما يصل إلى 1,000 عنصر في طلب بيانات واحد من واجهة برمجة التطبيقات.

جارٍ معالجة التعديلات في الوقت الفعلي

تتم معالجة كيان يتم تعديله من خلال تعديل في الوقت الفعلي في غضون 5 دقائق.

السابق
تتبُّع الإحالات الناجحة