تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

إعداد Google Cloud Platform

إعداد مشروع Google Cloud Platform يجب توفّر مشروع Google Cloud Platform للوصول إلى واجهة برمجة تطبيقات RTU.
- منح الإذن بتعديل المحتوى food-support@google.com
- يُرجى إبلاغ جهة التواصل المعيّنة لك في Google برقم مشروع Google Cloud Platform.يجب ربط مشروع Google Cloud Platform بحسابك على "مركز الإجراءات" لكي يتم تطبيق التعديلات في الوقت الفعلي.
- تفعيل 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 باللغة التي تختارها. استخدِم "https://www.googleapis.com/auth/mapsbooking" كنطاق OAuth. تستخدم نماذج التعليمات البرمجية المضمنة أدناه هذه المكتبات. وبخلاف ذلك، سيكون عليك التعامل مع تبادل الرموز المميزة يدويًا كما هو موضح في استخدام OAuth 2.0 للوصول إلى Google APIs.

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

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

لإعداد حساب خدمة، عليك اتّباع الخطوات التالية:

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

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

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

وضع الحماية 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

تحديث العناصر

لتعديل الكيانات في المستودع، استخدِم نقطة نهاية التحديث في طلب 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 إلى 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"
	}
}

في ما يلي عملية التحديث في الوقت الفعلي باستخدام طريقة POST لبروتوكول HTTP (تتم طباعة نصوص الطلبات بشكل واضح لتسهيل القراءة):

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

  {
      "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 دقائق.

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