Menerapkan server pemesanan: API v2

Menyiapkan server Pemesanan di pihak Anda akan memungkinkan Pusat Tindakan membuat janji temu / pemesanan / reservasi dengan Anda atas nama pengguna.

Mengimplementasikan antarmuka API berdasarkan gRPC

Perhatikan: semua partner baru harus menggunakan antarmuka REST API, bukan gRPC API.

Mengimplementasikan antarmuka API berdasarkan gRPC. Tindakan ini memungkinkan Google mengirim permintaan pemesanan. Platform API ditentukan menggunakan IDL berbasis protobuf gRPC.

Kami meminta partner baru kami untuk menerapkan serangkaian API v2 yang direkomendasikan. Partner dapat memilih URL dan PORT mana pun yang paling cocok untuk infrastruktur mereka.

Bagian ini memperkenalkan kumpulan API v2 yang direkomendasikan. Ini berlaku untuk partner yang belum menerapkan API v0. Untuk partner kami saat ini yang telah menerapkan API v0, hubungi Pusat Tindakan untuk mempelajari lebih lanjut.

Download definisi layanan dalam format proto di bawah untuk memulai penerapan API.

Mendownload definisi layanan

Resource API

Pahami jenis resource berikut yang akan digunakan dalam implementasi ini:

  • Slot: slot inventaris
  • Booking: janji temu untuk slot inventaris

Metode

Metode API berikut harus diterapkan di pihak Anda untuk server gRPC:

Kelima metode ini menentukan kumpulan RPC BookingService yang diperlukan:

// 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) {}
}

Alur: membuat pemesanan

Gambar 1: Membuat Pemesanan dari Slot

Saat membuat pemesanan, Google akan mengirimkan nama depan, nama belakang, nomor telepon, dan email pengguna kepada partner. Dari sudut pandang partner, hal ini harus diperlakukan sebagai checkout tanpa login karena Pusat Tindakan tidak memiliki cara untuk mencari akun pengguna di sistem partner. Pemesanan akhir harus ditampilkan kepada penjual partner dalam sistem mereka, seperti pemesanan yang disertakan untuk sistem pemesanan partner.

Implementasi Skeleton di Java

Untuk memulai, kami menyediakan server gRPC kerangka di Java yang dapat dikompilasi dan diinstal. Lihat di bagian Samples > gRPC Reference Implementation. Server ini telah menonaktifkan metode gRPC yang diperlukan untuk mendukung integrasi, termasuk autentikasi dan layanan kesehatan.

Persyaratan

Error gRPC dan error logika bisnis

Dua jenis error dapat terjadi saat backend partner menangani permintaan gRPC: error tak terduga yang muncul dari data yang salah; dan error logika bisnis yang menunjukkan ketidakmampuan membuat atau memperbarui pemesanan (lihat Kegagalan Pemesanan), misalnya, jika slot yang diminta tidak tersedia.

Error tak terduga, jika ditemukan, harus ditampilkan ke klien menggunakan kode error gRPC kanonis. Contohnya mencakup namun tidak terbatas pada:

  • INVALID_FILENAME digunakan dalam RPC seperti CheckAvailability dan CreateLease, dan harus ditampilkan jika slot yang disediakan berisi informasi yang tidak valid.
  • NOT_FOUND digunakan dalam RPC seperti CreateBooking dan ListBookings, serta harus ditampilkan jika ID yang diberikan tidak diketahui partner.

Lihat referensi setiap metode untuk kode error gRPC kanonisnya atau lihat daftar kode status lengkap.

Sebaliknya, error logika bisnis harus ditangkap dalam Kegagalan Pemesanan, dan ditampilkan dalam respons RPC. Error logika bisnis mungkin terjadi saat membuat atau memperbarui resource, yaitu dalam menangani CreateBooking RPC, dan UpdatesBooking. Contohnya mencakup namun tidak terbatas pada:

  • Slot_UNAVAILABLE digunakan jika slot yang diminta tidak lagi tersedia.
  • PAYMENT_ERROR_CARD_TYPE_ DITOLAK digunakan jika jenis kartu kredit yang diberikan tidak diterima.

