Struktura aktualizacji w czasie rzeczywistym

Przypadki użycia aktualizacji w czasie rzeczywistym

Aktualizacje w czasie rzeczywistym muszą być zawsze wydawane w tych sytuacjach:

  • gdy użytkownik anuluje rezerwację w Twoim systemie i miejsce staje się dostępne;
  • Gdy użytkownik zarezerwuje miejsce w Centrum działań, a miejsce jest już niedostępne.
  • Gdy rezerwacja dokonana w Centrum działań zostanie anulowana po Twojej stronie, na przykład przez sprzedawcę. Musisz zaktualizować rezerwację i dostępność, ponieważ pierwotny przedział czasowy jest znowu dostępny.

Jeśli dodatkowo wdrożysz specyfikację Availability Replace RTU, aktualizacje w czasie rzeczywistym powinny być wydawane w tych sytuacjach:

  • Gdy sprzedawca zmieni harmonogram (dostępność) w Twoim systemie.
  • Gdy użytkownik zarezerwuje rezerwację w Twoim systemie, a slot dostępności nie jest już dostępny.
  • Jeśli używasz starszej metody integracji z CheckAvailability, wywołanie serwera rezerwacji CheckAvailability zwraca zasoby reklamowe, które nie odpowiadają rzeczywistym zasobom.

Nie wszystkie wywołania interfejsu API Rezerwacji w Mapach są wymagane. Wymagane są te informacje:

W zależności od typu integracji mogą być dostępne lub wymagane te opcje:

Aktualizacja rezerwacji RTU

Jeśli w Twoim systemie wprowadzono zmiany w rezerwacji w Centrum działań (np. anulowanie lub modyfikacja), musisz wysłać wiadomość notification.partners.bookings.patch (BookingNotification.UpdateBooking).

Pola, które można modyfikować

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

Przykład anulowania

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

Dostępność Zastąp RTU

Dostępne są 2 rodzaje metod zastępowania, które umożliwiają aktualizowanie dostępności:

  • Zastępowanie zbiorcze (InventoryUpdate.BatchServiceAvailability): całkowicie zastępuje dane o dostępności dla wielu sprzedawców i usług.
    • Uwaga: to wywołanie zbiorcze nie gwarantuje wykonania operacji w ramach jednej transakcji. Zwrócone zostaną tylko zaktualizowane sloty dostępności.
  • Pojedyncze zastąpienie (InventoryUpdate.ReplaceServiceAvailability): całkowicie zastępuje dostępność dla jednego sprzedawcy i usługi.

Więcej informacji znajdziesz w tym dokumentie.

Aktualizacje w czasie rzeczywistym muszą używać tej samej struktury dostępności co dane przesyłane w plikach danych. Muszą użyć jednej z tych opcji:

  • spotsOpen
  • recurrence

Wybieranie metody zastępowania do wywołania

Aby określić, która metoda zastępowania jest najbardziej odpowiednia, skorzystaj z tego przewodnika:

  • Czy problem dotyczy wielu sprzedawców? Na przykład można zastąpić dostępność wielu sprzedawców w jednym żądaniu.
  • Twój system będzie od czasu do czasu synchronizować się z Google, wysyłając wszystkie zmiany dostępności od ostatniej aktualizacji (nie zalecane).
    • Zastępowanie zbiorcze
    • Uwaga: spodziewamy się, że odpowiedź RTU dotycząca zapasów zostanie wysłana w ciągu 5 minut od momentu wprowadzenia przez Ciebie aktualizacji. Dlatego aktualizacje należy sprawdzać i wysyłać co najmniej co 5 minut.
  • Żadne z tych rozwiązań nie pasuje do Twojej sytuacji lub chcesz zaktualizować tylko jednego sprzedawcę i jedną usługę?
    • Single Replace
    • Uwaga: możesz użyć wielu wywołań z pojedynczą wymianą, aby emulować wywołanie z wymianą zbiorczą, ale wydajniej będzie użyć pojedynczego wywołania z wymianą zbiorczą.

Aktualizacje w czasie rzeczywistym: otwarty format Spots

Ważne jest, aby używać tego samego formatu w plikach danych, na serwerze rezerwacji i w przypadku aktualizacji w czasie rzeczywistym.

Fragment kodu kanału spots_open wygląda tak:

Krótki opis pliku danych

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

W przypadku interfejsu Inventory Update API format treści żądania zastąpienia, gdy rezerwacja została dokonana na godzinę 15:30:

Zastąp fragment kodu aktualizującego w czasie rzeczywistym

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

Oto przykład tego, czego oczekujemy w następnym pliku danych dziennych, jeśli nowy slot o godzinie 15:30 zostanie zarezerwowany:

Krótki opis pliku danych

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

Aktualizacje w czasie rzeczywistym: format powtarzania

Ważne jest, aby używać tego samego formatu w plikach danych, na serwerze rezerwacji i w przypadku aktualizacji w czasie rzeczywistym.

Plik danych, który używa powtórzeń, wygląda tak:

Krótki opis pliku danych

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

W przypadku interfejsu Inventory Update API format treści żądania zastępczego, gdy rezerwacja została dokonana na godzinę 15:30, wygląda tak:

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

Oto przykład tego, czego oczekujemy w następnym pliku danych dziennych. Pamiętaj, że jest to dostępność całej usługi dla tego sprzedawcy, w tym wszystkich jego poprzednich i nowych schedule_exceptions:

Krótki opis pliku danych

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

Kiedy przesyłać aktualizacje w czasie rzeczywistym

Aktualizacje w czasie rzeczywistym powinny być wysyłane bez przerwy, gdy tylko zmienia się dostępność. Jest to dodatkowy, kompleksowy plik danych o dostępności, który należy przesyłać raz dziennie, aby zapewnić synchronizację dostępności między Twoimi systemami a systemami Google.