予約サーバーを立ち上げて、アクション センターがユーザーに代わって予約を作成および更新するためのコールバックを実行できるようにする必要があります。
- 標準実装。これにより、アクション センターがユーザーに代わって予約を作成できるようになります。
サンドボックスや本番環境の予約サーバーへの接続を設定する方法については、パートナー ポータルのドキュメントをご覧ください。
REST API インターフェースを実装する
REST ベースの API インターフェースを実装すると、Google が HTTP 経由で予約サーバー リクエストを送信できるようになります。
まず、Actions Center のサンドボックス環境に接続できる開発用またはサンドボックスの予約サーバーをセットアップします。本番環境に移行できるのは、サンドボックス サーバーのテストがすべて完了してからです。
Methods
予約サーバーの種類ごとに、お客様側で必要な API メソッドのセットが異なります。必要に応じて、サービス定義を proto 形式でダウンロードして、API の実装を開始できます。次の表に、各実装のメソッドと、サービス proto 形式へのリンクを示します。
標準の実装 |
---|
標準サービス定義: proto サービス定義ファイルをダウンロードします。 |
メソッド | HTTP リクエスト |
---|---|
HealthCheck | GET /v3/HealthCheck/ |
BatchAvailabilityLookup | POST /v3/BatchAvailabilityLookup/ |
CreateBooking | POST /v3/CreateBooking/ |
UpdateBooking | POST /v3/UpdateBooking/ |
GetBookingStatus | POST /v3/GetBookingStatus/ |
ListBookings | POST /v3/ListBookings/ |
API リソース
Booking
標準の実装では次のリソースタイプが使用されます。
フロー: 予約を作成
このセクションでは、標準実装で予約を作成する方法について説明します。
![図 1: スロットから予約を作成するワークフロー](https://developers-dot-devsite-v2-prod.appspot.com/static/actions-center/images/rest_api_v3_booking_flow_1.png?authuser=7&hl=ja)
ユーザーが予約を作成すると、Google からユーザーの氏名、電話番号、メールアドレスが送信されます。アクション センターはシステム内でユーザーのアカウントを参照できないため、この予約は「ログインせずに決済」として扱う必要があります。最終的な予約が、貴社の予約システムからの販売者の予約と同一であることを確認してください。
セキュリティと認証
予約サーバーへのすべての通信は HTTPS で行われるため、DNS 名と一致する有効な TLS 証明書がサーバーに存在することが不可欠です。サーバーを設定する際には、一般公開されている SSL/TLS 検証ツール(Qualys の SSL Server Test など)を使用することをおすすめします。
Google が予約サーバーに対して行うすべてのリクエストは、HTTP 基本認証を使用して認証されます。予約サーバーの基本認証情報(ユーザー名とパスワード)は、パートナー ポータルの [予約サーバーの構成] ページで入力できます。パスワードは 6 か月ごとにローテーションする必要があります。
スケルトン実装のサンプル
まずは、Node.js と Java フレームワーク用に作成された予約サーバーのスケルトンのサンプルをご覧ください。
- Node.js スケルトン js-maps-booking-rest-server-v3-skeleton
- Java スケルトン java-maps-booking-rest-server-v3-skeleton
これらのサーバーでは、REST メソッドがスタブアウトされていますが、
要件
HTTP エラーとビジネス ロジックのエラー
バックエンドが HTTP リクエストを処理する際に、次の 2 種類のエラーが発生することがあります。
- インフラストラクチャまたは不正確なデータに関連するエラー
- これらのエラーは、標準の HTTP エラーコードとともにクライアントに返します。HTTP ステータス コードの一覧をご覧ください。
- ビジネス ロジックに関連するエラー
200
OK に設定された HTTP ステータス コードを返し、レスポンスの本文でビジネス ロジックの失敗を指定します。発生する可能性のあるビジネス ロジックのエラーの種類は、サーバーの実装の種類によって異なります。
標準実装では、可能性のあるビジネス ロジックのエラーが Booking Failure(予約失敗)でキャプチャされ、それらが HTTP レスポンスで返されます。リソースの作成時または更新時にビジネス ロジックのエラーが発生することがあります。たとえば、メソッド CreateBooking
または UpdatingBooking
を処理する場合です。許可されないリスティングには次のものがあります(ただし、これらに限定されません)。
- リクエストされたスロットが利用できなくなった場合は、
SLOT_UNAVAILABLE
が使用されます。 PAYMENT_ERROR_CARD_TYPE_REJECTED
は、指定されたクレジット カードの種類が使用できない場合に使用します。
べき等性
ネットワークを介した通信は必ずしも確実ではなく、レスポンスを受信しなかった場合は HTTP リクエストが再試行されることがあります。このため、状態を変更するメソッドはすべてべき等でなければなりません。
CreateBooking
UpdateBooking
UpdateBooking
を除くすべてのリクエスト メッセージには、リクエストを一意に識別するためにべき等性トークンが含まれています。これにより、単一のリクエストを作成する目的で再試行された REST 呼び出しと、2 つの個別のリクエストを区別できます。UpdateBooking
は、それぞれ予約エントリ ID によって一意に識別されるため、リクエストにべき等性トークンは含まれません。
予約サーバーでのべき等性の処理方法の例は以下のとおりです。
成功した場合、
CreateBooking
HTTP レスポンスには作成された予約が含まれます。支払いは予約フローの一環として処理されることもあります。まったく同じCreateBookingRequest
を 2 回目(同じidempotency_token
で)受け取った場合は、同じCreateBookingResponse
を返す必要があります。2 回目の予約は作成されず、請求が行われるのは 1 回のみです(該当する場合)。CreateBooking
の試行に失敗し、同じリクエストが再送信された場合、バックエンドはリクエストを再試行する必要があります。
べき等性の要件は、状態を変更するすべてのメソッドに適用されます。