시스템의 인벤토리는 판매자의 새로운 예약, 취소, 일정 변경으로 인해 하루 종일 변동됩니다. 실시간 업데이트 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호출은 실제 인벤토리와 일치하지 않는 인벤토리를 반환합니다.
자세한 내용은 다음 리소스를 참고하세요.
예약 알림 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에 연결할 수도 있습니다.
| 언어 | 다운로드 링크 |
|---|---|
| Java | 자바 클라이언트 라이브러리 자세한 내용은 자바 클라이언트 안내를 참고하세요. |
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()