이 페이지는 Cloud Translation API를 통해 번역되었습니다.

예약 서버 구현: API v2

자체적으로 예약 서버를 설정하면 Actions Center에서 사용자를 대신하여 약속 / 예약 / 예약을 생성할 수 있습니다.

gRPC를 기반으로 API 인터페이스 구현

참고: 모든 신규 파트너는 gRPC API가 아닌 REST API 인터페이스를 사용해야 합니다.

gRPC 기반의 API 인터페이스를 구현합니다. 이렇게 하면 Google에서 예약 요청을 보낼 수 있습니다. API 노출 영역은 gRPC의 protobuf 기반 IDL을 사용하여 정의됩니다.

신규 파트너에게 권장되는 API v2 세트를 구현해 주시기 바랍니다. 파트너는 인프라에 가장 적합한 URL과 포트를 선택할 수 있습니다.

이 섹션에서는 권장되는 API v2 세트를 소개합니다. 이는 API v0를 구현하지 않은 파트너에게 적용됩니다. API v0를 구현한 현재 파트너의 경우 작업 센터에 문의하여 자세히 알아보세요.

API 구현을 시작하려면 아래 proto 형식으로 서비스 정의를 다운로드하세요.

서비스 정의 다운로드

API 리소스

이 구현에 활용되는 다음 리소스 유형을 숙지하세요.

슬롯: 인벤토리 슬롯
예약: 인벤토리 시간대 예약

방법

다음 API 메서드는 사용자 측에서 gRPC 서버에 구현되어야 합니다.

다음 5가지 메서드는 필수 BookingService RPC 집합을 정의합니다.

// Manages slot availability, leases and bookings for an inventory of
// appointments
service BookingService {
  // Gets availability information for an appointment slot
  rpc CheckAvailability(CheckAvailabilityRequest)
      returns (CheckAvailabilityResponse) {}

  // Creates a booking
  rpc CreateBooking(CreateBookingRequest) returns (CreateBookingResponse) {}

  // Updates an existing booking
  rpc UpdateBooking(UpdateBookingRequest) returns (UpdateBookingResponse) {}

  // Gets status for an existing booking
  rpc GetBookingStatus(GetBookingStatusRequest)
      returns (GetBookingStatusResponse) {}

  // Lists all upcoming bookings for a user
  rpc ListBookings(ListBookingsRequest) returns (ListBookingsResponse) {}
}

과정: 예약 만들기

예약을 생성할 때 Google에서 파트너에게 사용자의 이름, 성, 전화번호, 이메일을 전송합니다. 작업 센터는 파트너 시스템에서 사용자 계정을 조회할 방법이 없으므로 파트너의 관점에서 비회원 결제로 취급해야 합니다. 최종 예약은 파트너의 예약 시스템에 대해 오는 예약과 마찬가지로 파트너의 시스템에 표시되어야 합니다.

Java의 스켈레톤 구현

먼저 컴파일하고 설치할 수 있는 자바 형식의 스켈레톤 gRPC 서버를 제공합니다. 샘플 > gRPC 참조 구현 섹션에서 이를 확인하세요. 이 서버는 인증 및 상태 서비스를 포함하여 통합을 지원하는 데 필요한 gRPC 메서드를 스텁 처리했습니다.

요구사항

gRPC 오류 및 비즈니스 로직 오류

파트너 백엔드가 gRPC 요청을 처리할 때 두 가지 유형의 오류가 발생할 수 있습니다. 잘못된 데이터로 인해 발생하는 예기치 않은 오류와 예약을 만들거나 업데이트할 수 없음을 나타내는 비즈니스 로직 오류(예약 실패 참고)(예: 요청된 시간대를 사용할 수 없는 경우)입니다.

예상치 못한 오류가 발생하면 표준 gRPC 오류 코드를 사용하여 클라이언트에 반환해야 합니다. 이러한 예에는 다음 항목이 포함되나 이에 국한되지 않습니다.

INVALID_VERSION은 CheckAvailability 및 CreateLease와 같은 RPC에서 사용되며 제공된 슬롯에 잘못된 정보가 포함된 경우 반환되어야 합니다.
NOT_FOUND는 CreateBooking 및 ListBookings와 같은 RPC에서 사용되며 제공된 식별자를 파트너가 알 수 없는 경우 반환되어야 합니다.

표준 gRPC 오류 코드는 각 메서드의 참조를 확인하거나 전체 상태 코드 목록을 확인하세요.

반면 비즈니스 로직 오류는 예약 실패에서 캡처되고 RPC 응답으로 반환되어야 합니다. 리소스를 만들거나 업데이트할 때(예: RPC CreateBooking 및 UpdatesBooking) 비즈니스 로직 오류가 발생할 수 있습니다. 이러한 예에는 다음 항목이 포함되나 이에 국한되지 않습니다.

