Schritt 5: API-Aktualisierungen in Echtzeit

Aufgrund von neuen Buchungen, Stornierungen und Terminänderungen deiner Händler unterliegt das Inventar in deinem System im Laufe des Tages Schwankungen. Mit APIs für Echtzeitaktualisierungen wird Google über diese Änderungen der Inventarverfügbarkeit informiert. Du kannst sie auch verwenden, um Google über Änderungen an bestehenden Buchungen zu informieren.

API-Aktualisierungen in Echtzeit und Feeds

API-Aktualisierungen in Echtzeit werden verwendet, um Google in Echtzeit über inkrementelle Änderungen der Inventarverfügbarkeit und der Buchungen zu informieren. Zusätzlich solltest du jeden Tag vollständige Verfügbarkeitsfeeds senden, damit Google die aktuelle Informationen zur Verfügbarkeit in deinem System hat. Vollständige Feeds geben eine Übersicht über den aktuellen Status der Inventarverfügbarkeit in deinem System.

Du kannst API-Aktualisierungen nutzen, um alle Informationen zu aktualisieren, die in Feeds bereitgestellt werden, z. B. zu Händlern und Dienstleistungen. Sie werden aber normalerweise nur zum Aktualisieren von Verfügbarkeitsinformationen verwendet.

Erforderliche APIs für Echtzeitaktualisierungen

Echtzeitaktualisierungen über die Availability Replace API

Verwende die Availability Replace API, um die Verfügbarkeit in folgenden Fällen zu aktualisieren:

• Ein Nutzer reserviert einen Slot in deinem System. Er ist also nicht mehr verfügbar.
• Ein Händler ändert seine Verfügbarkeit in deinem System.
• Ein Nutzer reserviert einen Slot über Google. Er ist also nicht mehr verfügbar.
• Eine Reservierung, die über Google vorgenommen wurde, wird in deinem System storniert, 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.
• Ein BatchAvailabilityLookup-Aufruf des Buchungsservers gibt Inventar zurück, das nicht mit dem tatsächlichen Inventar übereinstimmt.

Weitere Informationen findest du unter folgenden Links:

• Anleitung: Echtzeitaktualisierungen strukturieren
• Java-Client-Beispiel für Echtzeitaktualisierungen mit RESTful-Aufrufen
• API-Referenzseite für die Inventaraktualisierung

Booking Notification API – Echtzeitaktualisierung

Über die Booking Notification API wird Google über Aktualisierungen bestehender Buchungen informiert. Wenn du eine Aktualisierung für Stornierungen sendest, schließe nur die wichtigsten Informationen in die Anfrage mit dem updateMask-Abfrageparameter ein. Hier ein Beispiel:

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

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"CANCELED"}

Auf die API zugreifen

Dienstkonto erstellen

Verwende den Tab Anmeldedaten in der Google API Console und erstelle ein Dienstkonto. Speichere den privaten Schlüssel im JSON-Format an einem sicheren Ort. Bei der Kontoerstellung kannst du die Rolle auf „Inhaber“ setzen.

Maps Booking APIs authentifizieren

Authentifiziere nach dem Erstellen des Dienstkontos die folgenden APIs:

• Google Maps Booking API
• Google Maps Booking API (Entwicklerversion)

Eine detaillierte Anleitung findest du hier.

RESTful-Aufrufe verwenden oder die Clientbibliothek herunterladen

Wir empfehlen, RESTful-Aufrufe direkt mit JSON-Nutzlasten an die Maps Booking API zu senden. Weitere Informationen findest du in der Dokumentation zur REST API.

Du kannst auch Clientbibliotheken verwenden, um eine Verbindung zur API herzustellen.

Du kannst zusätzliche Hilfsbibliotheken herunterladen, die die Autorisierung und andere Aspekte von Aufrufen von Google APIs verarbeiten. Sehen Sie sich bei Bedarf diese Beispiele an.

Discovery-Dokument abrufen

Bei einigen Clientbibliotheken (z. B. für Ruby) muss das Discovery-Dokument für die API abgerufen werden, in dem die Methoden und Parameter beschrieben sind.

Verwenden Sie den folgenden Befehl, um das Discovery-Dokument abzurufen:

curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'

Weitere Informationen zum Zugriff auf die API über Ruby findest du unter folgenden Links: Ruby API-Client und Ruby Auth Library.

Autorisierte API-Aufrufe durchführen

Wenn du API-Aufrufe durchführst, lies dir den Abschnitt zu autorisierten API-Aufrufen durch, um dein Dienstkonto mit deinem privaten Schlüssel und dem folgenden OAuth-Bereich zu autorisieren: https://www.googleapis.com/auth/mapsbooking.

API-Kontingente

API-Aktualisierungen ist ein Kontingent von 1.500 Anfragen pro 60 Sekunden zugewiesen. Das entspricht durchschnittlich 25 Anfragen pro Sekunde. Wird das Kontingent überschritten (was passieren kann, wenn du die richtige Google Cloud-Projektnummer nicht in deinem Partner-Portal hinzugefügt hast), erhältst du von Google die folgende Fehlermeldung:

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

Wiederhole den Aufruf in diesem Fall in exponentiell größeren Abständen, bis er erfolgreich ist. Wenn du das Kontingent regelmäßig mit ReplaceServiceAvailability ausschöpfst, kannst du zu BatchReplaceServiceAvailabily wechseln und so die Anzahl der API-Aufrufe reduzieren. Mit dieser Methode kannst du mehrere Dienstleistungen in einem einzigen API-Aufruf aktualisieren.

Sandbox- und Produktionsendpunkte

Über die API kannst du sowohl Sandbox- als auch die Produktionsumgebungen aufrufen. Dazu musst du beide APIs in deinem Google Cloud-Projekt aktiviert haben. Beide APIs verwenden denselben Bereich, haben aber unterschiedliche Endpunkte.

Produktionsendpunkt: https://mapsbooking.googleapis.com/

Sandbox-Endpunkt: https://partnerdev-mapsbooking.googleapis.com/

Hier siehst du anhand eines Java-Beispiels, wie Endpunkte gewechselt werden:

    // This block of code is for OAuth and is the same for prod and sandbox.
    GoogleCredential
      .fromStream(new FileInputStream(...))
      .createScoped(Collections.singleton("https://www.googleapis.com/auth/mapsbooking"))

    // This block of code sets the endpoint. This is what you'd change to connect to the sandbox.
    new GoogleMapsBookingAPI.Builder(...)
      .setApplicationName(...)
      .setRootUrl("https://partnerdev-mapsbooking.googleapis.com/") // you add this to change the endpoint to use partnerdev.
      .build()