予約サーバーを立ち上げて、アクション センターがユーザーに代わって予約を作成および更新するためのコールバックを実行できるようにする必要があります。
- 予約の順番待ちリストの実装。予約の順番待ちリストのパイロット プログラムに参加する場合に使用されます。これにより、アクション センターがユーザーに代わって待ち時間を予測し、順番待ちリストのエントリを作成できるようになります。
- 標準実装。これにより、アクション センターがユーザーに代わって予約を作成できるようになります。予約サーバーをエンドツーエンド統合用に実装するには、予約サーバーを実装するをご覧ください。
サンドボックスや本番環境の予約サーバーへの接続を設定する方法については、パートナー ポータルのドキュメントをご覧ください。
REST API インターフェースを実装する
REST ベースの API インターフェースを実装すると、Google が HTTP 経由で予約サーバー リクエストを送信できるようになります。
まず、Actions Center のサンドボックス環境に接続できる開発用またはサンドボックスの予約サーバーをセットアップします。本番環境に移行できるのは、サンドボックス サーバーのテストがすべて完了してからです。
Methods
予約サーバーの種類ごとに、お客様側で必要な API メソッドのセットが異なります。必要に応じて、サービス定義を proto 形式でダウンロードして、API の実装を開始できます。次の表に、各実装のメソッドと、サービス proto 形式へのリンクを示します。
順番待ちリストの実装 |
---|
順番待ちリストのサービス定義 proto サービス定義ファイルをダウンロードします。 |
メソッド | HTTP リクエスト |
---|---|
HealthCheck | GET /v3/HealthCheck/ |
BatchGetWaitEstimates | POST /v3/BatchGetWaitEstimates/ |
CreateWaitlistEntry | POST /v3/CreateWaitlistEntry/ |
GetWaitlistEntry | POST /v3/GetWaitlistEntry/ |
DeleteWaitlistEntry | POST /v3/DeleteWaitlistEntry/ |
API リソース
ウェイティング リスト
順番待ちリスト ベースの予約の実装では、以下のリソースを使用します。
- WaitEstimate: 特定の人数と販売者の予想待ち時間。
- WaitlistEntry: 順番待ちリストへのユーザーのエントリ。
フロー: 順番待ちリストのエントリを作成
このセクションでは、予約の順番待ちリストを統合するために予約を作成する方法について説明します。
![図 2: 順番待ちリストのエントリを作成するワークフロー](https://developers-dot-devsite-v2-prod.appspot.com/static/actions-center/images/waitlists/rest_api_v3_waitlist_flow.png?authuser=7&hl=ja)
ユーザーが順番待ちリストに登録すると、Google からユーザーの氏名、電話番号、メールアドレスが送信されます。このメールアドレスはユーザーの Google アカウントと同じであり、一意の識別子として扱われます。「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 ステータス コードを返し、レスポンスの本文でビジネス ロジックの失敗を指定します。発生する可能性のあるビジネス ロジックのエラーの種類は、サーバーの実装の種類によって異なります。
予約の順番待ちリスト統合の場合、ビジネス ロジックのエラーが順番待ちリストのビジネス ロジックの失敗にキャプチャされ、HTTP レスポンスで返されます。CreateWaitlistEntry
メソッドの処理など、リソースの作成時にビジネス ロジック エラーが発生することがあります。再利用されたコンテンツの例には以下のものが含まれますが、これらに限定されません。
ABOVE_MAX_PARTY_SIZE
は、リクエストされた順番待ちリストのエントリが販売者の最大人数を超えた場合に使用されます。MERCHANT_CLOSED
は、販売者がすでに閉鎖されているため順番待ちリストが開いていない場合に使用されます。
べき等性
ネットワークを介した通信は必ずしも確実ではなく、レスポンスを受信しなかった場合は HTTP リクエストが再試行されることがあります。このため、状態を変更するメソッドはすべてべき等でなければなりません。
CreateWaitlistEntry
DeleteWaitlistEntry
DeleteWaitlistEntry
を除くすべてのリクエスト メッセージには、リクエストを一意に識別するためにべき等性トークンが含まれています。これにより、単一のリクエストを作成する目的で再試行された REST 呼び出しと、2 つの個別のリクエストを区別できます。DeleteWaitlistEntry
は順番待ちリストのエントリ ID でそれぞれ一意に識別されるため、リクエストにべき等性トークンは含まれません。
予約サーバーでのべき等性の処理方法の例は以下のとおりです。
成功した
CreateWaitlistEntry
HTTP レスポンスには、作成された順番待ちリストのエントリ ID が含まれます。同じCreateWaitlistEntryRequest
を 2 回目(同じidempotency_token
で)受け取った場合は、同じCreateWaitlistEntryResponse
を返す必要があります。順番待ちリストへの 2 番目のエントリは作成されず、エラーは返されません。CreateWaitlistEntry
の試行が失敗し、同じリクエストが再送信された場合、この場合はバックエンドが再試行する必要があります。
べき等性の要件は、状態を変更するすべてのメソッドに適用されます。