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

تنظيم بنية التعديلات في الوقت الفعلي

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

يجب أن يتم إصدار التحديثات في الوقت الفعلي دائمًا في السيناريوهات التالية:

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

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

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

ليست كل طلبات البيانات للحجز عبر "خرائط Google" مطلوبة. ما يلي إلزامي:

notification.partners.bookings.patch (BookingNotification.UpdateBooking)

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

inventory.partners.availability.replace (InventoryUpdate.BatchServiceAvailability) أو inventory.partners.merchants.services.availability.replace (InventoryUpdate.ReplaceServiceAvailability)

تعديل RTU للحجز

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

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

status
startTime
duration
partySize
paymentInformation.prepaymentStatus

ملاحظة: يجب تحديد name وmerchant_id وservice_id والحقل المحدّد الذي يتم تغييره. وجميع الحقول الأخرى اختيارية. في بعض الحالات، يمكن أن تتغيّر عدة حقول في الوقت نفسه، وفي هذه الحالة، يمكنك الفصل بين الحقول في updateMask (مثل updateMask=partySize,startTime).

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

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": "2014-10-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

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

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

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

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

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

spotsOpen
recurrence

يُرجى مراجعة دليل بنية مدى التوفّر لتحديد التنسيق الأفضل بالنسبة إليك.

اختيار طريقة استبدال للاتصال

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

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

تحديثات في الوقت الفعلي: تنسيق Open Spots

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

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

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

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

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

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

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
        "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2014-10-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": 1412263800, # October 02, 2014 15:30:00
          "duration_sec": 1800,
          "availabilityTag": "1000001"
        }
      ]

ملاحظة: في حال عدم توفر المزيد من مدى التوفّر (spots_open هو 0)، يتوفّر تنسيقان محتملان لإرسال طلب الاستبدال لواجهة برمجة تطبيقات المستودع.

المواصفات الصريحة: هذه هي الطريقة الموصى بها إذا كان لديك spots_total > 1

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

مواصفات فارغة: لا يُنصح باستخدام هذه السمة إلا إذا كانت spots_total = 1 لمعظم التجّار والخدمات.

  {
  "extendedServiceAvailability": [
    {
      "merchantId": "1001",
      "serviceId": "12310",
      "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
      "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
      "availability": [
        {}
      ]
    }
  ]
}

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

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

الخلاصة التي تستخدم التكرار تبدو كما يلي:

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

  "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
              }
            }
          ],
        }
      ]

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

في ما يلي مثال على ما هو متوقع في الخلاصة اليومية التالية. ملاحظة: هذه السمة هي مدى توفّر الخدمة بالكامل لذلك التاجر، وجميع خدمات 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.