本頁面由 Cloud Translation API 翻譯而成。

導入預訂伺服器：API v2

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

實作以 gRPC 為基礎的 API 介面

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

根據 gRPC 實作 API 介面。以便 Google 傳送預訂要求。API 介面是使用以 gRPC 的 protobuf 為基礎的 IDL 定義。

我們要求新合作夥伴導入我們建議的 API v2 組合。合作夥伴可為自己的基礎架構選擇最適合的網址和通訊埠。

本節將介紹建議的 API 第 2 版。適用於尚未導入 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 會傳送使用者的姓名、電話號碼和電子郵件地址給合作夥伴。由於 Actions Center 無法在合作夥伴的系統中查詢使用者帳戶，因此應將其視為從合作夥伴觀點的訪客結帳。最終預訂應在合作夥伴的系統中顯示，就像在合作夥伴預訂系統中的預訂一樣。

Java 中的架構實作

您一開始可以先提供 Java 架構的 gRPC 伺服器，可以編譯及安裝。請前往範例 > gRPC 參考資料實作部分進行查看。這個伺服器已抽出支援整合所需的 gRPC 方法，包括驗證和健康服務。

需求條件

gRPC 錯誤和商業邏輯錯誤

合作夥伴後端處理 gRPC 要求時，可能會發生兩種錯誤：錯誤資料導致的意外錯誤；以及無法建立或更新預訂的商業邏輯錯誤 (請參閱預訂失敗相關說明)，例如要求的時段無法使用。

發生非預期的錯誤時，應使用標準 gRPC 錯誤代碼傳回用戶端。相關例子包括但不限於：

INVALID_COUNTRY 用於 CheckAvailability 和 CreateLease 等 RPC，且如果提供的運算單元包含無效資訊，則應傳回。
遠端程序呼叫 (RPC) 會使用 NOT_FOUND (例如 CreateBooking 和 ListBookings)，當合作夥伴不知道提供的 ID 時，就會傳回 NOT_FOUND。

如要瞭解每個方法的標準 gRPC 錯誤代碼，請參閱完整狀態碼清單。

相反地，您應在預訂失敗中擷取商業邏輯錯誤，並在遠端程序呼叫 (RPC) 回應中傳回。建立或更新資源時 (例如在處理遠端程序呼叫 (RPC) CreateBooking 和更新 Booking) 時，可能會發生商業邏輯錯誤。相關例子包括但不限於：

如果要求的運算單元已無法使用，系統會使用 SLOT_UNAVAILABLE。
如果不接受提供的信用卡類型，系統會使用 PAYMENT_ERROR_CARD_TYPE_REJECTED。

冪等

透過網路通訊有時不一定可靠，而如果沒有收到回應，Google Reserve 可能會重試遠端程序呼叫 (RPC)。因此，所有會變動狀態 (CreateBooking、UpdateBooking) 的遠端程序呼叫 (RPC) 都必須為冪等。這些遠端程序呼叫 (RPC) 的要求訊息包括可專門識別要求的冪等符記，並可讓合作夥伴區分重試的遠端程序呼叫 (RPC) (意圖建立單一預訂) 和兩項不同的預訂。

相關例子包括但不限於：

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

冪等性規定適用於所有包含冪等權杖的方法。

gRPC 伺服器安全性和驗證

從 Actions Center 到後端的呼叫必須使用安全資料傳輸層 (SSL)/傳輸層安全標準 (TLS) 和憑證式的雙向用戶端/伺服器驗證來保護。這需要在 gRPC 實作中使用有效的伺服器憑證，並接受有效的用戶端憑證。

伺服器憑證：合作夥伴伺服器必須搭載與伺服器網域名稱相關聯的有效伺服器憑證 (請參閱可接受的根憑證授權單位清單)。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 Authorityity G2 目前建議的根層級。在這兩種情況下，您可能要手動更新根憑證。

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

實作 GRPC 健康狀態檢查通訊協定。這個通訊協定可讓 Google 監控 gRPC 實作的後端狀態。服務規格是 GRPC 發布版本的一部分。遵循 GRPC 命名慣例，健康狀態檢查呼叫中的服務名稱為 ext.maps.booking.partner.v2.BookingService (API v2) 或 ext.maps.booking.partner.v0.BookingService (API v0)。健康狀態檢查應在與另一個端點相同的網址執行，且通訊埠 (PORT) 應相同。

其他版本

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