您必須建立預訂伺服器,才能讓 Actions Center 進行回呼,代表您建立及更新預訂。
- 標準導入:這可讓 Actions Center 代表使用者為您建立預約、預訂和預訂事宜。
請參閱合作夥伴入口網站說明文件,瞭解如何設定與沙箱及實際執行預訂伺服器的連線。
導入 REST API 介面
導入以 REST 為基礎的 API 介面,這可讓 Google 透過 HTTP 傳送預訂伺服器要求。
首先,請設定開發或沙箱預訂伺服器,以便連結至 Actions Center 沙箱環境。您必須先完整測試沙箱伺服器,才能移至實際執行環境。
方法
您必須針對每種預訂伺服器採用不同的 API 方法,您也可以選擇以 proto 格式下載服務定義,然後開始實作 API。下表說明各種實作的方法,並提供服務 proto 格式的連結。
標準導入 |
---|
標準服務定義:下載 proto 服務定義檔案。 |
方法 | HTTP 要求 |
---|---|
HealthCheck | GET /v3/HealthCheck/ |
BatchAvailabilityLookup | POST /v3/BatchAvailabilityLookup/ |
CreateBooking | POST /v3/CreateBooking/ |
UpdateBooking | POST /v3/UpdateBooking/ |
GetBookingStatus | POST /v3/GetBookingStatus/ |
ListBookings | POST /v3/ListBookings/ |
API 資源
預訂
下列資源類型可用於標準導入:
流程:建立預訂
本節說明如何為標準導入建立預訂。
![圖 1:從時段建立預訂的工作流程](https://developers-dot-devsite-v2-prod.appspot.com/static/actions-center/images/rest_api_v3_booking_flow_1.png?authuser=7&hl=zh-tw)
使用者建立預訂時,Google 會將使用者的姓名、電話號碼和電子郵件地址傳送給您。從您的視角,這個預訂必須視為訪客結帳,因為 Actions Center 無法在您的系統中查詢使用者帳戶。請確認最終預訂資訊與預訂系統中的商家預訂資訊一致。
安全性和驗證
所有與預訂伺服器的通訊都是透過 HTTPS 進行,因此伺服器必須具備與 DNS 名稱相符的有效傳輸層安全標準 (TLS) 憑證。為協助您設定伺服器,建議您使用公開的 SSL/TLS 驗證工具,例如 Qualys 的 SSL 伺服器測試。
Google 對預訂伺服器發出的所有要求都會使用 HTTP 基本驗證進行驗證。您可以前往合作夥伴入口網站的「預訂伺服器設定」頁面,輸入預訂伺服器的基本驗證憑證 (使用者名稱和密碼)。密碼必須每六個月輪替一次。
範例基本架構導入
首先,請查看下列專為 Node.js 和 Java 架構編寫的預訂伺服器基本架構範例:
- Node.js 基本架構 js-maps-booking-rest-server-v3-skeleton
- Java 架構 java-maps-booking-rest-server-v3-skeleton
這些伺服器已利用虛設常式模擬 REST 方法;
需求條件
HTTP 錯誤和商業邏輯錯誤
在後端處理 HTTP 要求時,可能會發生兩種錯誤。
- 基礎架構或資料錯誤相關錯誤
- 將這些錯誤傳回給用戶端,並附上標準 HTTP 錯誤代碼。 請參閱 HTTP 狀態碼完整清單。
- 商業邏輯相關錯誤
- 傳回設為
200
OK 的 HTTP 狀態碼,並在回應主體中指定商業邏輯失敗。不同類型的伺服器實作方式可能會遇到不同的商業邏輯錯誤。
- 傳回設為
如果是標準導入作業,系統會從預訂失敗中擷取可能的商業邏輯錯誤,並透過 HTTP 回應傳回。建立或更新資源時可能會發生商業邏輯錯誤。例如處理 CreateBooking
或 UpdatingBooking
方法時。相關範例包括但不限於:
- 如果要求的時段已無法使用,則會使用
SLOT_UNAVAILABLE
。 - 如果不接受提供的信用卡類型,系統會使用
PAYMENT_ERROR_CARD_TYPE_REJECTED
。
冪等
透過網路通訊有時不一定可靠,如果沒有收到回應,Google 可能會重試 HTTP 要求。因此,所有會改變狀態的方法都必須為冪等:
CreateBooking
UpdateBooking
針對 UpdateBooking
以外的所有要求訊息,系統都會顯示冪等權杖,以便識別該項要求。這可讓您區分重試的 REST 呼叫,且意圖建立單一要求和兩個不同的要求。UpdateBooking
是專屬於其預訂項目 ID 的專屬識別碼,因此這類要求中不包含冪等代碼。
以下是預訂伺服器處理冪等的一些範例:
成功的
CreateBooking
HTTP 回應會包含已建立的預訂。在某些情況下,付款作業會在預訂流程中處理。如果第二次收到完全相同的CreateBookingRequest
(具有相同的idempotency_token
),則必須傳回相同的CreateBookingResponse
。系統不會建立第二筆預訂,且只會向使用者收取一次費用 (如適用)。請注意,如果發生
CreateBooking
嘗試失敗且系統重新傳送相同要求,您的後端應進行重試。
冪等要求適用於會使狀態變動的所有方法。