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

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

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

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

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

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

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

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

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

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

API リソース

この実装で使用される次のリソースタイプについてよく理解してください。

スロット: 広告枠スロット
予約: 在庫スロットの予約

Methods

次の API メソッドが gRPC サーバー用にお客様側で実装される必要があります。

以下の 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 でのスケルトン実装

まず、コンパイルとインストールが可能なスケルトン gRPC サーバーを Java で提供しています。[Samples] > [gRPC Reference Implementation] の順に移動します。このサーバーでは、認証やヘルスサービスなど、統合をサポートするために必要な gRPC メソッドがスタブ化されています。

要件

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

パートナーバックエンドが gRPC リクエストを処理するときに発生するエラーは 2 つあります。1 つは不正確なデータに起因する予期しないエラーです。もう 1 つは、予約を作成または更新できないことを示すビジネスロジックエラー（予約失敗を参照）です（リクエストされたスロットが利用できない場合など）。

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

INVALID_ARGUMENT は、CheckAvailability や CreateLease などの RPC で使用され、提供されたスロットに無効な情報が含まれる場合に返されます。
NOT_FOUND は CreateBooking や ListBookings などの RPC で使用され、提供された ID がパートナーにわからない場合は返されます。

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

一方、ビジネスロジックのエラーは Booking Failure でキャプチャされ、RPC レスポンスで返されます。リソースの作成時または更新時（RPC CreateBooking と UpdateBooking の処理）で、ビジネスロジックエラーが発生することがあります。以下に例を示しますが、これらに限定されません。

SLOT_UNAVAILABLE は、リクエストされたスロットが利用できなくなった場合に使用されます。
PAYMENT_ERROR_CARD_TYPE_REJECTED は、指定されたクレジットカードの種類が受け入れられない場合に使用されます。

べき等性

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

以下に例を示しますが、これらに限定されません。

CreateBooking RPC 成功のレスポンスには作成された予約が含まれます。また、予約フローの一部として支払いが処理されることもあります。まったく同じ CreateBookingRequest が 2 回目（idempotency_token を含む）を受け取った場合は、同じ 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