การตั้งค่าเซิร์ฟเวอร์การจองในฝั่งของคุณจะช่วยให้ศูนย์การดำเนินการสร้างการนัดหมาย / การจอง / การจองกับคุณในนามของผู้ใช้ได้
ใช้อินเทอร์เฟซ API ตาม gRPC
โปรดทราบว่าพาร์ทเนอร์ใหม่ทั้งหมดควรใช้อินเทอร์เฟซ REST API แทน gRPC
ใช้อินเทอร์เฟซ API ตาม gRPC ซึ่งจะช่วยให้ Google ส่งคำขอจองได้ อินเทอร์เฟซ API ได้รับการกําหนดโดยใช้ IDL ที่อิงตาม protobuf ของ gRPC
เราขอให้พาร์ทเนอร์รายใหม่ใช้ชุด API v2 ที่แนะนํา พาร์ทเนอร์สามารถเลือก URL และพอร์ตที่เหมาะกับโครงสร้างพื้นฐานของตนมากที่สุด
ส่วนนี้จะแนะนำชุด API v2 ที่แนะนํา โดยจะมีผลกับพาร์ทเนอร์ที่ไม่ได้ใช้งาน API v0 สำหรับพาร์ทเนอร์ปัจจุบันที่ใช้ API v0 โปรดติดต่อศูนย์การดำเนินการเพื่อดูข้อมูลเพิ่มเติม
ดาวน์โหลดคําจํากัดความของบริการในรูปแบบโปรโตด้านล่างเพื่อเริ่มต้นใช้งาน API
แหล่งข้อมูล API
โปรดทำความคุ้นเคยกับประเภททรัพยากรต่อไปนี้ที่จะนำมาใช้ในการติดตั้งใช้งานนี้
เมธอด
คุณต้องติดตั้งใช้งานเมธอด API ต่อไปนี้ฝั่งคุณสำหรับเซิร์ฟเวอร์ gRPC
5 วิธีต่อไปนี้จะกำหนดชุด RPC ของ BookingService ที่จำเป็น
// 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) {}
}
ขั้นตอน: สร้างการจอง
เมื่อสร้างการจอง Google จะส่งชื่อนามสกุล หมายเลขโทรศัพท์ และอีเมลของผู้ใช้ให้พาร์ทเนอร์ การดำเนินการนี้ควรถือเป็นการชำระเงินโดยไม่ลงชื่อเข้าใช้จากมุมมองของพาร์ทเนอร์ เนื่องจากศูนย์การดําเนินการไม่มีวิธีค้นหาบัญชีของผู้ใช้ในระบบของพาร์ทเนอร์ การจองขั้นสุดท้ายควรแสดงต่อผู้ขายของพาร์ทเนอร์ในระบบของพาร์ทเนอร์เช่นเดียวกับการจองที่มาจากระบบการจองของพาร์ทเนอร์
การติดตั้งใช้งานโครงกระดูกใน Java
ในการเริ่มต้นใช้งาน เรามีเซิร์ฟเวอร์ gRPC โครงร่างใน Java ที่คอมไพล์และติดตั้งได้ โปรดดูในส่วนตัวอย่าง > การใช้งานอ้างอิง gRPC เซิร์ฟเวอร์นี้มีเมธอด gRPC ที่จําเป็นต่อการสนับสนุนการผสานรวม รวมถึงการตรวจสอบสิทธิ์และบริการตรวจสอบประสิทธิภาพ
ข้อกำหนด
ข้อผิดพลาด gRPC และข้อผิดพลาดตรรกะทางธุรกิจ
ข้อผิดพลาด 2 ประเภทที่อาจเกิดขึ้นเมื่อแบ็กเอนด์ของพาร์ทเนอร์จัดการคำขอ gRPC ได้แก่ ข้อผิดพลาดที่ไม่คาดคิดซึ่งเกิดจากข้อมูลที่ไม่ถูกต้อง และข้อผิดพลาดของตรรกะทางธุรกิจที่บ่งบอกว่าสร้างหรืออัปเดตการจองไม่ได้ (ดูการจองไม่สำเร็จ) เช่น หากไม่มีช่องที่ขอ
หากพบข้อผิดพลาดที่ไม่คาดคิด คุณควรส่งข้อผิดพลาดดังกล่าวกลับไปยังไคลเอ็นต์โดยใช้รหัสข้อผิดพลาด gRPC มาตรฐาน ตัวอย่างรวมถึงแต่ไม่จำกัดเพียงรายการต่อไปนี้
- INVALID_ARGUMENT ใช้กับ RPC เช่น CheckAvailability และ CreateLease และควรแสดงผลหากช่องที่ระบุมีข้อมูลไม่ถูกต้อง
- NOT_FOUND ใช้กับ RPC เช่น CreateBooking และ ListBookings และควรแสดงผลหากพาร์ทเนอร์ไม่ทราบตัวระบุที่ระบุ
ดูข้อมูลอ้างอิงของแต่ละเมธอดสำหรับรหัสข้อผิดพลาด gRPC ที่เป็นมาตรฐาน หรือดูรายการรหัสสถานะทั้งหมด
ในทางตรงกันข้าม ข้อผิดพลาดของตรรกะทางธุรกิจควรบันทึกไว้ใน Booking Failure และส่งคืนในการตอบกลับ RPC คุณอาจพบข้อผิดพลาดของตรรกะทางธุรกิจเมื่อสร้างหรืออัปเดตทรัพยากร เช่น ในการจัดการ RPC CreateBooking และ UpdatingBooking ตัวอย่างรวมถึงแต่ไม่จำกัดเพียงรายการต่อไปนี้
- ระบบจะใช้ SLOT_UNAVAILABLE หากช่องที่ขอไม่พร้อมใช้งานอีกต่อไป
- ระบบจะใช้ PAYMENT_ERROR_CARD_TYPE_REJECTED หากระบบไม่ยอมรับประเภทบัตรเครดิตที่ระบุ
การทำงานซ้ำ
การสื่อสารผ่านเครือข่ายอาจไม่น่าเชื่อถือเสมอไป และ Google Reserve อาจลองส่ง RPC อีกครั้งหากไม่ได้รับการตอบกลับ ด้วยเหตุนี้ RPC ทั้งหมดที่เปลี่ยนแปลงสถานะ (CreateBooking, UpdateBooking) จึงต้องเป็นการดำเนินการแบบ idempotent ข้อความคำขอสำหรับ RPC เหล่านี้จะมีโทเค็นแบบซ้ำกันเพื่อระบุคำขอที่ไม่ซ้ำกันและช่วยให้พาร์ทเนอร์แยกความแตกต่างระหว่าง RPC ที่ลองอีกครั้ง (โดยมีเจตนาสร้างการจองครั้งเดียว) กับการจอง 2 รายการแยกกันได้
ตัวอย่างรวมถึงแต่ไม่จำกัดเพียงรายการต่อไปนี้
- การตอบกลับ CreateBooking RPC ที่ดำเนินการสำเร็จจะรวมการจองที่สร้างขึ้น และระบบจะประมวลผลการชำระเงินเป็นส่วนหนึ่งของขั้นตอนการจองในบางกรณี หากได้รับ CreateBookingRequest เดียวกันนี้อีกครั้ง (รวมถึง
idempotency_token) จะต้องส่ง CreateBookingResponse เดียวกันนี้ ระบบจะไม่สร้างการจองครั้งที่ 2 และระบบจะเรียกเก็บเงินจากผู้ใช้เพียงครั้งเดียว (หากมี) โปรดทราบว่าหากพยายามสร้างการจองไม่สำเร็จ แบ็กเอนด์ของพาร์ทเนอร์ควรลองอีกครั้งหากมีการส่งคำขอเดียวกันอีกครั้ง
ข้อกำหนดเกี่ยวกับการทำงานซ้ำมีผลกับเมธอดทั้งหมดที่มีโทเค็นการทำงานซ้ำ
ความปลอดภัยและการตรวจสอบสิทธิ์ของเซิร์ฟเวอร์ gRPC
การเรียกใช้จากศูนย์การดำเนินการไปยังแบ็กเอนด์ต้องปลอดภัยโดยใช้ SSL/TLS ที่มีการรับรองไคลเอ็นต์/เซิร์ฟเวอร์ร่วมกันโดยอิงตามใบรับรอง ซึ่งต้องใช้ใบรับรองเซิร์ฟเวอร์ที่ถูกต้องสําหรับการติดตั้งใช้งาน gRPC และยอมรับใบรับรองไคลเอ็นต์ที่ถูกต้อง
ใบรับรองเซิร์ฟเวอร์: เซิร์ฟเวอร์ของพาร์ทเนอร์ต้องมีใบรับรองเซิร์ฟเวอร์ที่ถูกต้องซึ่งเชื่อมโยงกับชื่อโดเมนของเซิร์ฟเวอร์ (ดูรายการ CA รูทที่ยอมรับ) การติดตั้งใช้งานเซิร์ฟเวอร์ GRPC คาดว่าจะแสดงเชนใบรับรองที่นําไปยังใบรับรองรูท วิธีดำเนินการที่ง่ายที่สุดคือการเพิ่มใบรับรองกลางที่โฮสต์เว็บของพาร์ทเนอร์ให้มาในรูปแบบ PEM ต่อท้ายใบรับรองเซิร์ฟเวอร์ (ในรูปแบบ PEM เช่นกัน)
ระบบจะยืนยันใบรับรองเซิร์ฟเวอร์เมื่อเชื่อมต่อ และจะไม่ยอมรับใบรับรองที่ลงนามด้วยตนเอง ระบบจะไม่ตรวจสอบเนื้อหาของใบรับรองจริง ตราบใดที่ใบรับรองนั้นถูกต้อง คุณตรวจสอบความถูกต้องของใบรับรองได้ผ่านคําสั่งต่อไปนี้
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
ใบรับรองไคลเอ็นต์: เรามีใบรับรองไคลเอ็นต์ที่ออกโดย Google Internet Authority G2 (ใบรับรอง CA) ซึ่งมีพร็อพเพอร์ตี้ต่อไปนี้เพื่อตรวจสอบสิทธิ์กับพาร์ทเนอร์ (ในฐานะ Google)
| ช่อง | ค่า |
|---|---|
CN |
mapsbooking.businesslink-3.net |
SAN |
DNS:mapsbooking.businesslink-3.net |
เซิร์ฟเวอร์ของพาร์ทเนอร์ควรปฏิเสธการเชื่อมต่อที่ไม่มีใบรับรองไคลเอ็นต์นี้
เซิร์ฟเวอร์จะใช้ชุดใบรับรองรูทไคลเอ็นต์ที่เชื่อถือได้เพื่อตรวจสอบใบรับรองไคลเอ็นต์ คุณสามารถเลือกรับชุดรูทที่เชื่อถือได้นี้จากหน่วยงานที่เชื่อถือได้ เช่น Mozilla หรือติดตั้งชุดรูทที่ Google Internet Authority G2 แนะนำในปัจจุบัน ไม่ว่าในกรณีใด คุณอาจต้องอัปเดตใบรับรองรูทด้วยตนเองในบางครั้ง
ใช้โปรโตคอลการตรวจสอบประสิทธิภาพการทํางาน gRPC
ใช้โปรโตคอลการตรวจสอบประสิทธิภาพการทํางานของ GRPC
โปรโตคอลนี้ช่วยให้ Google ตรวจสอบสถานะแบ็กเอนด์ของการติดตั้งใช้งาน gRPC ได้ ข้อกำหนดของบริการเป็นส่วนหนึ่งของการแจกจ่าย GRPC ตามรูปแบบการตั้งชื่อ GRPC ชื่อบริการในการเรียกการตรวจสอบสถานะจะเป็น ext.maps.booking.partner.v2.BookingService สำหรับ API เวอร์ชัน 2 หรือ ext.maps.booking.partner.v0.BookingService สำหรับ API เวอร์ชัน 0 การตรวจสอบประสิทธิภาพการทำงานควรทำงานบน URL และพอร์ตเดียวกับปลายทางอื่นๆ
เวอร์ชันอื่นๆ
ดูเอกสารประกอบสำหรับ API เวอร์ชันอื่นๆ ได้ที่หน้าต่อไปนี้ * API v3 * API v0