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

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

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

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

ユーザーがシステムで予約をキャンセルし、そのスロットが使用可能になったとき。
ユーザーがアクションセンターから予約を行ったときに、予約枠が利用できなくなった場合。
アクションセンターを通じて行われた予約が、パブリッシャー側によって（販売者が直接キャンセルした場合など）キャンセルされた場合。元の予約枠が再び利用可能になったため、予約と空き情報を更新する必要があります。

さらに、可用性の置換 RTU を実装すると、次のシナリオでリアルタイムアップデートが発行されます。

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

必ずしも Maps Booking API の呼び出しを行う必要はありません。次の項目は必須です。

notification.partners.bookings.patch（BookingNotification.UpdateBooking）

統合のタイプによっては、以下も利用できる場合と、必要となる場合があります。

inventory.partners.availability.replace（InventoryUpdate.BatchServiceAvailability）または inventory.partners.merchants.services.availability.replace（InventoryUpdate.ReplaceServiceAvailability）

予約 RTU の更新

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

変更可能なフィールド

status
startTime
duration
partySize
paymentInformation.prepaymentStatus

注: name、merchant_id、service_id、および変更する特定のフィールドを指定する必要があります。その他のフィールドはすべて省略可能です。状況によっては、複数のフィールドが同時に変更されることがあります。その場合は、updateMask 内のフィールドをカンマで区切ります（例: updateMask=partySize,startTime）。

解約の例

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）: 単一の販売者とサービスの在庫状況を完全に置き換えます。

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

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

spotsOpen
recurrence

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

次のガイドを参考に、適切な置換方法を判断してください。

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

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

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

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"
        }
      ]

注: 在庫が残っていない場合（spots_open が 0）、Inventory API の置換リクエストを送信する方法は 2 つあります。

明示的な指定: spots_total > 1 がある場合は、この方法をおすすめします。

  {
    "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": "0",
            "spotsTotal": "2",
            "availabilityTag": "1000001"
          }
        ]
      }
    ]
  }

空の指定: この方法は、ほとんどの販売者とサービスで spots_total = 1 の場合にのみ使用することをおすすめします。

  {
  "extendedServiceAvailability": [
    {
      "merchantId": "1001",
      "serviceId": "12310",
      "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
      "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
      "availability": [
        {}
      ]
    }
  ]
}

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

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

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

フィードスニペット

  "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 がすべて含まれている必要があります。これは、API メソッドがその特定のサービスと販売者の在庫状況を置き換えるためです。別のものに置き換える場合は、そのサービスの可用性に関する完全な情報であり、予約されたすべてのスロットが含まれている必要があります。

以下は、次回の日次フィードで想定される内容の例です。その販売者のサービス全体の可用性と、以前および新しい 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 回送信する必要があります。

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

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

予約 RTU の更新

空き情報置換 RTU

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

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

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

リアルタイムの更新を送信するタイミング

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