การตั้งค่าเซิร์ฟเวอร์การจองในฝั่งของคุณจะทำให้ Actions Center สร้างการนัดหมาย / การจอง / การจองกับคุณในนามของผู้ใช้ได้
ใช้อินเทอร์เฟซ API ที่อิงตาม gRPC
โปรดทราบว่าพาร์ทเนอร์รายใหม่ทุกรายควรใช้อินเทอร์เฟซ REST API แทน gRPC API
ใช้อินเทอร์เฟซ API ตาม gRPC ซึ่งจะช่วยให้ Google ส่งคำขอจองได้ แพลตฟอร์ม API จะกำหนดโดยใช้ IDL ที่ใช้ protobuf ของ gRPC
เราขอให้พาร์ทเนอร์รายใหม่ใช้ชุด API เวอร์ชัน 2 ที่แนะนำ พาร์ทเนอร์สามารถเลือก 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 จะส่งชื่อ นามสกุล หมายเลขโทรศัพท์ และอีเมลของผู้ใช้ให้แก่พาร์ทเนอร์ ซึ่งควรถือเป็นการชำระเงินโดยไม่ลงชื่อเข้าใช้จากมุมมองของพาร์ทเนอร์ เนื่องจากศูนย์การดำเนินการไม่มีวิธีใดเพื่อค้นหาบัญชีของผู้ใช้ในระบบของพาร์ทเนอร์ การจองขั้นสุดท้ายควรแสดงให้ผู้ขายของพาร์ทเนอร์เห็นในระบบของพวกเขา เช่นเดียวกับการจองที่มากับระบบการจองของพาร์ทเนอร์
การติดตั้งใช้งาน Skeleton ในชวา
ในการเริ่มต้นใช้งาน เรามีเซิร์ฟเวอร์ Skeleton gRPC ใน Java ซึ่งสามารถคอมไพล์และติดตั้งได้ โปรดไปที่ส่วนตัวอย่าง > การใช้งานข้อมูลอ้างอิง gRPC เซิร์ฟเวอร์นี้ได้ตัดวิธีการ gRPC ที่จำเป็นต่อการรองรับการผสานรวมออกไป รวมถึงการตรวจสอบสิทธิ์และบริการด้านสุขภาพ
ข้อกำหนด
ข้อผิดพลาด gRPC และข้อผิดพลาดด้านตรรกะทางธุรกิจ
ข้อผิดพลาด 2 ประเภทอาจเกิดขึ้นเมื่อแบ็กเอนด์ของพาร์ทเนอร์จัดการคำขอ gRPC ได้แก่ ข้อผิดพลาดที่ไม่คาดคิดซึ่งเกิดจากข้อมูลที่ไม่ถูกต้อง และข้อผิดพลาดด้านตรรกะทางธุรกิจที่บ่งบอกถึงไม่สามารถสร้างหรืออัปเดตการจอง (ดูการจองล้มเหลว) เช่น ช่วงเวลาที่ขอไม่พร้อมใช้งาน
หากพบข้อผิดพลาดที่ไม่คาดคิด ควรส่งกลับไปยังไคลเอ็นต์โดยใช้รหัสข้อผิดพลาด gRPC ตามรูปแบบบัญญัติ ตัวอย่างรวมถึงแต่ไม่จำกัดเฉพาะกรณีต่อไปนี้
- INVALID_ARGUMENT จะใช้ใน RPC เช่น CheckAvailability และ CreateLease และควรแสดงผลหากช่องที่ระบุมีข้อมูลที่ไม่ถูกต้อง
- NOT_FOUND จะใช้ใน RPC เช่น CreateBooking และ ListBookings และควรแสดงผลหากพาร์ทเนอร์ไม่ทราบตัวระบุที่ให้ไว้
ดูข้อมูลอ้างอิงของแต่ละวิธีสำหรับรหัสข้อผิดพลาด gRPC ตามรูปแบบบัญญัติหรือดูรายการรหัสสถานะแบบเต็ม
ในทางตรงกันข้าม ควรบันทึกข้อผิดพลาดด้านตรรกะทางธุรกิจไว้ในการจองไม่สำเร็จและแสดงผลในการตอบสนอง RPC อาจพบข้อผิดพลาดตามตรรกะทางธุรกิจเมื่อสร้างหรืออัปเดตทรัพยากร เช่น ในการจัดการ RPC CreateBooking และอัปเดตการจอง ตัวอย่างรวมถึงแต่ไม่จำกัดเฉพาะกรณีต่อไปนี้
- ระบบจะใช้ SLOT_UNAVAILABLE หากช่องที่ขอไม่พร้อมใช้งานอีกต่อไป
- ระบบจะใช้ PAYMENT_ERROR_CARD_TYPE_REJECTED หากไม่ได้ยอมรับประเภทบัตรเครดิตที่ระบุ
การแสดงถึงตัวตน
การสื่อสารผ่านเครือข่ายอาจไม่น่าเชื่อถือเสมอไป และ Google Reserve อาจลองใช้ RPC อีกครั้งหากไม่ได้รับการตอบกลับ ด้วยเหตุนี้ RPC ทั้งหมดที่เปลี่ยนแปลงสถานะ (CreateBooking, UpdateBooking) จะต้องเป็นแบบเดี่ยว ข้อความคำขอสำหรับ RPC เหล่านี้ประกอบด้วยโทเค็นการแสดงตัวตนเพื่อระบุคำขอโดยไม่ซ้ำกัน และช่วยให้พาร์ทเนอร์แยกความแตกต่างระหว่าง RPC ที่พยายามดำเนินการซ้ำ (โดยมีเจตนาสร้างการจองรายการเดียว) กับการจอง 2 รายการแยกกัน
ตัวอย่างรวมถึงแต่ไม่จำกัดเฉพาะกรณีต่อไปนี้
- การตอบกลับ RPC สำหรับ CreateBooking ที่ประสบความสำเร็จจะรวมการจองที่สร้างขึ้น และในบางกรณี การชำระเงินจะได้รับการประมวลผลโดยเป็นส่วนหนึ่งของขั้นตอนการจอง หากได้รับ CreateBookingRequest ที่เหมือนกันเป็นครั้งที่ 2 (รวม
idempotency_token) ก็จะต้องส่งคืน CreateBookingResponse เดิม ไม่มีการสร้างการจองครั้งที่ 2 และ จะมีการเรียกเก็บเงินจากผู้ใช้เพียงครั้งเดียว (หากมี) โปรดทราบว่าหากพยายาม CreateBooking ไม่สำเร็จ แบ็กเอนด์ของพาร์ทเนอร์ควรลองอีกครั้งหากมีการส่งคำขอเดิมอีกครั้ง
ข้อกำหนดด้านการมีตัวตนจะมีผลกับทุกเมธอดที่มีโทเค็นการมีตัวตน
ความปลอดภัยและการตรวจสอบสิทธิ์ของเซิร์ฟเวอร์ gRPC
การเรียกใช้จาก Actions Center ไปยังแบ็กเอนด์ต้องมีการรักษาความปลอดภัยด้วย SSL/TLS ที่มีการตรวจสอบสิทธิ์ไคลเอ็นต์/เซิร์ฟเวอร์ร่วมกันตามใบรับรอง โดยต้องใช้ใบรับรองเซิร์ฟเวอร์ที่ถูกต้องสำหรับการใช้งาน gRPC และยอมรับใบรับรองไคลเอ็นต์ที่ถูกต้อง
ใบรับรองเซิร์ฟเวอร์: เซิร์ฟเวอร์พาร์ทเนอร์ต้องมีใบรับรองเซิร์ฟเวอร์ที่ถูกต้องซึ่งเชื่อมโยงกับชื่อโดเมนของเซิร์ฟเวอร์ (ดูรายการ CA รูทที่ยอมรับ) การใช้งานเซิร์ฟเวอร์ GRPC ควรให้บริการเชนใบรับรองที่นำไปสู่ใบรับรองรูท วิธีที่ง่ายที่สุดคือการใส่ใบรับรองกลางที่โฮสต์เว็บของพาร์ทเนอร์ให้ไว้ในรูปแบบ PEM ต่อท้ายใบรับรองเซิร์ฟเวอร์ (ซึ่งอยู่ในรูปแบบ PEM เช่นกัน)
ใบรับรองเซิร์ฟเวอร์จะได้รับการยืนยัน ณ เวลาการเชื่อมต่อ และจะไม่มีการยอมรับใบรับรองแบบ Self-signed เนื้อหาใบรับรองตามจริงจะไม่ได้รับการตรวจสอบตราบใดที่ใบรับรองใช้งานได้ คุณสามารถตรวจสอบความถูกต้องของใบรับรองผ่านคำสั่งต่อไปนี้
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 InternetAuthority G2 แนะนำในปัจจุบันก็ได้ ในทั้ง 2 กรณี คุณอาจต้องอัปเดตใบรับรองรูทด้วยตนเองเป็นครั้งคราว
ใช้โปรโตคอลการตรวจสอบประสิทธิภาพการทำงานของ gRPC
ใช้โปรโตคอลการตรวจสอบประสิทธิภาพการทำงานของ GRPC
โปรโตคอลนี้จะช่วยให้ Google ตรวจสอบสถานะแบ็กเอนด์ของการใช้งาน gRPC ได้ ข้อกําหนดในการให้บริการเป็นส่วนหนึ่งของการเผยแพร่ GRPC ตามแบบแผนการตั้งชื่อ GRPC ชื่อบริการในการเรียกใช้การตรวจสอบประสิทธิภาพการทำงานคือ ext.maps.booking.partner.v2.BookingService สำหรับ API v2 หรือ ext.maps.booking.partner.v0.BookingService สำหรับ API v0 การตรวจสอบประสิทธิภาพการทำงานควรทำงานบน URL และพอร์ตเดียวกับปลายทางอื่นๆ
เวอร์ชันอื่นๆ
ดูเอกสารประกอบสำหรับ API เวอร์ชันอื่นๆ ได้ที่หน้าต่อไปนี้ * API v3 * API v0