システム内の空き情報は、新しい予約、キャンセル、販売者からのスケジュール変更により、1 日をとおして変動します。リアルタイム更新 API は、空き情報の変化を Google に通知するメカニズムです。リアルタイム API 更新を使用すると、既存の予約に加えられた変更を Google に通知することも可能です。
API リアルタイム更新とフィード
API リアルタイム更新は、空き情報と予約への増分変更がリアルタイムで行われる際に Google に通知するために使用されます。リアルタイム API 更新に加えて、完成した Availability フィードを毎日送信することで、自社のシステムにある最新で正確な空き情報を Google が常に把握できるようにします。完成したフィードは、システム内の空き情報のスナップショットとして機能します。
API 更新は、フィードで提供される情報（販売者やサービスに関する情報など）の更新に使用できますが、通常は空き情報の更新にのみ使用されます。
必須のリアルタイム更新 API
| リアルタイム更新（RTU）API | ||
|---|---|---|
| BookingNotification | 必須 | 予約に変更（変更やキャンセルなど）があった場合は、BookingNotification RTU を送信します。 |
| 空き情報置換 RTU | 条件付き必須[1] | 一括置換または単一置換の RTU を送信して、空き情報を更新します。変更が反映されるまでに数分かかることがあります。 |
| 販売者 RTU | 省略可 | 販売者の情報をリアルタイムで変更する場合は、販売者 RTU を送信します。変更が反映されるまでに数時間かかることがあります。 |
| サービス RTU | 省略可 | サービス情報をリアルタイムで変更する場合は、サービス RTU を送信します。サービスの価格が日中に大幅に変動することが頻繁に発生する場合は、価格の不一致による注文の失敗を避けるためサービス RTU の実装をおすすめします。変更が反映されるまでに数時間かかることがあります。 |
Availability Replace API RTU
Availability Replace API を使用して、次のユースケースで空き情報更新を提供します。
- ユーザーがシステムで予約を行ったため、予約枠が利用できなくなった。
- 販売者がシステムで空き情報を変更した。
- ユーザーが Google 経由で予約したため、予約枠が利用できなくなった。
- Google 経由で行った予約が、販売者によって直接キャンセルされた。元の予約枠が再び利用可能になったため、予約と空き情報を更新する必要があります。
- 予約サーバーの
BatchAvailabilityLookup呼び出しが、実際の空き情報と一致しない空き情報を返した。
詳細については、次のリソースをご覧ください。
Booking Notification 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 形式で安全な場所に保存します。アカウントを作成するときに、役割を [Owner] に設定することもできます。
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 の呼び出しを処理する追加のサポート ライブラリをダウンロードできます。必要に応じて、こちらのサンプルをご覧ください。
ディスカバリ ドキュメントを取得する
Ruby などの一部のクライアント ライブラリでは、API のメソッドとパラメータを記述した Discovery ドキュメントを取得する必要があります。
次のコマンドを使用して、検出ドキュメントを取得します。
curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'
Ruby からの API へのアクセスについて詳しくは、Ruby API クライアントと Ruby 認証ライブラリをご覧ください。
API に対して承認された呼び出しを行う
API を呼び出す場合は、承認済み API 呼び出しの準備についての記事を参照して、秘密鍵と OAuth スコープ（https://www.googleapis.com/auth/mapsbooking）でサービス アカウントを承認します。
API 割り当て
API の更新では、60 秒ごとに 1,500 リクエスト、つまり 1 秒あたり平均 25 リクエストが割り当てられます。割り当てを超過すると（パートナー ポータルに正しい Google Cloud プロジェクト番号を追加していない場合に発生することがあります）、次のエラー メッセージが返されます。
{
"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()