リアルタイム更新の構造化

リアルタイムの更新のユースケース

リアルタイムの更新は、常に次の場合に発行する必要があります。

  • ユーザーがシステムで予約をキャンセルし、スロットが使用可能になった場合。
  • ユーザーが「Google で予約」を使用して予約すると、予約枠は利用できなくなります。
  • 「Google で予約」を通した予約が、お客様側で自動的にキャンセルされた場合など。元のスロットが再度利用可能になったため、予約と空室状況を更新する必要があります。

また、Availability の代替 RTU を実装する場合は、以下のシナリオでリアルタイム更新を行う必要があります。

  • システムでスケジュール（空室状況）が変更された場合。
  • ユーザーがシステムで予約を行い、予約枠が利用できなくなった場合。
  • 従来の CheckAvailability との統合を使用している場合、予約サーバーの CheckAvailability 呼び出しで、実際の在庫と一致しない在庫が返されることがあります。

すべての Maps Booking API の呼び出しは必須ではありません。次の入力は必須です。

統合のタイプによっては、以下が利用可能になる場合があります。

予約の RTU を更新

システムで「Google で予約」の予約を更新（キャンセル、変更など）した場合は、notification.partners.bookings.patch（BookingNotification.UpdateBooking）を送信する必要があります。

変更可能なフィールド

  • status
  • startTime
  • duration
  • partySize
  • paymentInformation.prepaymentStatus

解約の例

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{
  "name": "partners/<PARTNER_ID>/bookings/<BOOKING_ID>",
  "merchantId": "10001",
  "serviceId": "1001",
  "startTime": "2014-10-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

空き情報置換 RTU

可用性を更新するには、次の 2 種類の置換方法があります。

  • バッチ置換（InventoryUpdate.BatchServiceAvailability）: 販売者と複数のサービスの可用性データを完全に置き換えます。
    • 注: このバッチ呼び出しはアトミック性を保証しません。正常に更新された予約枠のみが返されます。
  • 単一置換（InventoryUpdate.ReplaceServiceAvailability）: 1 つの販売者とサービスの在庫状況を完全に置き換えます。

詳しくは、こちらのリファレンスをご覧ください。

リアルタイム更新では、フィードで送信されるデータと同じ可用性構造を使用する必要があります。次のいずれかを使用する必要があります。

  • spotsOpen
  • recurrence

最適な形式については、可用性構造ガイドをご覧ください。

呼び出す置換メソッドを選択する

次のガイドを使用して、どちらの置換メソッドが適切かを判断してください。

  • 1 回の予約で複数のサービスが影響を受けることはありますか？たとえば、ヘアカットとカラーリング（それぞれ別の Service）はスタイリストで予約されるため、その時間帯のスタイリストに関連付けられているすべてのサービスを削除する必要があります。
  • システムは、前回の更新以降に可用性に関するすべての変更を送信することにより、Google と随時同期されます（非推奨）。
    • バッチ置換
    • 注: 広告枠 RTU は、お客様側で更新が行われてから 5 分以内に送信される予定です。そのため、少なくとも 5 分ごとにアップデートを確認して送信する必要があります。
  • 上記のいずれにも該当しない
    • 単一の置換
    • 注: 複数の置換呼び出しを使用してバッチ置換の呼び出しをエミュレートすることもできますが、1 つの一括置換呼び出しを使用する方が効率的です

リアルタイム更新: Spot のオープン フォーマット

フィード、予約サーバー、リアルタイム アップデートで同じフォーマットを使用することが重要です。

spots_open フィード スニペットは次のようになります。

フィード スニペット

   "availability": [
          {
            "merchant_id": "1001",
            "service_id": "12310",
            "spots_open": 2,
            "spots_total": 2,
            "start_sec": 1412263800, # October 02, 2014 15:30:00
            "duration_sec": 1800,
            "availabilityTag": "1000001"
          }
    ]

Inventory Update API では、午後 3:30 のスロットが予約されたときの置換リクエスト本文の形式は次のとおりです。

リアルタイム更新スニペットを置き換える

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
        "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2014-10-02T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "spotsTotal": "2",
            "availabilityTag": "1000001"
          }
        ]
      }
    ]
  }

次の例は、午後 3 時 30 分に新しいスロットが予約された場合に、翌日のフィードで想定される内容の例です。

フィード スニペット

"availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 2,
          "start_sec": 1412263800, # October 02, 2014 15:30:00
          "duration_sec": 1800,
          "availabilityTag": "1000001"
        }
      ]

リアルタイム更新: 繰り返し形式

フィード、予約サーバー、リアルタイム アップデートで同じフォーマットを使用することが重要です。

繰り返しを使用するフィードは次のようになります。

フィード スニペット

  "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            }
          ],
        }
      ]

Inventory Update API では、午後 3:30 のスロットが予約されたときの置換リクエスト本文の形式は次のようになります。

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2018-10-30T15:01:23.045123456Z",
        "endTimeRestrict": "2018-10-30T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2018-10-30T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "scheduleException": [
             {
                "timeRange": {
                  "startTime": "2018-10-30T12:30:00.00Z",
                  "endTime": "2018-10-30T13:00:00.00Z"
                }
              },
              {
                "timeRange": {
                  "startTime": "2018-10-30T15:30:00.00Z",
                  "endTime": "2018-10-30T16:00:00.00Z"
                }
              }
            ]
          }
        ]
      }
    ]
  }

次の 1 日のフィードの例を以下に示します。なお、この販売者はサービス全体が利用可能であり、以前のものと新しい店舗すべてが利用できる状態になっています。schedule_exceptions

フィード スニペット

   "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            },
            {
              "time_range": {
                "begin_sec": 1540913400, # October 30, 2018 3:30:00 PM
                "end_sec": 1540915200 # October 30, 2018 4:00:00 PM
              }
            }
          ],
        }
      ]

リアルタイム アップデートを送信するタイミング

在庫状況が変更される場合は、リアルタイム更新を継続的に送信する必要があります。これは、お客様と Google のシステムの間で在庫状況を同期させるために、1 日 1 回送信する包括的な在庫状況フィードに加えて使用します。