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

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

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

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

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

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

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

ليست كل طلبات البيانات من Maps Booking API مطلوبة. المتطلبات التالية إلزامية:

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

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

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

تعديل مهلة النقل في الوقت الفعلي للحجز

في حال إجراء تعديل على حجز في "مركز الإجراءات" (مثلاً تم إلغاؤه أو تعديله) على نظامك، يجب إرسال 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 دقائق على الأقل.
ألا ينطبق أي مما يلي؟
- استبدال فردي
- ملاحظة: يمكنك استخدام عدة طلبات استبدال فردية لمحاكاة استدعاء استبدال مُجمَّع، ولكن سيكون من الأكثر فعالية استخدام طلب استبدال مجمّع واحد.

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

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

يبدو مقتطف خلاصة 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)، هناك تنسيقان محتمَلان لإرسال طلب الاستبدال لواجهة برمجة التطبيقات Inventory API.

المواصفات الصريحة: هذه هي الطريقة التي ننصح بها إذا كان لديك 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 وأنظمة Google.