Idempotensi

Komunikasi melalui jaringan tidak selalu dapat diandalkan dan Google Reserve dapat mencoba ulang RPC jika tidak ada respons yang diterima. Karena alasan ini, semua RPC yang mengubah status (CreateBooking, UpdateBooking) harus idempoten. Pesan permintaan untuk RPC ini mencakup token idempotensi untuk mengidentifikasi permintaan secara unik dan memungkinkan partner membedakan antara RPC yang dicoba lagi (dengan maksud untuk membuat satu pemesanan) dan dua pemesanan terpisah.

Contohnya mencakup namun tidak terbatas pada:

  • Respons RPC CreateBooking yang berhasil mencakup pemesanan yang dibuat dan, dalam beberapa kasus, pembayaran diproses sebagai bagian dari alur pemesanan. Jika CreateBookingRequest yang sama persis diterima untuk kedua kalinya (termasuk idempotency_token), CreateBookingResponse yang sama harus ditampilkan. Tidak ada pemesanan kedua yang dibuat dan pengguna, jika ada, akan ditagih satu kali. Perhatikan bahwa jika upaya CreateBooking gagal, backend partner harus mencoba lagi jika permintaan yang sama dikirim lagi.

Persyaratan idempotensi berlaku untuk semua metode yang berisi token idempotensi.

Keamanan dan autentikasi Server gRPC

Panggilan dari Pusat Actions ke backend Anda harus diamankan menggunakan SSL/TLS dengan autentikasi klien/server bersama berbasis sertifikat. Hal ini memerlukan penggunaan sertifikat server yang valid untuk implementasi gRPC Anda dan penerimaan sertifikat klien yang valid.

Sertifikat server: server partner harus dilengkapi dengan sertifikat server valid yang terkait dengan nama domain server (lihat daftar root CA yang diterima ini). Penerapan server GRPC akan menayangkan rantai sertifikat yang mengarah ke root certificate. Cara termudah untuk melakukannya adalah dengan menambahkan sertifikat perantara yang disediakan oleh host web partner dalam format PEM ke sertifikat server (juga dalam format PEM).

Sertifikat server diverifikasi pada waktu koneksi dan sertifikat yang ditandatangani sendiri tidak diterima. Konten sertifikat yang sebenarnya tidak akan diperiksa selama sertifikat tersebut valid. Anda dapat memeriksa validitas sertifikat Anda melalui perintah berikut:

echo "" | openssl s_client  -connect YOUR_URL:YOUR_PORT  -showcerts -CApath /etc/ssl/certs

Sertifikat klien: untuk mengautentikasi kami (sebagai Google) kepada partner, kami memberikan sertifikat klien yang diterbitkan oleh Google Internet Authority G2 (sertifikat CA) dengan properti berikut:

Kolom Nilai
CN mapsbooking.businesslink-3.net
SAN DNS:mapsbooking.businesslink-3.net

Upaya koneksi tanpa sertifikat klien ini harus ditolak oleh server partner.

Untuk memvalidasi sertifikat klien, server mengandalkan sekumpulan root certificate klien tepercaya. Anda dapat memilih untuk mendapatkan kumpulan root tepercaya ini dari otoritas seperti Mozilla atau menginstal kumpulan root yang saat ini direkomendasikan oleh Google Internet Authority G2. Dalam kedua kasus tersebut, Anda mungkin terkadang harus memperbarui root certificate secara manual.

Menerapkan Protokol Health Check gRPC

Terapkan Protokol Pemeriksaan Kesehatan GRPC. Protokol ini memungkinkan Google memantau status backend penerapan gRPC Anda. Spesifikasi layanan adalah bagian dari distribusi GRPC. Berdasarkan konvensi penamaan GRPC, nama layanan dalam panggilan health check adalah ext.maps.booking.partner.v2.BookingService untuk API v2, atau ext.maps.booking.partner.v0.BookingService untuk API v0. Health check harus dijalankan pada URL dan PORT yang sama dengan endpoint lainnya.

Versi lainnya

Untuk dokumentasi bagi versi API lainnya, lihat halaman berikut: * API v3 * API v0