導入預訂伺服器：API v2

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

導入以 gRPC 為基礎的 API 介面

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

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

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

本節將介紹建議的 API v2 組合。適用於尚未導入 API v0 的合作夥伴。如果目前的合作夥伴已導入 API v0，請與 Actions Center 聯絡以瞭解詳情。

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

下載服務定義

API 資源

請熟悉下列資源類型，這些類型將用於本次實作：

Slot：庫存清單時段
Booking：庫存清單時段的預約

方法

您必須在 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) {}
}

流程：建立預訂

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

Java 中的基本架構實作

為協助您開始使用，我們提供 Java 的 gRPC 伺服器架構，可供編譯及安裝。請參閱「範例 > gRPC 參考實作」一節。這個伺服器已存根化支援整合所需的 gRPC 方法，包括驗證和健康狀態服務。

需求條件

gRPC 錯誤和商業邏輯錯誤

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

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

INVALID_ARGUMENT 用於 CheckAvailability 和 CreateLease 等 RPC，如果提供的時段含有無效資訊，就應傳回這項錯誤。
NOT_FOUND 用於 CreateBooking 和 ListBookings 等 RPC，如果合作夥伴不知道提供的 ID，就應傳回這個錯誤。

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

反之，商業邏輯錯誤應擷取自「預訂失敗」，並在 RPC 回應中傳回。建立或更新資源時可能會發生商業邏輯錯誤，也就是處理 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 網際網路授權單位 G2 核發的用戶端憑證 (CA 憑證)，並具備下列屬性：

欄位	值
`CN`	mapsbooking.businesslink-3.net
`SAN`	DNS：mapsbooking.businesslink-3.net

合作夥伴伺服器應拒絕未提供這項用戶端憑證的連線嘗試。

為驗證用戶端憑證，伺服器會使用一組信任的用戶端根憑證。您可以選擇從 Mozilla 等機構取得這組信任的根憑證，或是安裝 Google Internet Authority 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