Menerapkan server pemesanan: API v2

Menyiapkan server Pemesanan di sisi Anda akan memungkinkan Actions Center membuat janji temu / pemesanan / reservasi dengan Anda atas nama pengguna.

Menerapkan antarmuka API berdasarkan gRPC

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

Menerapkan antarmuka API berdasarkan gRPC. Hal ini memungkinkan Google mengirimkan permintaan pemesanan. Permukaan API ditentukan menggunakan IDL berbasis protobuf gRPC.

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

Bagian ini memperkenalkan kumpulan API v2 yang direkomendasikan. Hal ini berlaku untuk partner yang belum menerapkan API v0. Untuk partner lama yang telah menerapkan API v0, hubungi Actions Center untuk mempelajari lebih lanjut.

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

Download definisi layanan

Resource API

Pelajari jenis resource berikut yang akan digunakan dalam penerapan ini:

Slot: slot inventaris
Pemesanan: janji temu untuk slot inventaris

Metode

Metode API berikut harus diimplementasikan di sisi 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. Hal ini harus ditangani sebagai bayar tanpa login dari sudut pandang partner karena Pusat Tindakan tidak dapat mencari akun pengguna di sistem partner. Pemesanan akhir harus ditampilkan kepada penjual partner di sistem mereka seperti pemesanan yang berasal dari sistem pemesanan partner.

Penerapan 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 membuat stub metode gRPC yang diperlukan untuk mendukung integrasi, termasuk layanan autentikasi dan kesehatan.

Persyaratan

Error gRPC dan error logika bisnis

Dua jenis error dapat terjadi saat backend partner menangani permintaan gRPC: error tak terduga yang muncul akibat data yang salah; dan error logika bisnis yang menunjukkan ketidakmampuan untuk 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_ARGUMENT digunakan dalam RPC seperti CheckAvailability dan CreateLease, dan harus ditampilkan jika slot yang diberikan berisi informasi yang tidak valid.
NOT_FOUND digunakan dalam RPC seperti CreateBooking dan ListBookings, dan harus ditampilkan jika ID yang diberikan tidak diketahui oleh partner.

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

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

SLOT_UNAVAILABLE digunakan jika slot yang diminta tidak lagi tersedia.
PAYMENT_ERROR_CARD_TYPE_REJECTED digunakan jika jenis kartu kredit yang diberikan tidak diterima.

Idempotensi

Komunikasi melalui jaringan tidak selalu dapat diandalkan dan Google Reserve dapat mencoba lagi RPC jika tidak ada respons yang diterima. Oleh karena itu, semua RPC yang mengubah status (CreateBooking, UpdateBooking) harus bersifat idempotent. 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 sesuai, ditagih hanya sekali. Perhatikan bahwa jika percobaan CreateBooking gagal, backend partner harus mencoba lagi jika permintaan yang sama dikirim lagi.

Persyaratan idempotency berlaku untuk semua metode yang berisi token idempotency.

Keamanan dan autentikasi Server gRPC

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

Sertifikat server: server partner harus dilengkapi dengan sertifikat server yang valid dan terkait dengan nama domain server (lihat daftar CA root yang diterima ini). Implementasi server GRPC diharapkan untuk menyajikan rantai sertifikat yang mengarah ke sertifikat root. 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 sebenarnya tidak diperiksa selama sertifikat 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) ke partner, kami memberikan sertifikat klien yang dikeluarkan 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 serangkaian sertifikat root klien tepercaya. Anda dapat memilih untuk mendapatkan kumpulan root tepercaya ini dari otoritas seperti Mozilla atau menginstal kumpulan root yang saat ini direkomendasikan oleh Otoritas Internet Google G2. Dalam kedua kasus tersebut, Anda mungkin harus memperbarui sertifikat root secara manual dari waktu ke waktu.

Menerapkan Protokol Health Check gRPC

Terapkan Protokol Health Check GRPC. Protokol ini memungkinkan Google memantau status backend penerapan gRPC Anda. Spesifikasi layanan adalah bagian dari distribusi GRPC. Dengan mengikuti 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 berjalan di URL dan PORT yang sama dengan endpoint lainnya.

Versi lainnya

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