Du musst einen Buchungsserver einrichten, damit das Actions Center Rückrufe senden kann, um Buchungen in deinem Namen zu erstellen und zu aktualisieren.
- Die Standardimplementierung: So können über das Actions Center im Namen des Nutzers Termine, Buchungen und Reservierungen bei Ihnen erstellt werden.
In der Dokumentation zum Partner-Portal erfährst du, wie du die Verbindung zu deiner Sandbox und zu Produktions-Buchungsservern konfigurierst.
REST API-Schnittstelle implementieren
Implementiere eine API-Schnittstelle auf der Grundlage von REST. So kann Google Buchungsserveranfragen über HTTP senden.
Richte zuerst einen Entwicklungs- oder Sandbox-Buchungsserver ein, der mit der Actions Center-Sandbox-Umgebung verbunden werden kann. Wechsle erst dann in eine Produktionsumgebung, wenn der Sandbox-Server vollständig getestet wurde.
Methoden
Für jede Art von Buchungsserver sind unterschiedliche API-Methoden erforderlich. Optional können Sie die Dienstdefinition im .proto-Format herunterladen, um mit der API-Implementierung zu beginnen. Die folgenden Tabellen enthalten die Methoden für die einzelnen Implementierungen sowie Links zu den Dienstproto-Formaten.
Standardimplementierung |
---|
Standarddienstdefinition: Laden Sie die .proto-Dienstdefinitionsdatei 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:
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](https://developers-dot-devsite-v2-prod.appspot.com/static/actions-center/images/rest_api_v3_booking_flow_1.png?authuser=19&hl=de)
Wenn ein Nutzer eine Buchung erstellt, sendet Google dir den Namen, den Nachnamen, die Telefonnummer und die E-Mail-Adresse des Nutzers. Aus deiner Sicht muss diese Buchung wie eine Buchung als Gast behandelt werden, da das Actions Center das Konto des Nutzers in deinem System nicht nachschlagen kann. Die endgültige Buchung muss mit den Buchungen deiner Händler aus deinem Buchungssystem übereinstimmen.
Sicherheit und Authentifizierung
Die gesamte Kommunikation mit deinem Buchungsserver erfolgt über HTTPS. Daher muss dein Server ein gültiges TLS-Zertifikat haben, das mit seinem DNS-Namen übereinstimmt. Wir empfehlen für die Einrichtung des Servers die Verwendung eines öffentlich verfügbaren Tools zur SSL/TLS-Überprüfung, z. B. SSL Server Test von Qualys.
Alle Anfragen, die Google an deinen Buchungsserver sendet, werden mit der HTTP-Basisauthentifizierung authentifiziert. Die Anmeldedaten für die Basisauthentifizierung (Nutzername und Passwort) für deinen Buchungsserver können auf der Konfigurationsseite des Buchungsservers im Partner-Portal eingegeben werden. Passwörter müssen alle sechs Monate rotiert werden.
Beispielimplementierungen für Skeletons
Sieh dir zuerst die folgenden Beispielskeletons eines Buchungsservers an, die für Node.js- und Java-Frameworks geschrieben 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 Ihr Back-End HTTP-Anfragen verarbeitet, können zwei Arten von Fehlern auftreten.
- Fehler im Zusammenhang mit der Infrastruktur oder falschen Daten
- Geben Sie diese Fehler mit Standard-HTTP-Fehlercodes an den Client zurück. Weitere Informationen finden Sie in der vollständigen Liste der HTTP-Statuscodes.
- Fehler im Zusammenhang mit der Geschäftslogik
- Geben Sie den HTTP-Statuscode zurück, der auf
200
OK gesetzt ist, und geben Sie im Antworttext den Fehler in der Geschäftslogik an. Die Arten von Geschäftslogikfehlern, die auftreten können, unterscheiden sich je nach Art der Serverimplementierung.
- Geben Sie den HTTP-Statuscode zurück, der auf
Bei der Standardimplementierung werden die möglichen Fehler in der Geschäftslogik in Buchungsfehler erfasst und in der HTTP-Antwort zurückgegeben. Beim Erstellen oder Aktualisieren einer Ressource können Fehler in der Geschäftslogik auftreten. Das ist beispielsweise der Fall, wenn Sie die Methoden CreateBooking
oder UpdatingBooking
verarbeiten. Hier einige 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 und Google kann HTTP-Anfragen wiederholen, wenn keine Antwort empfangen wird. Aus diesem Grund müssen alle Methoden, die den Status ändern, idempotent sein:
CreateBooking
UpdateBooking
Für jede Anfragenachricht außer UpdateBooking
werden Idempotenztokens verwendet, um die Anfrage eindeutig zu identifizieren. Auf diese Weise können Sie zwischen einem REST-Aufruf, der wiederholt und mit der Absicht eine einzelne Anfrage erstellen soll, und zwei separaten Anfragen unterscheiden.
UpdateBooking
wird anhand der Buchungseintrags-IDs eindeutig identifiziert, sodass in den Anfragen kein Idempotenztoken enthalten ist.
Nachfolgend findest du einige Beispiele dafür, wie Server Idempotenz verarbeiten:
Eine erfolgreiche
CreateBooking
-HTTP-Antwort enthält die erstellte Buchung. In einigen Fällen wird die Zahlung als Teil des Buchungsvorgangs verarbeitet. Wenn genau dieselbeCreateBookingRequest
ein zweites Mal (mit demselbenidempotency_token
) empfangen wird, muss auch dieselbeCreateBookingResponse
zurückgegeben werden. Es wird keine zweite Buchung erstellt und dem Nutzer wird der Betrag gegebenenfalls genau einmal in Rechnung gestellt.Wenn ein
CreateBooking
-Versuch fehlschlägt und dieselbe Anfrage noch einmal gesendet wird, sollte das Back-End den Vorgang in diesem Fall wiederholen.
Die Idempotenz-Vorgabe gilt für alle Methoden, die den Status ändern.