Wenn du einen Buchungsserver auf deiner Seite einrichtest, kann das Actions Center im Namen des Nutzers Termine / Buchungen / Reservierungen bei dir erstellen.
API-Schnittstelle basierend auf gRPC implementieren
Hinweis: Alle neuen Partner sollten die REST API-Schnittstelle anstelle der gRPC API verwenden.
Implementieren Sie eine API-Schnittstelle, die auf gRPC basiert. So kann Google Buchungsanfragen senden. Die API-Oberfläche wird mit der protobuf-basierten IDL von gRPC definiert.
Wir bitten unsere neuen Partner, einen empfohlenen Satz API-Version 2 zu implementieren. Partner können die URL und den PORT auswählen, die für ihre Infrastruktur am besten geeignet sind.
In diesem Abschnitt wird ein empfohlener Satz von API v2 vorgestellt. Sie gilt für Partner, die API v0 nicht implementiert haben. Weitere Informationen für unsere aktuellen Partner, die API-Version 0 implementiert haben, erhalten Sie im Actions Center.
Laden Sie die Dienstdefinition unten im .proto-Format herunter, um mit der API-Implementierung zu beginnen.
Dienstdefinition herunterladen
API-Ressourcen
Machen Sie sich mit den folgenden Ressourcentypen vertraut, die in dieser Implementierung verwendet werden:
Methoden
Die folgenden API-Methoden sind für den gRPC-Server erforderlich:
Diese fünf Methoden definieren den erforderlichen Satz von BookingService-RPCs:
// Manages slot availability, leases and bookings for an inventory of
// appointments
service BookingService {
// Gets availability information for an appointment slot
rpc CheckAvailability(CheckAvailabilityRequest)
returns (CheckAvailabilityResponse) {}
// Creates a booking
rpc CreateBooking(CreateBookingRequest) returns (CreateBookingResponse) {}
// Updates an existing booking
rpc UpdateBooking(UpdateBookingRequest) returns (UpdateBookingResponse) {}
// Gets status for an existing booking
rpc GetBookingStatus(GetBookingStatusRequest)
returns (GetBookingStatusResponse) {}
// Lists all upcoming bookings for a user
rpc ListBookings(ListBookingsRequest) returns (ListBookingsResponse) {}
}
Ablauf: Eine Buchung erstellen
Beim Erstellen einer Buchung sendet Google dem Partner den Namen, den Nachnamen, die Telefonnummer und die E-Mail-Adresse des Nutzers. Dies sollte aus der Sicht des Partners als Gast-Checkout betrachtet werden, da das Actions Center keine Möglichkeit hat, das Konto des Nutzers im System des Partners nachzuschlagen. Die endgültige Buchung sollte den Händlern des Partners in ihrem System angezeigt werden – genau wie Buchungen, die über das Buchungssystem des Partners eingehen.
Skeleton-Implementierung in Java
Zuerst stellen wir ein Basis-gRPC-Server in Java bereit, das kompiliert und installiert werden kann. Weitere Informationen finden Sie im Abschnitt Beispiele > gRPC-Referenzimplementierung. Dieser Server hat gRPC-Methoden, die zur Unterstützung der Integration erforderlich sind, einschließlich Authentifizierung und Systemdiagnose.
Voraussetzungen
gRPC-Fehler und Fehler in der Geschäftslogik
Es können zwei Arten von Fehlern auftreten, wenn ein Partner-Back-End gRPC-Anfragen verarbeitet: unerwartete Fehler, die durch falsche Daten verursacht werden, und Fehler in der Geschäftslogik, die darauf hinweisen, dass eine Buchung nicht erstellt oder aktualisiert werden kann (siehe Buchungsfehler), z.B. wenn der angeforderte Slot nicht verfügbar ist.
Unerwartete Fehler sollten mithilfe von kanonischen gRPC-Fehlercodes an den Client zurückgegeben werden. Beispiele:
- INVALID_ARGUMENT wird in RPCs wie CheckAvailability und CreateLease verwendet und sollte zurückgegeben werden, wenn der bereitgestellte Slot ungültige Informationen enthält.
- NOT_FOUND wird in RPCs wie CreateBooking und ListBookings verwendet und sollte zurückgegeben werden, wenn die angegebene ID dem Partner unbekannt ist.
In der Referenz zu den einzelnen Methoden finden Sie die kanonischen gRPC-Fehlercodes sowie die vollständige Statuscodeliste.
Im Gegensatz dazu sollten Fehler in der Geschäftslogik in Booking Failure (Buchungsfehler) erfasst und in der RPC-Antwort zurückgegeben werden. Fehler in der Geschäftslogik können beim Erstellen oder Aktualisieren einer Ressource, d.h. bei der Verarbeitung von RPCs CreateBooking und RefreshBooking auftreten. 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 Reserve kann RPCs wiederholen, wenn keine Antwort empfangen wird. Aus diesem Grund müssen alle RPCs, die den Status ändern (CreateBooking, UpdateBooking), idempotent sein. Anfragenachrichten für diese RPCs enthalten Idempotenztokens, um die Anfrage eindeutig zu identifizieren und dem Partner zu ermöglichen, zwischen einem wiederholten RPC (mit der Absicht, eine einzelne Buchung zu erstellen) und zwei separaten Buchungen zu unterscheiden.
Beispiele:
- Eine erfolgreiche CreateBooking-RPC-Antwort enthält die erstellte Buchung. In einigen Fällen wird die Zahlung als Teil des Buchungsvorgangs verarbeitet. Wenn dieselbe „CreateBookingRequest“ ein zweites Mal eingeht (einschließlich
idempotency_token), muss dieselbe „CreateBookingResponse“ zurückgegeben werden. Es wird keine zweite Buchung erstellt und dem Nutzer wird, falls zutreffend, genau einmal Kosten in Rechnung gestellt. Wenn ein CreateBooking-Versuch fehlschlägt, sollte das Partner-Back-End einen neuen Versuch starten, wenn dieselbe Anfrage noch einmal gesendet wird.
Die Idempotenzanforderung gilt für alle Methoden, die Idempotenztokens enthalten.
gRPC Server-Sicherheit und -Authentifizierung
Aufrufe vom Actions Center an Ihr Back-End müssen durch SSL/TLS mit zertifikatbasierter gegenseitiger Client/Server-Authentifizierung gesichert werden. Dazu müssen Sie ein gültiges Serverzertifikat für Ihre gRPC-Implementierung verwenden und ein gültiges Clientzertifikat akzeptieren.
Serverzertifikat:Der Partnerserver muss mit einem gültigen Serverzertifikat ausgestattet sein, das dem Domainnamen des Servers zugeordnet ist (siehe Liste der akzeptierten Root-Zertifizierungsstellen). GRPC-Serverimplementierungen erwarten eine Zertifikatskette, die zum Root-Zertifikat führt. Am einfachsten ist es, wenn Sie die vom Webhost des Partners bereitgestellten Zwischenzertifikate im PEM-Format an das Serverzertifikat anhängen (auch im PEM-Format).
Das Serverzertifikat wird zum Zeitpunkt der Verbindung überprüft und selbst signierte Zertifikate werden nicht akzeptiert. Der tatsächliche Zertifikatinhalt wird nicht geprüft, solange das Zertifikat gültig ist. Die Gültigkeit Ihres Zertifikats können Sie mit dem folgenden Befehl prüfen:
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
Clientzertifikat:Zur Authentifizierung von uns als Google gegenüber dem Partner stellen wir ein von der Google Internet Authority G2 ausgestelltes CA-Zertifikat mit den folgenden Attributen zur Verfügung:
| Feld | Wert |
|---|---|
CN |
mapsbooking.businesslink-3.net |
SAN |
DNS:mapsbooking.businesslink-3.net |
Verbindungsversuche ohne dieses Clientzertifikat sollten vom Partnerserver abgelehnt werden.
Zur Validierung des Clientzertifikats stützt sich der Server auf eine Reihe vertrauenswürdiger Root-Zertifikate von Clients. Sie können diese vertrauenswürdigen Root-Zertifikate von einer Behörde wie Mozilla beziehen oder den aktuell von der Google Internet Authority G2 empfohlenen Satz von Root-Dateien installieren. In beiden Fällen müssen Sie die Root-Zertifikate manchmal manuell aktualisieren.
gRPC-Systemdiagnoseprotokoll implementieren
Implementieren Sie das gRPC-Systemdiagnoseprotokoll.
Mit diesem Protokoll kann Google den Back-End-Status Ihrer gRPC-Implementierung überwachen. Die Dienstspezifikation ist Teil der gRPC-Distribution. Gemäß der GRPC-Namenskonvention lautet der Name des Dienstes in den Systemdiagnoseaufrufen ext.maps.booking.partner.v2.BookingService für API v2 und ext.maps.booking.partner.v0.BookingService für API v0. Die Systemdiagnose sollte für dieselbe URL und denselben PORT wie die anderen Endpunkte ausgeführt werden.
Weitere Versionen
Eine Dokumentation für andere Versionen der API finden Sie auf den folgenden Seiten: * API Version 3 * API Version 0