システム内の在庫は、新規予約、キャンセル、販売者からのスケジュール変更により、1 日を通して変動します。リアルタイム更新 API は、在庫状況の変化を Google に通知するメカニズムです。リアルタイムの API 更新を使用して、既存の予約に加えられた変更を Google に通知することもできます。
API リアルタイム更新とフィード
API のリアルタイム更新は、在庫状況と予約にリアルタイムの変更が発生した場合に、Google に通知するために使用されます。リアルタイムの API 更新に加えて、完全な可用性フィードを毎日送信して、システムに存在する最新の可用性に関する情報を Google が取得できるようにします。完全なフィードは、システム内の在庫状況に関する現在のスナップショットとして機能します。
API の更新は、フィードで提供される情報(販売者やサービスに関する情報など)の更新に使用できますが、通常は空室情報の更新にのみ使用されます。
必須のリアルタイム更新 API
リアルタイム更新(RTU)API | ||
---|---|---|
BookingNotification | 必須 | 予約に変更(変更、キャンセルなど)があれば、BookingNotification RTU を送信します。 |
空き情報置換 RTU | 条件付き必須[1] | バッチ置換または単一置換の RTU を送信して、在庫状況の更新を送信します。変更が反映されるまでに、数分かかることがあります。 |
販売者 RTU | 任意 | 販売者の情報をリアルタイムで変更する場合は、販売者の RTU を送信します。変更が反映されるまでに数時間かかることがあります。 |
サービス RTU | 任意 | サービス情報をリアルタイムで変更する場合は、サービス RTU を送信します。一般的なユースケースでは、日中にサービス料金が著しく変動する場合は、価格の不一致による注文の失敗を避けるためにサービス RTU を実装することをおすすめします。変更が反映されるまでに数時間かかることがあります。 |
Availability Replace API RTU
AvailabilityReplace API を使用して、次のユースケースで在庫状況の更新を提供します。
- ユーザーがシステムで予約すると、予約枠は利用できなくなります。
- 販売者がシステムで空き情報を変更した。
- ユーザーが Google 経由で予約すると、予約枠は利用できなくなります。
- Google を通じて行われた予約は、販売者が直接キャンセルするなどしてお客様側でキャンセルされます。元のスロットが再度利用可能になったため、予約と空室状況を更新する必要があります。
- 予約サーバーの
BatchAvailabilityLookup
呼び出しが、実際の在庫と一致しない在庫を返す。
詳細については、次のリソースをご覧ください。
- チュートリアル: リアルタイム アップデートの構成方法
- RESTful 呼び出しを使用したリアルタイム更新の Java クライアントの例
- Inventory update API リファレンス ページ
予約通知 API RTU
Booking Notification API は、既存の予約の更新を Google に通知します。キャンセルに関する更新を送信する場合は、updateMask
クエリ パラメータを使用して、リクエストに必要な情報のみを送信します。次に例を示します。
Request: PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status Body: {"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"CANCELED"}
API へのアクセス
サービス アカウントを作成する
Google API Console の [認証情報] タブを使用して、サービス アカウントを作成します。秘密鍵は JSON 形式で安全な場所に保管してください。アカウントを作成するときに、ロールを「オーナー」に設定できます。
Maps Booking API を認証する
サービス アカウントを作成したら、次の API を認証します。
- Google Maps Booking API
- Google Maps Booking API(Dev)
詳しい手順については、Maps Booking API による認証のチュートリアルをご覧ください。
RESTful 呼び出しを使用するかクライアント ライブラリをダウンロードする
JSON ペイロードを使用して、Maps Booking API に対して RESTful 呼び出しを直接行うことをおすすめします。詳細については、REST API ドキュメントをご覧ください。
クライアント ライブラリを使用して API に接続することもできます。
母国語 | ダウンロード リンク |
---|---|
Java | Java Client ライブラリ。詳しくは、Java クライアントの手順をご覧ください。 |
追加の サポート ライブラリをダウンロードして、認証やその他の Google API の呼び出しを処理できます。必要に応じて、サンプルをご覧ください。
Discovery ドキュメントを取得する
Ruby などの一部のクライアント ライブラリでは、API の Discovery ドキュメントを取得して、そのメソッドとパラメータを記述する必要があります。
ディスカバリ ドキュメントを取得するには、次のコマンドを使用します。
curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'
Ruby から API にアクセスする方法について詳しくは、Ruby API クライアントと Ruby Auth ライブラリをご覧ください。
API に対して承認された呼び出しを行う
API を呼び出すときは、承認済み API 呼び出しの準備を行うを参照し、秘密鍵と次の OAuth スコープを使用してサービス アカウントを承認してください。
https://www.googleapis.com/auth/mapsbooking
API 割り当て
API 更新には、60 秒ごとに 1,500 リクエスト、または平均で 1 秒あたり 25 リクエストの割り当てがあります。割り当てを超過すると(パートナー ポータルに正しい Google Cloud プロジェクト番号を追加していない場合に発生することがあります)、Google から次のエラー メッセージが返されます。
{ "error": { "code": 429, "message": "Insufficient tokens for quota ...", "status": "RESOURCE_EXHAUSTED", "details": [...] } }
これに対処するには、成功するまで指数間隔を高くして呼び出しを再試行します。ReplaceServiceAvailability
で割り当てを使い切った場合は、BatchReplaceServiceAvailabily
に切り替えて API 呼び出しの回数を減らしてください。このメソッドを使用すると、1 回の API 呼び出しで複数のサービスを更新できます。
サンドボックス エンドポイントと本稼働エンドポイント
API を使用して、サンドボックス環境と本番環境の両方を呼び出すことができます。Google Cloud プロジェクトで両方の API が有効になっていることを確認します。どちらの API も同じスコープを使用しますが、エンドポイントは異なります。
本番環境エンドポイント: https://mapsbooking.googleapis.com/
サンドボックス エンドポイント: https://partnerdev-mapsbooking.googleapis.com/
Java でのエンドポイントの切り替え方法の例を次に示します。
// This block of code is for OAuth and is the same for prod and sandbox. GoogleCredential .fromStream(new FileInputStream(...)) .createScoped(Collections.singleton("https://www.googleapis.com/auth/mapsbooking")) // This block of code sets the endpoint. This is what you'd change to connect to the sandbox. new GoogleMapsBookingAPI.Builder(...) .setApplicationName(...) .setRootUrl("https://partnerdev-mapsbooking.googleapis.com/") // you add this to change the endpoint to use partnerdev. .build()