Buchungsserver implementieren: API Version 2

Wenn Sie einen Buchungsserver einrichten, kann das Actions Center im Namen des Nutzers Termine, Buchungen und Reservierungen bei Ihnen erstellen.

API-Schnittstelle auf Basis von gRPC implementieren

Hinweis: Alle neuen Partner sollten die REST API-Schnittstelle anstelle der gRPC API verwenden.

Implementiere eine gRPC. Damit kann Google Buchungsanfragen senden. Die API-Oberfläche wird mit der Protobuf-basierten IDL von gRPC definiert.

Wir bitten unsere neuen Partner, die empfohlenen APIs (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 werden die empfohlenen APIs (Version 2) vorgestellt. Sie gilt für Partner, die die API v0 nicht implementiert haben. Wenn Sie bereits API v0 implementiert haben, wenden Sie sich bitte an das Actions Center, um mehr zu erfahren.

Lade die Dienstleistungsdefinition 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:

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

Methoden

Die folgenden API-Methoden müssen von Ihnen für den gRPC-Server implementiert werden:

Mit diesen fünf Methoden werden die erforderlichen BookingService-RPCs definiert:

// 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

Abbildung 1: Buchung über einen Slot erstellen

Wenn eine Buchung erstellt wird, sendet Google dem Partner den Namen, den Nachnamen, die Telefonnummer und die E-Mail-Adresse des Nutzers. Aus Sicht des Partners sollte dies als Bezahlung als Gast 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 angezeigt werden, genau wie Buchungen, die über das Buchungssystem des Partners eingehen.

Skeleton-Implementierung in Java

Zuerst stellen wir einen gRPC-Server-Prototyp in Java bereit, der kompiliert und installiert werden kann. Sie finden sie im Abschnitt Beispiele > gRPC-Referenzimplementierung. Auf diesem Server wurden gRPC-Methoden als Stubs implementiert, die für die Integration erforderlich sind, einschließlich Authentifizierung und Systemdiagnose.

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 auf falsche Daten zurückzuführen sind, und Fehler in der Geschäftslogik, die darauf hinweisen, dass eine Buchung nicht erstellt oder aktualisiert werden kann (siehe Buchung fehlgeschlagen), 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 angegebene 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 Referenz der jeweiligen Methode oder in der vollständigen Liste der Statuscodes.

Fehler in der Geschäftslogik sollten dagegen 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, z.B. beim Umgang mit den RPCs „CreateBooking“ und „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 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-Token, 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 RPC-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 (einschließlich idempotency_token) eingeht, muss dieselbe CreateBookingResponse-Antwort zurückgegeben werden. Es wird keine zweite Buchung erstellt und der Nutzer muss gegebenenfalls 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-Token enthalten.

Sicherheit und Authentifizierung des gRPC-Servers

Aufrufe vom Actions Center an Ihr Backend müssen mit SSL/TLS und einer zertifikatbasierten, wechselseitigen Client-/Server-Authentifizierung 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. Weitere Informationen finden Sie in der Liste der akzeptierten Stammzertifizierungsstellen. GRPC-Serverimplementierungen erwarten eine Zertifikatskette, die zum Stammzertifikat 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 bei der Verbindung geprüft und selbst signierte Zertifikate werden nicht akzeptiert. Der Inhalt des Zertifikats 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 von der Google Internet Authority G2 (CA-Zertifikat) mit den folgenden Eigenschaften 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 verwendet der Server eine Reihe vertrauenswürdiger Client-Root-Zertifikate. Sie können diese vertrauenswürdigen Stammzertifikate von einer Zertifizierungsstelle wie Mozilla beziehen oder die von der Google Internet Authority G2 derzeit empfohlenen Stammzertifikate installieren. In beiden Fällen müssen Sie die Root-Zertifikate möglicherweise manuell aktualisieren.

Implementieren Sie das gRPC-Systemdiagnoseprotokoll.

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-Benennungskonvention 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 über dieselbe URL und denselben PORT wie die anderen Endpunkte ausgeführt werden.

Weitere Versionen

Dokumentationen zu anderen Versionen der API finden Sie auf den folgenden Seiten: * API v3 * API v0