실시간 업데이트 구조화

실시간 업데이트의 사용 사례

다음과 같은 경우에는 항상 실시간 업데이트를 실행해야 합니다.

  • 사용자가 시스템에서 예약을 취소하여 이용 가능 시간대가 사용 가능해지는 경우
  • 사용자가 작업 센터를 통해 예약을 하고 이용 가능 시간대를 더 이상 사용할 수 없는 경우
  • 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

재고를 업데이트하는 데 사용할 수 있는 replace 메서드에는 두 가지 유형이 있습니다.

  • 일괄 대체 (InventoryUpdate.BatchServiceAvailability): 여러 판매자 및 서비스의 재고 데이터를 완전히 대체합니다.
    • 참고: 이 일괄 호출은 원자성을 보장하지 않습니다. 성공적으로 업데이트된 이용 가능 시간대만 반환됩니다.
  • 단일 대체 (InventoryUpdate.ReplaceServiceAvailability): 단일 판매자 및 서비스의 이용 가능 여부를 완전히 대체합니다.

자세한 내용은 다음 참조를 참고하세요.

실시간 업데이트는 피드를 통해 전송되는 데이터와 동일한 사용 가능 여부 구조를 사용해야 합니다. 다음 중 하나를 사용해야 합니다.

  • spotsOpen
  • recurrence

호출할 대체 메서드 선택

다음 가이드를 사용하여 더 적합한 대체 방법을 결정하세요.

  • 여러 판매자가 영향을 받나요? 예를 들어 한 번의 요청으로 여러 판매자의 이용 가능 여부를 대체합니다.
  • 시스템은 가끔 Google 시스템과 동기화하여 지난 업데이트 이후의 모든 사용 가능 여부 변경사항을 전송합니다 (권장하지 않음).
    • 일괄 대체
    • 참고: 인벤토리 RTU는 판매자 측에서 업데이트가 발생한 후 5분 이내에 전송될 것으로 예상됩니다. 따라서 최소 5분마다 업데이트를 확인하고 전송해야 합니다.
  • 위의 내용이 모두 해당되지 않거나 단일 판매자 및 서비스를 업데이트하기만 하면 되나요?
    • 단일 대체
    • 참고: 여러 개의 단일 replace 호출을 사용하여 일괄 replace 호출을 에뮬레이션할 수 있지만 단일 일괄 replace 호출을 사용하는 것이 더 효율적입니다.

실시간 업데이트: 스팟 오픈 형식

피드, 예약 서버, 실시간 업데이트에서 동일한 형식을 사용하는 것이 중요합니다.

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분 슬롯이 예약될 때의 replace 요청 본문 형식은 다음과 같습니다.

  {
    "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 시스템 간에 이용 가능 여부가 동기화되도록 매일 한 번 제출해야 하는 포괄적인 이용 가능 여부 피드 외에도 적용됩니다.