您必須建立預訂伺服器,才能讓 Actions Center 進行回呼,代表您建立及更新預訂。
- 實作預訂等候名單。在您參與預訂等候名單前測計畫時,系統會使用這項資訊。這樣一來,Actions Center 就能擷取預估等候時間,並代表使用者建立等候名單項目。
- 標準導入:這可讓 Actions Center 代表使用者為您建立預約、預訂和預訂事宜。如要導入「預訂」端對端整合的預訂伺服器,請參閱「導入預訂伺服器」一文。
請參閱合作夥伴入口網站說明文件,瞭解如何設定與沙箱及實際執行預訂伺服器的連線。
導入 REST API 介面
導入以 REST 為基礎的 API 介面,這可讓 Google 透過 HTTP 傳送預訂伺服器要求。
首先,請設定開發或沙箱預訂伺服器,以便連結至 Actions Center 沙箱環境。您必須先完整測試沙箱伺服器,才能移至實際執行環境。
方法
您必須針對每種預訂伺服器採用不同的 API 方法,您也可以選擇以 proto 格式下載服務定義,然後開始實作 API。下表說明各種實作的方法,並提供服務 proto 格式的連結。
等候名單導入 |
---|
等候名單服務定義:下載 proto 服務定義檔案。 |
方法 | HTTP 要求 |
---|---|
HealthCheck | GET /v3/HealthCheck/ |
BatchGetWaitEstimates | POST /v3/BatchGetWaitEstimates/ |
CreateWaitlistEntry | POST /v3/CreateWaitlistEntry/ |
GetWaitlistEntry | POST /v3/GetWaitlistEntry/ |
DeleteWaitlistEntry | POST /v3/DeleteWaitlistEntry/ |
API 資源
等候名單
以下資源可用於導入以等候名單為基礎的預訂:
- WaitEstimate:特定預訂人數和商家的預估等候時間。
- WaitlistEntry:等候名單中的使用者項目。
流程:建立等候名單項目
本節說明如何為預訂等候名單整合建立預訂。
![圖 2:建立等候名單項目的工作流程](https://developers-dot-devsite-v2-prod.appspot.com/static/actions-center/images/waitlists/rest_api_v3_waitlist_flow.png?authuser=6&hl=zh-tw)
使用者建立等候名單項目時,Google 會將使用者的姓名、電話號碼和電子郵件地址傳送給您。電子郵件地址與使用者的 Google 帳戶相同,並視為專屬 ID。從您的角度來看,這份等候名單必須視為訪客結帳,因為「透過 Google 預訂」功能無法在您的系統中查詢使用者帳戶。請確認最終等候名單項目與等候名單系統中的商家項目資訊相同。
安全性和驗證
所有與預訂伺服器的通訊都是透過 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 回應傳回。建立資源時可能會發生商業邏輯錯誤,例如處理 CreateWaitlistEntry
方法時。相關示例包括但不限於下列幾項:
- 如果要求的等候名單項目超過商家的預訂人數上限,系統會使用
ABOVE_MAX_PARTY_SIZE
。 - 如果商家已關閉,導致未開放等候名單,系統會使用
MERCHANT_CLOSED
。
冪等
透過網路通訊有時不一定可靠,如果沒有收到回應,Google 可能會重試 HTTP 要求。因此,所有會改變狀態的方法都必須為冪等:
CreateWaitlistEntry
DeleteWaitlistEntry
針對 DeleteWaitlistEntry
以外的所有要求訊息,系統都會顯示冪等權杖,以便識別該項要求。這可讓您區分重試的 REST 呼叫,且意圖建立單一要求和兩個不同的要求。DeleteWaitlistEntry
分別以等候名單項目 ID 識別,因此這類要求中不包含冪等權杖。
以下是預訂伺服器處理冪等的一些範例:
成功的
CreateWaitlistEntry
HTTP 回應會包含已建立的等候名單項目 ID。如果第二次收到相同的CreateWaitlistEntryRequest
(具有相同的idempotency_token
),則必須傳回相同的CreateWaitlistEntryResponse
。系統不會建立第二個等候名單項目,也不會傳回任何錯誤。請注意,如果發生
CreateWaitlistEntry
嘗試失敗且系統重新傳送相同要求,則您的後端應重試。
冪等要求適用於會使狀態變動的所有方法。