Actions Center에서 판매자를 대신하여 콜백을 실행하여 예약을 생성하고 업데이트할 수 있도록 예약 서버를 설정해야 합니다.
- 예약 대기자 명단 구현 예약 대기자 명단 파일럿 프로그램에 참여할 때 사용됩니다. 이를 통해 Actions Center는 사용자를 대신하여 예상 대기자 수를 검색하고 대기자 명단 항목을 만들 수 있습니다.
- 표준 구현 이렇게 하면 Actions Center에서 사용자를 대신하여 약속, 예약을 만들 수 있습니다. 예약 엔드투엔드 통합을 위한 예약 서버를 구현하려면 예약 서버 구현을 참고하세요.
샌드박스 및 프로덕션 예약 서버에 대한 연결을 구성하는 방법을 알아보려면 파트너 포털 문서를 참고하세요.
REST API 인터페이스 구현
REST를 기반으로 API 인터페이스를 구현합니다. 이렇게 하면 Google에서 HTTP를 통해 예약 서버 요청을 보낼 수 있습니다.
시작하려면 Actions Center 샌드박스 환경에 연결할 수 있는 개발 또는 샌드박스 예약 서버를 설정하세요. 샌드박스 서버가 완전히 테스트된 후에만 프로덕션 환경으로 이동합니다.
메서드
예약 서버 유형마다 다른 API 메서드 집합이 필요합니다. 원하는 경우 Proto 형식으로 서비스 정의를 다운로드하여 API 구현을 시작할 수 있습니다. 다음 표에는 각 구현의 메서드가 표시되어 있으며, 서비스 Proto 형식에 대한 링크도 포함되어 있습니다.
| 대기자 명단 구현 |
|---|
| 대기자 명단 서비스 정의 Proto 서비스 정의 파일을 다운로드합니다. |
| 메서드 | HTTP 요청 |
|---|---|
| HealthCheck | GET /v3/HealthCheck/ |
| BatchGetWaitEstimates | POST /v3/BatchGetWaitEstimates/ |
| CreateWaitlistEntry | POST /v3/CreateWaitlistEntry/ |
| GetWaitlistEntry | POST /v3/GetWaitlistEntry/ |
| DeleteWaitlistEntry | POST /v3/DeleteWaitlistEntry/ |
API 리소스
대기자 명단
다음 리소스는 대기자 명단 기반 예약을 구현하는 데 사용됩니다.
- WaitEstimate: 특정 인원수 및 판매자에 대한 예상 대기자 수입니다.
- WaitlistEntry: 대기자 명단에 있는 사용자의 항목입니다.
과정: 대기자 명단 항목 만들기
이 섹션에서는 예약 대기자 명단 통합을 위한 예약을 만드는 방법을 설명합니다.
사용자가 대기자 명단 항목을 만들면 Google에서 사용자의 이름, 성, 전화번호, 이메일을 전송합니다. 이메일은 사용자의 Google 계정과 동일하며 고유 식별자로 처리됩니다. 이 대기자 명단은 Google 예약이 시스템에서 사용자 계정을 조회할 수 없기 때문에 비회원 결제로 처리되어야 합니다. 최종 대기자 명단 항목이 대기자 명단 시스템에서 오는 판매자의 항목과 동일하게 표시되는지 확인합니다.
보안 및 인증
예약 서버와의 모든 통신은 HTTPS를 통해 이루어지므로 서버에 DNS 이름과 일치하는 유효한 TLS 인증서가 있어야 합니다. 서버를 설정하는 데 도움이 되도록 Qualys SSL 서버 테스트와 같이 무료로 제공되는 SSL/TLS 확인 도구를 사용하는 것이 좋습니다.
Google에서 예약 서버에 보내는 모든 요청은 HTTP 기본 인증을 사용하여 인증됩니다. 예약 서버의 기본 사용자 인증 정보(사용자 이름 및 비밀번호)는 파트너 포털의 예약 서버 구성 페이지에 입력할 수 있습니다. 비밀번호는 6개월마다 변경되어야 합니다.
샘플 스켈레톤 구현
시작하려면 Node.js 및 Java 프레임워크용으로 작성된 예약 서버의 다음 샘플 스켈레톤을 확인하세요.
- Node.js 스켈레톤 js-maps-booking-rest-server-v3-skeleton
- Java 스켈레톤 java-maps-booking-rest-server-v3-skeleton
이 서버는 REST 메서드를 스터브 처리했습니다.
요구사항
HTTP 오류 및 비즈니스 로직 오류
백엔드가 HTTP 요청을 처리하면 두 가지 유형의 오류가 발생할 수 있습니다.
- 인프라 또는 잘못된 데이터와 관련된 오류
- 이러한 오류를 표준 HTTP 오류 코드와 함께 클라이언트에 반환합니다. 전체 HTTP 상태 코드 목록을 참고하세요.
- 비즈니스 로직과 관련된 오류
- HTTP 상태 코드를
200OK로 설정하고 응답 본문에 비즈니스 로직 실패를 지정합니다. 발생할 수 있는 비즈니스 로직 오류 유형은 서버 구현 유형에 따라 다릅니다.
- HTTP 상태 코드를
예약 대기자 명단 통합의 경우 비즈니스 로직 오류는 대기자 명단 비즈니스 로직 실패에 캡처되며 HTTP 응답으로 반환됩니다. 리소스를 만들 때(예: CreateWaitlistEntry 메서드 처리 시) 비즈니스 로직 오류가 발생할 수 있습니다. 이러한 예에는 다음 항목이 포함되나 이에 국한되지 않습니다.
ABOVE_MAX_PARTY_SIZE는 요청된 대기자 명단 항목이 판매자의 최대 인원수를 초과할 때 사용됩니다.MERCHANT_CLOSED는 판매자가 이미 폐쇄되어 대기자 명단을 열지 않은 경우에 사용됩니다.
멱등성
네트워크를 통한 통신이 항상 신뢰할 수 있는 것은 아니며 응답을 받지 못하면 Google에서 HTTP 요청을 다시 시도할 수 있습니다. 따라서 상태를 변경하는 모든 메서드는 멱등성을 갖춰야 합니다.
CreateWaitlistEntryDeleteWaitlistEntry
DeleteWaitlistEntry를 제외한 모든 요청 메시지에 멱등성 토큰이 포함되어 요청을 고유하게 식별합니다. 이렇게 하면 단일 요청을 만드는 인텐트와 두 개의 개별 요청을 사용하여 재시도된 REST 호출을 구분할 수 있습니다.
DeleteWaitlistEntry는 각각 대기자 명단 항목 ID로 고유하게 식별되므로 요청에 멱등성 토큰이 포함되지 않습니다.
다음은 예약 서버가 멱등성을 처리하는 방법의 몇 가지 예입니다.
성공적인
CreateWaitlistEntryHTTP 응답에는 생성된 대기자 명단 항목 ID가 포함됩니다. 동일한CreateWaitlistEntryRequest가 두 번째로 수신되면 (동일한idempotency_token포함) 동일한CreateWaitlistEntryResponse가 반환되어야 합니다. 두 번째 대기자 명단 항목이 생성되지 않으며 오류가 반환되지 않습니다.CreateWaitlistEntry시도가 실패하고 동일한 요청이 다시 전송되면 백엔드에서 이를 다시 시도해야 합니다.
멱등성 요구사항은 상태를 변경하는 모든 메서드에 적용됩니다.