導入預訂伺服器：API v2

在您這端設定預訂伺服器後，Actions Center 就能代表使用者向您建立預約/預訂。

導入以 gRPC 為基礎的 API 介面

請注意：所有新合作夥伴都應使用 REST API 介面，而非 gRPC API。

導入以 gRPC 為基礎的 API 介面。這樣一來，Google 就能傳送預訂要求。使用 gRPC 的 protobuf 類型 IDL 定義 API 介面。

我們要求新合作夥伴導入建議的 API v2 組合。合作夥伴可以選擇最適合其基礎架構的網址和連接埠。

本節將介紹建議的 API v2 組合。適用於尚未導入 API 第 0 版的合作夥伴。如果是已導入 API v0 的現有合作夥伴，請洽詢 Actions Center 瞭解詳情。

請下載下方 proto 格式的服務定義，開始導入 API。

下載服務定義

API 資源

請熟悉下列資源類型，因為這類資源會在本導入作業中使用：

  • Slot：廣告空間時段
  • 預訂：庫存清單時段的預約

方法

您必須為 gRPC 伺服器實作下列 API 方法：

以下 5 種方法定義了 BookingService RPC 的必要組合：

// 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) {}
}

流程：建立預訂

圖 1：從時段建立預訂

使用者建立預訂時，Google 會將使用者的姓名、電話號碼和電子郵件地址傳送給合作夥伴。從合作夥伴的角度來看，這應視為訪客結帳，因為 Actions Center 無法在合作夥伴的系統中查詢使用者帳戶。最終預訂資訊應透過合作夥伴的系統向合作夥伴的商家顯示，就像合作夥伴的預訂系統一樣。

在 Java 中實作骨架

為協助您開始使用，我們提供可編譯及安裝的 Java 版 gRPC 伺服器架構。請前往「Samples」>「gRPC Reference Implementation」專區查看。這個伺服器已為支援整合作業所需的 gRPC 方法建立 Stubbed，包括驗證和健康狀態服務。

需求條件

gRPC 錯誤和商業邏輯錯誤

合作夥伴後端處理 gRPC 要求時，可能會發生兩種錯誤：因資料不正確而發生的非預期錯誤；以及因無法建立或更新預訂而發生的商業邏輯錯誤 (請參閱「預訂失敗」)，例如無法使用要求的時段。

如果發生非預期的錯誤，請使用標準 gRPC 錯誤代碼傳回給用戶端。相關範例包括但不限於：

  • INVALID_ARGUMENT 會用於 CheckAvailability 和 CreateLease 等 RPC，如果提供的空格包含無效資訊，就應傳回此錯誤。
  • NOT_FOUND 用於 CreateBooking 和 ListBookings 等 RPC，如果合作夥伴不知道提供的 ID，就應傳回此值。

請參閱各個方法的參考資料，瞭解其標準 gRPC 錯誤代碼，或查看完整狀態代碼清單。

相反地，商業邏輯錯誤應擷取於預訂失敗，並在 RPC 回應中傳回。建立或更新資源時可能會發生商業邏輯錯誤，例如在處理 CreateBooking 和 UpdatingBooking 時。相關範例包括但不限於：

  • 如果要求的時段已無法提供，系統會使用 SLOT_UNAVAILABLE。
  • 如果系統不接受提供的信用卡類型，就會使用 PAYMENT_ERROR_CARD_TYPE_REJECTED。

冪等

網路通訊有時不一定可靠；如果未收到任何回應，Google 預訂服務可能會重試 RPC。因此，所有會變更狀態的 RPC (CreateBooking、UpdateBooking) 都必須為冪等。這些 RPC 的請求訊息會包含冪等代碼，用於唯一識別要求，並讓合作夥伴區分重試的 RPC (意圖建立單一預訂) 和兩個個別預訂。

相關範例包括但不限於：

  • 成功的 CreateBooking RPC 回應會包含已建立的預訂，在某些情況下，付款作業會在預訂流程中一併處理。如果第二次收到完全相同的 CreateBookingRequest (包括 idempotency_token)，則必須傳回相同的 CreateBookingResponse。系統不會建立第二筆預訂，且只會向使用者收取一次費用 (如適用)。請注意，如果 CreateBooking 嘗試失敗，合作夥伴後端應在再次傳送相同要求時重試。

冪等要求適用於包含冪等權杖的所有方法。

gRPC 伺服器安全性和驗證

從 Actions Center 到後端的呼叫必須使用 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 網際網路權威機構 G2 目前建議的根。無論是哪種情況，您都可能需要不時手動更新根憑證。

實作 gRPC 健康狀態檢查通訊協定

實作 GRPC 健康狀態檢查通訊協定。這項通訊協定可讓 Google 監控 gRPC 實作項目的後端狀態。服務規格是 GRPC 發行版的一部分。依據 GRPC 命名慣例，健康狀態檢查呼叫中的服務名稱為 API v2 的 ext.maps.booking.partner.v2.BookingService，或 API v0 的 ext.maps.booking.partner.v0.BookingService。健康狀態檢查應在與其他端點相同的網址和通訊埠上執行。

其他版本

如需其他 API 版本的說明文件，請參閱以下頁面： * API v3 * API v0