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

ステップ 5: リアルタイム API 更新を実装する

システムの在庫は、販売者による新規予約、キャンセル、スケジュールの変更により、1 日を通じて変動します。リアルタイム更新 API は、こうした在庫状況の変化を Google に通知するメカニズムです。また、リアルタイムの API 更新を使用して、既存の予約に加えた変更を Google に通知することもできます。

API リアルタイム更新とフィード

API のリアルタイム更新により、空室状況や予約の増分変更をリアルタイムで Google に通知できます。API のリアルタイム更新に加えて、完全な在庫状況フィードを毎日送信して、システムに存在する最新の在庫状況を Google に正確かつ最新の状態に保ってください。完全フィードは、システムの在庫状況の現在の状態を示すスナップショットとして機能します。

API による更新は、フィードで提供される情報（販売者やサービスに関する情報など）の更新に使用できますが、通常は在庫状況の情報を更新する目的でのみ使用します。

必須のリアルタイム更新 API

リアルタイム更新（RTU）API
BookingNotification	必須	予約に変更（変更やキャンセルなど）が行われるたびに BookingNotification RTU を送信します。
空き情報置換 RTU	条件付き必須[1]	一括置換または単一の置換 RTU のいずれかを送信して、在庫状況の更新を送信します。変更が反映されて反映されるまでに数分かかることがあります。
販売者 RTU	任意	販売者情報をリアルタイムで変更する場合は、販売者 RTU を送信してください。変更が反映されるまでに数時間かかることがあります。
サービス RTU	任意	サービス情報をリアルタイムで変更する場合は、サービス RTU を送信してください。一般的なユースケースとして、1 日のなかでサービス料金が大幅に変動する場合、料金の不一致による注文エラーを回避するために、サービス RTU の実装が推奨されます。変更が反映されるまでに数時間かかることがあります。

Availability Replace API RTU

在庫状況の更新 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 形式で安全な場所に保管してください。アカウントを作成するときに、ロールを「オーナー」に設定できます。

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 のディスカバリドキュメントを取得する必要があります。

ディスカバリドキュメントを取得するには、次のコマンドを使用します。

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 プロジェクト番号を追加していない場合に発生することがあります）、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()

ステップ 4: 予約サーバーを実装する

ステップ 6: エンドツーエンドテスト