ميزة "النتائج في الوقت الفعلي" في "البنية"

حالات استخدام التحديثات في الوقت الفعلي

يجب دائمًا إصدار "تعديلات في الوقت الفعلي" في الحالات التالية:

  • عندما يلغي المستخدم حجزًا في نظامك، ويصبح الموعد متاحًا
  • عندما يحجز المستخدم موعدًا من خلال "مركز الإجراءات"، ولم يعُد خانة المواعيد المتاحة متوفرة.
  • عند إلغاء حجز تم إجراؤه من خلال "مركز الإجراءات" من جهتك، مثلاً من خلال التاجر مباشرةً عليك تعديل الحجز وتعديل معلومات التوفّر لأنّ خانة الموعد الأصلية أصبحت متاحة من جديد.

بالإضافة إلى ذلك، في حال تنفيذ استبدال المحتوى المتوفّر في الوقت الفعلي، يجب إصدار "التعديلات في الوقت الفعلي" في الحالات التالية:

  • عندما يغيّر التاجر جدوله الزمني (مدى التوفّر) على نظامك
  • عندما يحجز المستخدم موعدًا في نظامك ولم يعُد خانة المواعيد المتاحة متوفرة.
  • إذا كنت تستخدم عملية دمج لنظام قائم مع CheckAvailability، عندما يعرض طلب CheckAvailability من خادم الحجز مستودعًا لا يتطابق مع المستودع الفعلي.

ليست جميع طلبات البيانات من واجهة برمجة التطبيقات Maps Booking API مطلوبة. يجب استيفاء المتطلبات التالية:

اعتمادًا على نوع الدمج، قد يتوفّر أو يكون مطلوبًا ما يلي أيضًا:

تعديل وحدة RTU الخاصة بالحجز

في حال إجراء تعديل على حجز في "مركز الإجراءات" (مثل الإلغاء أو التعديل) على نظامك، يجب إرسال notification.partners.bookings.patch (BookingNotification.UpdateBooking).

الحقول القابلة للتعديل

  • status
  • startTime
  • duration
  • partySize
  • paymentInformation.prepaymentStatus

مثال على الإلغاء

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{
  "name": "partners/<PARTNER_ID>/bookings/<BOOKING_ID>",
  "merchantId": "10001",
  "serviceId": "1001",
  "startTime": "2025-01-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

استبدال معلومات التوفّر في RTU

يتوفّر نوعان من طرق الاستبدال لتعديل معلومات التوفّر:

  • الاستبدال المجمّع (InventoryUpdate.BatchServiceAvailability): يستبدل هذا الخيار بيانات التوفّر الخاصة بتجّار وخدمات متعددة بشكل كامل.
    • ملاحظة: لا يضمن هذا الاتصال المجمّع الذرية. سيتم عرض خانات التوفّر التي تم تعديلها بنجاح فقط.
  • الاستبدال الفردي (InventoryUpdate.ReplaceServiceAvailability): يستبدل هذا الخيار بيانات التوفّر لتاجر واحد وخدمة واحدة بشكل كامل.

يُرجى الرجوع إلى المرجع التالي للحصول على مزيد من التفاصيل.

يجب أن تستخدم التعديلات في الوقت الفعلي بنية بيانات التوفّر نفسها التي تستخدمها البيانات المرسَلة من خلال الخلاصات. يجب استخدام أحد ما يلي:

  • spotsOpen
  • recurrence

اختيار طريقة استبدال لاستدعائها

استخدِم الدليل التالي لمساعدتك في تحديد طريقة الاستبدال الأنسب لك:

  • هل تأثّر العديد من التجّار؟ على سبيل المثال، استبدال معلومات التوفّر لعدة تجار في طلب واحد
  • سيتم من وقت لآخر مزامنة نظامك مع نظام Google من خلال إرسال جميع التغييرات التي طرأت على مدى التوفّر منذ آخر تحديث (لا يُنصح بذلك).
    • الاستبدال المجمّع
    • ملاحظة: نتوقّع إرسال "وحدة وقت التشغيل" الخاصة بالمستودع الإعلاني في غضون 5 دقائق من حدوث أي تعديل من جهتك. لذا، عليك التحقّق من أي تحديثات وإرسالها كل 5 دقائق على الأقل.
  • لا ينطبق أيّ من هذه الشروط أو تحتاج فقط إلى تعديل تاجر واحد وخدمة واحدة؟
    • الاستبدال الفردي
    • ملاحظة: يمكنك استخدام عدّة طلبات استبدال فردية لمحاكاة طلب استبدال مجمّع، ولكن سيكون من الأفضل استخدام طلب استبدال مجمّع واحد

تحديثات في الوقت الفعلي: تنسيق "جلسات سريعة"

من المهم استخدام التنسيق نفسه في جميع الخلاصات وخادم الحجز والتعديلات في الوقت الفعلي.

يبدو spots_open مقتطف الخلاصة على النحو التالي:

مقتطف الخلاصة

   "availability": [
          {
            "merchant_id": "1001",
            "service_id": "12310",
            "spots_open": 2,
            "spots_total": 2,
            "start_sec": 1735831800, # January 02, 2025 15:30:00
            "duration_sec": 1800,
            "availabilityTag": "1000001"
          }
    ]

بالنسبة إلى Inventory Update API، إليك تنسيق نص طلب الاستبدال عندما يتم حجز فترة زمنية تبدأ في الساعة 3:30 مساءً:

استبدال مقتطف "النتائج في الوقت الفعلي"

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2025-01-02T15:01:23.045123456Z",
        "endTimeRestrict": "2025-01-02T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2025-01-02T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "spotsTotal": "2",
            "availabilityTag": "1000001"
          }
        ]
      }
    ]
  }

