Halaman ini diterjemahkan oleh Cloud Translation API.

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.

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. Platform API ditentukan menggunakan IDL berbasis protobuf gRPC.

Kami meminta partner baru 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 kami saat ini yang telah menerapkan API v0, hubungi Pusat Actions untuk mempelajari lebih lanjut.

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

Mendownload definisi layanan

Resource API

Pelajari jenis resource berikut yang akan digunakan dalam implementasi ini:

Slot: slot inventaris
Pemesanan: janji temu untuk slot inventaris

Metode

Metode API berikut diperlukan untuk diimplementasikan di pihak Anda untuk server gRPC:

5 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 diperlakukan sebagai checkout tamu dari sudut pandang partner karena Pusat Tindakan tidak memiliki cara untuk mencari akun pengguna di sistem partner. Pemesanan akhir harus ditampilkan kepada penjual partner di sistem mereka, sama seperti pemesanan yang berasal dari sistem pemesanan partner.

Implementasi Skeleton di Java

Untuk memulai, kami menyediakan server gRPC kerangka di Java yang dapat dikompilasi dan diinstal. Lihat di bagian Contoh > Implementasi Referensi gRPC. Server ini telah menghapus 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 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 kode error gRPC kanonisnya atau lihat daftar kode status lengkap.

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 dalam menangani RPC CreateBooking, dan UpdatingBooking. 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. Karena alasan ini, semua RPC yang mengubah status (CreateBooking, UpdateBooking) harus bersifat idempotent. Pesan permintaan untuk RPC ini menyertakan token idempotency 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 berlaku, 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 menerima sertifikat klien yang valid.

Sertifikat server: server partner harus dilengkapi dengan sertifikat server yang valid dan terkait dengan nama domain server (lihat daftar root CA yang diterima ini). Implementasi server GRPC diharapkan dapat 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 diperiksa selama sertifikat tersebut valid. Anda dapat memeriksa validitas sertifikat 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 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 kumpulan 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 Google Internet Authority G2. Dalam kedua kasus tersebut, Anda mungkin harus memperbarui sertifikat root secara manual.

Mengimplementasikan 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. 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