Wenn Sie einen Buchungsserver einrichten, kann das Actions Center im Namen des Nutzers Termine, Buchungen und Reservierungen bei Ihnen erstellen.
API-Schnittstelle auf Grundlage von gRPC implementieren
Hinweis: Alle neuen Partner sollten die REST API-Schnittstelle anstelle der gRPC API verwenden.
Implementiere eine gRPC-API-Schnittstelle. So kann Google Buchungsanfragen senden. Die API-Oberfläche wird mit der protobuf-basierten IDL von gRPC definiert.
Wir bitten unsere neuen Partner, eine empfohlene Reihe von API v2 zu implementieren. Partner können die URL und den Port auswählen, die am besten zu ihrer Infrastruktur passen.
In diesem Abschnitt wird eine empfohlene Gruppe von APIs (Version 2) vorgestellt. Sie gilt für Partner, die die API v0 nicht implementiert haben. Wenn Sie ein aktueller Partner sind, der API v0 implementiert hat, wenden Sie sich bitte an das Actions Center, um weitere Informationen zu erhalten.
Lade die Dienstleistungsdefinition im .proto-Format unten 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 müssen von Ihnen für den gRPC-Server implementiert werden:
Diese fünf Methoden definieren die erforderlichen 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
Wenn ein Nutzer eine Buchung erstellt, sendet Google dem Partner den Namen, den Nachnamen, die Telefonnummer und die E-Mail-Adresse, die er angegeben hat. Aus Sicht des Partners sollte dies als Gastbestellung behandelt werden, da das Actions Center das Konto des Nutzers im System des Partners nicht abrufen kann. Die endgültige Buchung sollte den Händlern des Partners in ihrem System genauso angezeigt werden wie Buchungen aus dem Buchungssystem des Partners.
Skeleton-Implementierung in Java
Für den Einstieg stellen wir einen gRPC-Serverskelett in Java bereit, der kompiliert und installiert werden kann. Sie finden sie im Abschnitt Beispiele > gRPC-Referenzimplementierung. Dieser Server hat gRPC-Methoden, die für die Unterstützung der Integration erforderlich sind, einschließlich Authentifizierungs- und Gesundheitsdienst, als Stub implementiert.
Voraussetzungen
gRPC-Fehler und Fehler in der Geschäftslogik
Wenn ein Partner-Back-End gRPC-Anfragen verarbeitet, können zwei Arten von Fehlern auftreten: unerwartete Fehler, die durch falsche Daten entstehen, und Fehler in der Geschäftslogik, die darauf hinweisen, dass eine Buchung nicht erstellt oder aktualisiert werden kann (siehe Fehler bei der Buchung), z.B. wenn der angeforderte Slot nicht verfügbar ist.
Unerwartete Fehler sollten mit 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 Kennung dem Partner nicht bekannt ist.
Die kanonischen gRPC-Fehlercodes für die einzelnen Methoden finden Sie in der Referenzdokumentation zu den Methoden oder in der vollständigen Liste der Statuscodes.
Fehler in der Geschäftslogik sollten hingegen in BookingFailure erfasst und in der RPC-Antwort zurückgegeben werden. Fehler in der Geschäftslogik können beim Erstellen oder Aktualisieren einer Ressource auftreten, d.h. beim Verarbeiten der RPCs „CreateBooking“ und „UpdateBooking“. 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 Reserve RPCs eventuell noch einmal, wenn keine Antwort zurückgegeben wird. Aus diesem Grund müssen alle RPCs, die den Status ändern (CreateBooking, UpdateBooking), idempotent sein. Anfragenachrichten für diese RPCs enthalten Idempotenz-Tokens, um die Anfrage eindeutig zu identifizieren und dem Partner zu ermöglichen, zwischen einem RPC, der noch einmal gesendet wurde (mit der Absicht, eine einzelne Buchung zu erstellen), und zwei separaten Buchungen zu unterscheiden.
Beispiele:
- Eine erfolgreiche RPC-Antwort auf CreateBooking enthält die erstellte Buchung. In einigen Fällen wird die Zahlung im Rahmen des Buchungsablaufs 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 der Nutzer muss genau einmal bezahlen. Wenn ein CreateBooking-Versuch fehlschlägt, sollte das Partner-Back-End einen neuen Versuch starten, wenn dieselbe Anfrage noch einmal gesendet wird.
Die Idempotenz-Vorgabe gilt für alle Methoden, die Idempotenz-Tokens enthalten.
Sicherheit und Authentifizierung von gRPC-Servern
Aufrufe vom Actions Center an Ihr Backend müssen mit SSL/TLS mit zertifikatbasierter, gegenseitiger Client-/Serverauthentifizierung gesichert werden. Dazu ist die Verwendung eines gültigen Serverzertifikats für Ihre gRPC-Implementierung und die Annahme eines gültigen Clientzertifikats erforderlich.
Serverzertifikat:Der Partnerserver muss mit einem gültigen Serverzertifikat ausgestattet sein, das mit dem Domainnamen des Servers verknüpft ist (siehe Liste der akzeptierten Stammzertifizierungsstellen). GRPC-Serverimplementierungen erwarten, dass eine Zertifikatskette bereitgestellt wird, die bis zum Root-Zertifikat führt. Am einfachsten ist es, die vom Webhost des Partners bereitgestellten Zwischenzertifikate im PEM-Format an das Serverzertifikat (ebenfalls im PEM-Format) anzuhängen.
Das Serverzertifikat wird zum Zeitpunkt der Verbindung überprüft. Selbst signierte Zertifikate werden nicht akzeptiert. Der tatsächliche Zertifikatsinhalt wird nicht geprüft, solange das Zertifikat gültig ist. Sie können die Gültigkeit Ihres Zertifikats mit dem folgenden Befehl prüfen:
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
Clientzertifikat:Um uns (als Google) beim Partner zu authentifizieren, stellen wir ein Clientzertifikat aus, das von der Google Internet Authority G2 (CA-Zertifikat) mit den folgenden Eigenschaften ausgestellt wurde:
| 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 verwendet der Server eine Reihe vertrauenswürdiger Client-Root-Zertifikate. Sie können diese vertrauenswürdigen Root-Zertifikate von einer Zertifizierungsstelle wie Mozilla beziehen oder die derzeit von der Google Internet Authority G2 empfohlenen Root-Zertifikate installieren. In beiden Fällen müssen Sie die Root-Zertifikate möglicherweise von Zeit zu Zeit manuell aktualisieren.
gRPC-Systemdiagnoseprotokoll implementieren
Implementieren Sie das GRPC-Systemdiagnoseprotokoll.
Mit diesem Protokoll kann Google den Backend-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 oder ext.maps.booking.partner.v0.BookingService für API v0. Die Systemdiagnose sollte auf derselben URL und demselben Port wie die anderen Endpunkte ausgeführt werden.
Weitere Versionen
Die Dokumentation für andere Versionen der API finden Sie auf den folgenden Seiten: * API v3 * API v0