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