요청된 시간대를 더 이상 사용할 수 없는 경우 SLOT_UNAVAILABLE이 사용됩니다.
제공된 신용카드 유형이 허용되지 않는 경우 PAYMENT_ERROR_CARD_TYPE_REJECTED가 사용됩니다.

멱등성

네트워크를 통한 통신이 항상 신뢰할 수 있는 것은 아니며 응답이 수신되지 않으면 Google Reserve가 RPC를 다시 시도할 수 있습니다. 따라서 상태를 변경하는 모든 RPC (CreateBooking, UpdateBooking)는 멱등성을 갖춰야 합니다. 이러한 RPC의 요청 메시지에는 요청을 고유하게 식별하고 파트너가 재시도된 RPC (단일 예약을 만들기 위한 인텐트)와 두 개의 개별 예약을 구분하는 멱등성 토큰이 포함되어 있습니다.

이러한 예에는 다음 항목이 포함되나 이에 국한되지 않습니다.

CreateBooking RPC 응답에는 생성된 예약이 포함되며, 경우에 따라 예약 흐름의 일부로 결제가 처리됩니다. 정확히 동일한 CreateBookingRequest가 두 번째로 수신되면 (idempotency_token 포함) 동일한 CreateBookingResponse를 반환해야 합니다. 두 번째 예약이 생성되지 않으며 해당하는 경우 사용자에게 정확히 한 번 청구됩니다. CreateBooking 시도가 실패하면 동일한 요청이 다시 전송되면 파트너 백엔드가 다시 시도해야 합니다.

멱등성 요구사항은 멱등성 토큰을 포함하는 모든 메서드에 적용됩니다.

gRPC 서버 보안 및 인증

작업 센터에서 백엔드로 보내는 호출은 인증서 기반의 상호 클라이언트/서버 인증과 함께 SSL/TLS를 사용하여 보호해야 합니다. 이를 위해서는 gRPC 구현에 유효한 서버 인증서를 사용하고 유효한 클라이언트 인증서를 수락해야 합니다.

서버 인증서: 파트너 서버에 서버의 도메인 이름과 연결된 유효한 서버 인증서가 있어야 합니다 (이 허용되는 루트 CA 목록 참고). GRPC 서버 구현은 루트 인증서로 이어지는 인증서 체인을 제공할 것으로 예상합니다. 가장 쉬운 방법은 파트너의 웹 호스트에서 PEM 형식으로 제공한 중간 인증서를 서버 인증서(PEM 형식)에 추가하는 것입니다.

서버 인증서는 연결 시 확인되며 자체 서명된 인증서는 허용되지 않습니다. 인증서가 유효하면 실제 인증서 내용은 확인되지 않습니다. 다음 명령어를 통해 인증서의 유효성을 확인할 수 있습니다.

echo "" | openssl s_client  -connect YOUR_URL:YOUR_PORT  -showcerts -CApath /etc/ssl/certs

클라이언트 인증서: Google로서 파트너에 대해 Google을 인증하기 위해 Google Internet Authority G2에서 발급한 클라이언트 인증서(CA 인증서)와 다음 속성을 제공합니다.

필드	값
`CN`	mapsbooking.businesslink-3.net
`SAN`	DNS:mapsbooking.businesslink-3.net

이 클라이언트 인증서가 없는 연결 시도는 파트너 서버에서 거부해야 합니다.

클라이언트 인증서의 유효성을 검사하기 위해 서버는 신뢰할 수 있는 클라이언트 루트 인증서 집합을 사용합니다. Mozilla와 같은 권한에서 신뢰할 수 있는 이 루트 세트를 가져오거나 현재 Google 인터넷 인증 기관 G2에서 권장하는 루트 세트를 설치할 수 있습니다. 두 경우 모두 루트 인증서를 수동으로 업데이트해야 할 수도 있습니다.

gRPC 상태 확인 프로토콜 구현

GRPC 상태 확인 프로토콜을 구현합니다. 이 프로토콜을 통해 Google은 gRPC 구현의 백엔드 상태를 모니터링할 수 있습니다. 서비스 사양은 GRPC 배포의 일부입니다. GRPC 이름 지정 규칙에 따라 상태 확인 호출의 서비스 이름은 API v2의 경우 ext.maps.booking.partner.v2.BookingService, API v0의 경우 ext.maps.booking.partner.v0.BookingService입니다. 상태 점검은 다른 엔드포인트와 동일한 URL 및 포트에서 실행되어야 합니다.

다른 버전

다른 버전의 API에 관한 문서는 다음 페이지를 참조하세요. * API v3 * API v0