Buchungsserver implementieren

Sie müssen einen Buchungsserver einrichten, damit das Actions Center Rückrufe ausführen kann, um Buchungen in Ihrem Namen zu erstellen und zu aktualisieren.

• Die Standardimplementierung: So kann das Actions Center im Namen des Nutzers Termine, Buchungen und Reservierungen bei dir erstellen.
• Die wartelistenbasierte Implementierung: Sie wird verwendet, wenn du am Pilotprogramm für wartelistenbasierte Buchungen teilnimmst. So können im Actions Center im Namen des Nutzers geschätzte Wartezeiten abgerufen und Wartelisteneinträge erstellt werden. Informationen zum Implementieren eines Buchungsservers für die Warteliste findest du unter Buchungsserver für die Warteliste implementieren.

In der Dokumentation zum Partner-Portal kannst du nachlesen, wie du die Verbindung zu deinen Sandbox- und Produktionsbuchungsservern konfigurierst.

REST API-Schnittstelle implementieren

Implementiere eine REST, damit Google Buchungsserveranfragen über HTTP senden kann.

Dazu richtest du zuerst einen Entwicklungs- oder Sandbox-Buchungsserver ein, der mit der Sandbox-Umgebung des Actions Centers verbunden werden kann. Du solltest erst zu einer Produktionsumgebung wechseln, nachdem der Sandbox-Server vollständig getestet wurde.

Methoden

Für jede Art von Buchungsserver sind unterschiedliche API-Methoden erforderlich. Optional kannst du die Dienstleistungsdefinition im .proto-Format herunterladen, um mit der API-Implementierung zu beginnen. In den folgenden Tabellen findest du die Methoden für jede Implementierung und Links zu den .proto-Formaten.

Standardimplementierung
Dienstleistungsdefinition – Standard: Lade die Dienstleistungsdefinition im .proto-Format herunter.

Methode	HTTP-Anfrage
HealthCheck	GET /v3/HealthCheck/
BatchAvailabilityLookup	POST /v3/BatchAvailabilityLookup/
CreateBooking	POST /v3/CreateBooking/
UpdateBooking	POST /v3/UpdateBooking/
GetBookingStatus	POST /v3/GetBookingStatus/
ListBookings	POST /v3/ListBookings/

API-Ressourcen

Buchung

Die folgenden Ressourcentypen werden in der Standardimplementierung verwendet:

• Slot: Ein verfügbarer Slot (Zeitblock).
• Buchung: Ein Termin für einen Inventar-Slot.

Ablauf: Eine Buchung erstellen

In diesem Abschnitt erfährst du, wie eine Buchung in der Standardimplementierung erstellt wird.

Abbildung 1: Workflow zum Erstellen einer Buchung über einen Slot

Wenn ein Nutzer eine Buchung erstellt, sendet Google dir den Namen, den Nachnamen, die Telefonnummer und die E-Mail-Adresse, die er angegeben hat. Die Funktion „Mit Google reservieren“ kann das Konto des Nutzers in deinem System nicht abrufen. Daher musst du diese Buchung wie eine „Buchung als Gast“ behandeln. Die endgültige Buchung muss mit denen deiner Händler aus deinem Buchungssystem übereinstimmen. Die „Buchung als Gast“ und alternative E-Mail-Adressen werden standardmäßig für nicht bezahlte Buchungen unterstützt.

Sicherheit und Authentifizierung

Die gesamte Kommunikation mit deinem Buchungsserver erfolgt über HTTPS. Daher muss der Server ein gültiges TLS-Zertifikat haben, das mit seinem DNS-Namen übereinstimmt. Wir empfehlen dir, bei der Einrichtung deines Servers ein öffentlich verfügbares SSL/TLS-Verifizierungstool zu verwenden, z. B. SSL Server Test von Qualys.

Alle Anfragen, die Google an deinen Buchungsserver sendet, werden über die HTTP-Basisauthentifizierung authentifiziert. Die Anmeldedaten für die Basisauthentifizierung (Nutzername und Passwort) für deinen Buchungsserver können auf seiner Konfigurationsseite im Partner-Portal eingegeben werden. Passwörter müssen alle sechs Monate rotiert werden.

