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

予約サーバーを設定すると、アクションセンターでユーザーに代わって予約を作成できるようになります。

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

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

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

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

このセクションでは、推奨される API v2 のセットを紹介します。API v0 を実装していないパートナーに適用されます。API v0 を実装済みの既存のパートナー様は、アクションセンターにお問い合わせください。

API の実装を開始するには、以下の proto 形式のサービス定義をダウンロードします。

サービス定義をダウンロードする

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 リクエストを処理する際に、2 種類のエラーが発生することがあります。不適切なデータが原因で発生する予期しないエラーと、予約の作成または更新ができないことを示すビジネスロジックエラー（予約の失敗を参照）。たとえば、リクエストされた時間枠が利用できない場合などです。

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

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

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

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

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

べき等性

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

これには次のような使用法が含まれますが、これらに限定されません。

成功した CreateBooking RPC レスポンスには、作成された予約が含まれます。場合によっては、予約フローの一部として決済が処理されます。同じ CreateBookingRequest を 2 回受け取った場合（idempotency_token を含む）は、同じ CreateBookingResponse を返す必要があります。2 回目の予約は作成されず、その場合、ユーザーは 1 回のみ請求されます。CreateBooking の試行が失敗し、同じリクエストが再度送信された場合は、パートナーバックエンドで再試行する必要があります。

べき等性の要件は、べき等性トークンを含むすべてのメソッドに適用されます。

gRPC サーバーのセキュリティと認証

アクションセンターからバックエンドへの呼び出しは、証明書ベースの相互クライアント/サーバー認証による 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 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