في ما يلي مثال على ما نتوقّعه في الخلاصة اليومية التالية، في حال تم حجز فترة زمنية جديدة في الساعة 3:30 مساءً:

مقتطف الخلاصة

"availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 2,
          "start_sec": 1735831800, # January 02, 2025 15:30:00
          "duration_sec": 1800,
          "availabilityTag": "1000001"
        }
      ]

التحديثات في الوقت الفعلي: تنسيق التكرار

من المهم استخدام التنسيق نفسه في جميع الخلاصات وخادم الحجز والتعديلات في الوقت الفعلي.

تبدو الخلاصة التي تستخدم التكرار على النحو التالي:

مقتطف الخلاصة

  "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            }
          ],
        }
      ]

بالنسبة إلى Inventory Update API، يكون تنسيق نص طلب الاستبدال عند حجز فترة زمنية في الساعة 3:30 مساءً على النحو التالي:

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2018-10-30T15:01:23.045123456Z",
        "endTimeRestrict": "2018-10-30T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2018-10-30T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "scheduleException": [
             {
                "timeRange": {
                  "startTime": "2018-10-30T12:30:00.00Z",
                  "endTime": "2018-10-30T13:00:00.00Z"
                }
              },
              {
                "timeRange": {
                  "startTime": "2018-10-30T15:30:00.00Z",
                  "endTime": "2018-10-30T16:00:00.00Z"
                }
              }
            ]
          }
        ]
      }
    ]
  }

في ما يلي مثال على ما هو متوقّع في خلاصة اليوم التالي. يُرجى العِلم أنّها تشير إلى مدى توفّر الخدمة بالكامل لهذا التاجر، وجميع schedule_exceptions السابقة والجديدة:

مقتطف الخلاصة

   "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            },
            {
              "time_range": {
                "begin_sec": 1540913400, # October 30, 2018 3:30:00 PM
                "end_sec": 1540915200 # October 30, 2018 4:00:00 PM
              }
            }
          ],
        }
      ]

حالات إرسال التعديلات في الوقت الفعلي

يجب إرسال الإشعارات في الوقت الفعلي بشكل مستمر عند حدوث تغييرات في مدى التوفّر. يُضاف ذلك إلى خلاصة شاملة حول مدى التوفّر يجب إرسالها مرة واحدة يوميًا لضمان مزامنة معلومات التوفّر بين أنظمتك وأنظمة Google.