Echtzeitaktualisierungen strukturieren

Anwendungsfälle für Echtzeit-Updates

In den folgenden Fällen müssen immer Aktualisierungen in Echtzeit erfolgen:

• Wenn ein Nutzer eine Reservierung in Ihrem System storniert und der Slot wieder verfügbar wird.
• Wenn ein Nutzer über das Aktionscenter eine Reservierung vornimmt und der Verfügbarkeitsslot nicht mehr verfügbar ist.
• Wenn eine Reservierung, die über das Actions Center vorgenommen wurde, in Ihrem System storniert wird, z. B. direkt vom Händler. Du musst die Buchung und die Verfügbarkeit aktualisieren, weil der ursprüngliche Slot jetzt wieder verfügbar ist.

Wenn Sie außerdem die Echtzeitaktualisierung für „AvailabilityReplace“ implementieren, sollten Echtzeitaktualisierungen in den folgenden Fällen ausgegeben werden:

• Wenn ein Händler seinen Zeitplan (Verfügbarkeit) in Ihrem System ändert.
• Wenn ein Nutzer einen Slot in Ihrem System reserviert und der verfügbare Slot nicht mehr verfügbar ist.
• Wenn Sie eine alte Integration mit CheckAvailability verwenden, gibt ein CheckAvailability-Aufruf des Buchungsservers Inventar zurück, das nicht mit dem tatsächlichen Inventar übereinstimmt.

Nicht alle Maps Booking API-Aufrufe sind erforderlich. Folgende Angaben sind erforderlich:

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

Je nach Art der Integration sind möglicherweise auch die folgenden Optionen verfügbar oder erforderlich:

• inventory.partners.availability.replace (InventoryUpdate.BatchServiceAvailability) ODER inventory.partners.merchants.services.availability.replace (InventoryUpdate.ReplaceServiceAvailability)

UpdateBooking – Echtzeitaktualisierung

Wenn eine Aktualisierung an einer Actions Center-Buchung in Ihrem System vorgenommen wurde (z.B. Stornierung oder Änderung), muss eine notification.partners.bookings.patch (BookingNotification.UpdateBooking) gesendet werden.

Änderbare Felder

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

Hinweis:name, merchant_id, service_id und das spezifische Feld, das sich ändert, müssen angegeben werden. Alle anderen sind optional. Unter Umständen können sich mehrere Felder gleichzeitig ändern. In diesem Fall müssen Sie die Felder in updateMask durch Kommas trennen (z. B. updateMask=partySize,startTime).

Beispiel für die Kündigung

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

Echtzeitaktualisierung für "AvailabilityReplace"

Hinweis:Die Echtzeitaktualisierung für „AvailabilityReplace“ ist nur für bestimmte Arten der Integration verfügbar bzw. erforderlich. Wenn Sie sich nicht sicher sind, wenden Sie sich bitte an Ihren Google-Ansprechpartner.

Es gibt zwei Arten von Ersetzungsmethoden, mit denen Sie Ihre Verfügbarkeit aktualisieren können:

• Batch Replace (InventoryUpdate.BatchServiceAvailability): Ersetzt die Verfügbarkeitsdaten für mehrere Händler und Dienste vollständig.
  • Hinweis: Dieser Batch-Aufruf garantiert nicht die Atomarität. Nur erfolgreich aktualisierte verfügbare Slots werden zurückgegeben.
• Einzelvorgang zum Ersetzen (InventoryUpdate.ReplaceServiceAvailability): Ersetzt die Verfügbarkeit für einen einzelnen Händler und Dienst vollständig.

Weitere Informationen finden Sie in der Referenz.

Für Echtzeit-Updates muss dieselbe Verfügbarkeitsstruktur wie für die Daten verwendet werden, die über Feeds gesendet werden. Sie müssen eine der folgenden Optionen verwenden:

• spotsOpen
• recurrence

Ersatzmethode zum Aufrufen auswählen

Anhand der folgenden Anleitung können Sie entscheiden, welche Ersetzungsmethode besser geeignet ist:

