このページは Cloud Translation API によって翻訳されました。

予約サーバーの実装: API v2

予約サーバーを設定すると、Actions Center はユーザーに代わって予約を作成できます。

gRPC に基づいて API インターフェースを実装する

注: 新しいパートナーはすべて、gRPC API ではなく REST API インターフェースを使用する必要があります。

gRPC に基づいて API インターフェースを実装します。これにより、Google のシステムが予約リクエストを送信できるようになります。API サーフェスは、gRPC の protobuf ベースの IDL を使用して定義されます。

新規パートナーには、推奨の API v2 のセットを実装していただくようお願いしています。パートナーは、インフラストラクチャに最適な URL とポートを選択できます。

このセクションでは、推奨される 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) {}
}

フロー: 予約を作成

予約の作成時に、ユーザーの氏名、電話番号、メールアドレスがパートナーに送信されます。Actions Center ではパートナーのシステム内のユーザーアカウントを検索できないため、これはパートナーの視点から「ログインせずに決済」として処理する必要があります。最終的な予約は、パートナーの予約システムからの予約と同様に、パートナーの販売者のシステムに表示されます。

Java でのスケルトンの実装

始めに、コンパイルしてインストールできる Java のスケルトン gRPC サーバーを用意します。[サンプル] > [gRPC リファレンス実装] セクションで確認できます。このサーバーは、認証やヘルスサービスなど、統合をサポートするために必要な gRPC メソッドをスタブ化しています。

要件

gRPC エラーとビジネスロジックエラー

パートナーのバックエンドで gRPC リクエストを処理する際に、2 種類のエラーが発生する可能性があります。1 つは、不適切なデータが原因で発生する予期しないエラーです。もう 1 つは、予約の作成または更新ができないことを示すビジネスロジックのエラーです（予約の失敗を参照）。たとえば、リクエストされた時間枠が利用できない場合があります。

予期しないエラーが発生した場合は、標準の gRPC エラーコードを使用してクライアントに返す必要があります。これには次のものが含まれますが、これらに限定されません。

INVALID_ARGUMENT は、CheckAvailability や CreateLease などの RPC で使用され、指定されたスロットに無効な情報が含まれている場合に返されます。
NOT_FOUND は、CreateBooking や ListBookings などの RPC で使用され、指定された ID がパートナーにとって不明な場合に返す必要があります。

正規の gRPC エラーコードについては、各メソッドのリファレンスをご覧ください。または、完全なステータスコードのリストをご覧ください。

一方、ビジネスロジックのエラーは BookingFailure に記録し、RPC レスポンスで返す必要があります。リソースの作成または更新時に、ビジネスロジックのエラーが発生することがあります。たとえば、RPC CreateBooking と UpdatingBooking の処理で発生することがあります。これには次のものが含まれますが、これらに限定されません。

リクエストされた時間枠が使用できなくなった場合は、SLOT_UNAVAILABLE が使用されます。
指定されたクレジットカードの種類を承認できない場合は、PAYMENT_ERROR_CARD_TYPE_REJECTED が使用されます。

べき等性

ネットワーク経由の通信は常に信頼できるわけではなく、Google 予約は、レスポンスを受信でない場合に RPC を再試行することがあります。そのため、状態を変更するすべての RPC（CreateBooking、UpdateBooking）はべき等である必要があります。これらの RPC のリクエストメッセージには、リクエストを一意に識別するためのべき等性トークンが含まれます。これにより、パートナーは、（単一の予約を作成する目的で）再試行された RPC と 2 つの個別の予約を区別できます。

これには次のものが含まれますが、これらに限定されません。

成功した CreateBooking RPC レスポンスには、作成された予約が含まれます。場合によっては、予約フローの一部として決済が処理されます。同じ CreateBookingRequest（idempotency_token を含む）を 2 回受け取った場合は、同じ CreateBookingResponse を返す必要があります。2 回目の予約は作成されず、その場合、ユーザーは 1 回のみ請求されます。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 として）認証されるように、Google Internet Authority 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 です。ヘルスチェックは、他のエンドポイントと同じ URL とポートで実行する必要があります。

他のバージョン

他のバージョンの API のドキュメントについては、次のページをご覧ください。 * API v3 * API v0