Hinweis:Sie müssen den Nutzernamen und das Passwort für die Sandbox und die Produktionsumgebung separat über den Umgebungsschalter festlegen.

Beispielimplementierungen für Skeletons

Sieh dir zuerst die folgenden Beispiel-Skeletons eines Buchungsservers an, die für Node.js- und Java-Frameworks erstellt wurden:

• Node.js-Skeleton: js-maps-booking-rest-server-v3-skeleton
• Java-Skeleton: java-maps-booking-rest-server-v3-skeleton

Diese Server haben REST-Methoden, die weiter ausgebaut werden können (Stubs).

Voraussetzungen

HTTP-Fehler und Fehler in der Geschäftslogik

Wenn dein Back-End HTTP-Anfragen verarbeitet, sind zwei Arten von Fehlern möglich:

• Fehler im Zusammenhang mit der Infrastruktur oder falsche Daten
  • Diese Fehler werden mit den Standard-HTTP-Fehlercodes an den Client zurückgegeben. Weitere Informationen findest du in der vollständigen Liste der HTTP-Statuscodes.
• Fehler im Zusammenhang mit der Geschäftslogik
  • Gib den HTTP-Statuscode 200 OK zurück und gib den Fehler in der Geschäftslogik im Antworttext an. Die möglichen Fehler in der Geschäftslogik unterscheiden sich je nach Art der Serverimplementierung.

Bei der Standardimplementierung werden die möglichen Fehler in der Geschäftslogik in BookingFailure (Buchungsfehler) erfasst und in der HTTP-Antwort zurückgegeben. Fehler in der Geschäftslogik können auftreten, wenn eine Ressource erstellt oder aktualisiert wird. etwa beim Verarbeiten der Methoden CreateBooking oder UpdatingBooking. Beispiele:

• SLOT_UNAVAILABLE wird verwendet, wenn der angeforderte Slot nicht mehr verfügbar ist.
• PAYMENT_ERROR_CARD_TYPE_REJECTED wird verwendet, wenn der angegebene Kreditkartentyp nicht akzeptiert wird.

Idempotenz

Die Kommunikation über das Netzwerk ist nicht immer zuverlässig. Daher sendet Google HTTP-Anfragen eventuell noch einmal, wenn keine Antwort zurückgegeben wird. Aus diesem Grund müssen alle Methoden, die den Status ändern, idempotent sein:

• CreateBooking
• UpdateBooking

Für jede Anfragenachricht außer UpdateBooking werden Idempotenz-Token verwendet, um die Anfrage eindeutig zu identifizieren. Dadurch kannst du zwischen einem REST-Aufruf, der noch einmal gesendet wurde und über den eine einzelne Anfrage erstellt werden soll, und zwei separaten Anfragen unterscheiden. UpdateBooking werden eindeutig über ihre IDs für die Buchung bzw. den Wartelisteneintrag identifiziert. Daher ist in diesen Anfragen kein Idempotenz-Token enthalten.

Nachfolgend findest du einige Beispiele dafür, wie Server Idempotenz verarbeiten:

• Eine erfolgreiche HTTP-Antwort auf CreateBooking enthält die erstellte Buchung. In einigen Fällen wird die Zahlung im Rahmen des Buchungsablaufs verarbeitet. Wenn dieselbe CreateBookingRequest-Anfrage ein zweites Mal (mit demselben idempotency_token) eingeht, muss auch dieselbe CreateBookingResponse-Antwort zurückgegeben werden. Es wird keine zweite Buchung erstellt und der Nutzer muss genau einmal bezahlen.

  Wenn ein CreateBooking-Versuch fehlschlägt und dieselbe Anfrage noch einmal gesendet wird, sollte das Back-End einen neuen Versuch starten.

Die Idempotenz-Vorgabe gilt für alle Methoden, die den Status ändern.