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

リアルタイム アップデートのユースケース

次のシナリオでは、常にリアルタイム更新を発行する必要があります。

  • ユーザーがシステムで予約をキャンセルし、そのスロットが空いた場合。
  • ユーザーが Actions Center で予約を行ったため、予約枠が利用できなくなった。
  • Actions Center 経由で行った予約が、販売者によって直接キャンセルされた。元の予約枠が再び利用可能になったため、予約と空き情報を更新する必要があります。

また、空き情報置換 RTU を実装する場合は、次のシナリオでリアルタイム更新を発行する必要があります。

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

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

統合の種類によっては、以下も使用可能または必須になる場合があります。

予約の更新 RTU

システムで Actions Center の予約が更新された場合（キャンセルや変更など）、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": "2025-01-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

空き情報置換 RTU

在庫状況を更新する方法には、次の 2 種類があります。

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

詳細については、次のリファレンスをご覧ください。

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

  • spotsOpen
  • recurrence

呼び出す置換方法を選択する

どの交換方法が適しているかを判断するには、次のガイドを参照してください。

  • 複数の販売者に影響していますか？たとえば、1 つのリクエストで複数の販売者の在庫を置き換えます。
  • システムは、前回の更新以降の在庫状況の変更をすべて送信することで、Google と随時同期します（推奨されません）。
    • 一括置換
    • 注: 広告枠の RTU は、お客様側で更新が行われてから 5 分以内に送信されます。そのため、少なくとも 5 分ごとに最新情報を確認して送信する必要があります。
  • 上記のいずれも該当しない場合、または単一の販売者とサービスを更新する必要がある場合。
    • 単一置換
    • 注: 複数の単一置換呼び出しを使用してバッチ置換呼び出しをエミュレートできますが、単一のバッチ置換呼び出しを使用する方が効率的です。

リアルタイム更新: スポットのオープン形式

フィード、予約サーバー、リアルタイム更新で同じ形式を使用することが重要です。

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

フィード スニペット

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

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

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

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2025-01-02T15:01:23.045123456Z",
        "endTimeRestrict": "2025-01-02T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2025-01-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": 1735831800, # January 02, 2025 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"
                }
              }
            ]
          }
        ]
      }
    ]
  }

次の日次フィードに含まれるデータの例を次に示します。これは、その販売者のサービスの空き状況全体と、以前と新しいすべての 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 回送信する必要がある包括的な空き状況フィードとは別に行う必要があります。