• Sind mehrere Händler betroffen? So können Sie beispielsweise die Verfügbarkeit für mehrere Händler in einer Anfrage ersetzen.
  • Batch-Ersetzung
• Ihr System wird von Zeit zu Zeit mit dem von Google synchronisiert, indem alle Verfügbarkeitsänderungen seit dem letzten Update gesendet werden (nicht empfohlen).
  • Batch-Ersetzung
  • Hinweis: Wir erwarten, dass die RTU für das Inventar innerhalb von 5 Minuten nach einer Aktualisierung auf Ihrer Seite gesendet wird. Sie sollten also mindestens alle 5 Minuten nach Updates suchen und diese senden.
• Keine dieser Situationen trifft zu oder Sie müssen nur einen einzelnen Händler und Dienst aktualisieren?
  • Einzelner Ersatz
  • Hinweis: Sie können mehrere einzelne Ersetzungsaufrufe verwenden, um einen Batch-Ersetzungsaufruf zu emulieren. Es wäre jedoch effizienter, einen einzelnen Batch-Ersetzungsaufruf zu verwenden.

Echtzeitupdates: Spots Open Format

Es ist wichtig, dass Sie in allen Feeds, auf dem Buchungsserver und bei Echtzeitupdates dasselbe Format verwenden.

Ein spots_open-Feed-Snippet sieht so aus:

Feed-Snippet

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

Für die Inventory Update API ist das Format des Anfragetexts für das Ersetzen, wenn ein Slot um 15:30 Uhr gebucht wird:

Snippet für Echtzeitaktualisierungen ersetzen

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

Hier ist ein Beispiel dafür, was wir im nächsten täglichen Feed erwarten, wenn ein neuer Slot um 15:30 Uhr gebucht wird:

Feed-Snippet

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

Hinweis:Wenn keine Verfügbarkeit mehr vorhanden ist (spots_open ist 0), gibt es zwei mögliche Formate zum Senden der Ersetzungsanfrage für die Inventory API.

• Explizite Angabe:Dies ist die empfohlene Methode, wenn Sie spots_total > 1 haben.

    {
      "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": "0",
              "spotsTotal": "2",
              "availabilityTag": "1000001"
            }
          ]
        }
      ]
    }

• Leere Spezifikation:Diese Option wird nur empfohlen, wenn spots_total = 1 für die meisten Händler und Dienste gilt.

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

Echtzeitupdates: Wiederholungsformat

Es ist wichtig, dass Sie in allen Feeds, auf dem Buchungsserver und bei Echtzeitupdates dasselbe Format verwenden.

Ein Feed, in dem Wiederholung verwendet wird, sieht so aus:

Feed-Snippet

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

Für die Inventory Update API sieht das Format des Anfragetexts für die Ersetzungsanfrage, wenn ein Slot um 15:30 Uhr gebucht wird, so aus:

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

Hinweis:Echtzeit-Updates sollten alle schedule_exceptions für die gebuchten Zeiträume enthalten. Der Grund dafür ist, dass die API-Methode die Verfügbarkeit für diesen bestimmten Dienst und Händler ersetzt. Wenn Sie sie durch etwas anderes ersetzen, müssen Sie alle Informationen zur Verfügbarkeit dieses Dienstes angeben und alle gebuchten Zeitblöcke einschließen.

Hier ein Beispiel dafür, was im nächsten täglichen Feed erwartet wird. Beachten Sie, dass es sich um die gesamte Verfügbarkeit des Dienstes für diesen Händler und alle seine bisherigen und neuen schedule_exceptions handelt:

Feed-Snippet

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

Echtzeitupdates senden

Aktualisierungen in Echtzeit sollten kontinuierlich gesendet werden, wenn sich die Verfügbarkeit ändert. Zusätzlich zu einem umfassenden Verfügbarkeitsfeed, der einmal täglich eingereicht werden sollte, damit die Verfügbarkeit zwischen Ihrem und dem Google-System synchronisiert wird.