시스템의 인벤토리는 새로운 예약, 취소, 판매자의 일정 변경으로 인해 하루 종일 변동합니다. 실시간 업데이트 API는 인벤토리 가용성의 이러한 변경사항을 Google에 알리는 메커니즘입니다. 또한 실시간 API 업데이트를 사용하여 기존 예약의 변경사항을 Google에 알릴 수 있습니다.
API 실시간 업데이트 및 피드
API 실시간 업데이트는 인벤토리 가용성 및 예약이 실시간으로 변경될 때 이를 Google에 알리는 데 사용됩니다. 실시간 API 업데이트 외에도 Google은 시스템에 존재하는 가장 정확한 최신 상태 정보를 제공하기 위해 전체 가용성 피드를 매일 전송합니다. 전체 피드는 시스템 인벤토리 가용성의 현재 상태에 대한 스냅샷 역할을 합니다.
API 업데이트는 판매자 및 서비스에 대한 정보와 같이 피드에서 제공하는 모든 정보를 업데이트하는 데 사용할 수 있지만 일반적으로 가용성 정보를 업데이트하는 데만 사용됩니다.
필수 실시간 업데이트 API
| 실시간 업데이트(RTU) API | ||
|---|---|---|
| BookingNotification | 필수 | 예약이 변경 (예: 수정 또는 취소)될 때마다 BookingNotification RTU를 전송합니다. |
| 이용 가능 여부 교체 RTU | 조건부 필수[1] | 일괄 교체 또는 단일 교체 RTU를 전송하여 인벤토리 가용성에 대한 업데이트를 전송합니다. 변경사항이 반영되고 반영되기까지 몇 분 정도 걸릴 수 있습니다. |
| 판매자 RTU | 선택사항 | 판매자 정보를 실시간으로 변경하려면 판매자 RTU를 전송하세요. 변경사항이 전파되고 반영되는 데 몇 시간이 걸릴 수 있습니다. |
| 서비스 RTU | 선택사항 | 서비스 정보를 실시간으로 변경하려면 서비스 RTU를 전송하세요. 일반적인 사용 사례는 하루 동안 서비스 가격이 급격히 변동하는 경우 가격 불일치로 인한 주문 실패를 방지하기 위해 서비스 RTU를 구현하는 것입니다. 변경사항이 전파되고 반영되는 데 몇 시간이 걸릴 수 있습니다. |
Availability Replace API RTU
Availability Replace 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 콘솔의 사용자 인증 정보 탭을 사용하여 서비스 계정을 만듭니다. 비공개 키를 안전한 위치에 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에 연결할 수도 있습니다.
| 언어 | 다운로드 링크 |
|---|---|
| 자바 | 자바 클라이언트 라이브러리 자세한 내용은 자바 클라이언트 안내를 참조하세요. |
Google API 호출에 대한 승인 및 기타 측면을 처리하는 추가 지원 라이브러리를 다운로드할 수 있습니다. 필요한 경우 이 샘플을 참고하세요.
Discovery Document 가져오기
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개 또는 초당 평균 요청 25개입니다. 파트너 포털에 올바른 Google Cloud 프로젝트 번호를 추가하지 않은 경우 할당량을 초과할 수 있으며 이 경우 Google은 다음과 같은 오류 메시지를 표시합니다.
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}
이 문제를 해결하려면 호출이 성공할 때까지 기하급수적으로 큰 간격으로 다시
재시도하세요. ReplaceServiceAvailability를 사용하여 할당량을 정기적으로 소진하는 경우 BatchReplaceServiceAvailabily로 전환하여 API 호출 수를 줄이세요. 이 메서드를 사용하면 API 호출 한 번으로 여러 서비스를 업데이트할 수 있습니다.
샌드박스 및 프로덕션 엔드포인트
API를 통해 샌드박스와 프로덕션 환경을 모두 호출할 수 있습니다. Google Cloud 프로젝트에서 두 API를 모두 사용 설정했는지 확인합니다. 두 API 모두 동일한 범위를 사용하지만 엔드포인트가 다릅니다.
프로덕션 엔드포인트: https://mapsbooking.googleapis.com/
샌드박스 엔드포인트: https://partnerdev-mapsbooking.googleapis.com/
다음은 엔드포인트를 전환하는 방법의 자바로 작성된 예입니다.
// 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()