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

예약 서버 구현: API v2

예약 서버를 설정하면 작업 센터에서 사용자를 대신하여 약속 / 예약 / 예약을 만들 수 있습니다.

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

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

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

Google은 신규 파트너에게 권장 API v2 집합을 구현하도록 요청합니다. 파트너는 인프라에 가장 적합한 URL과 포트를 선택할 수 있습니다.

이 섹션에서는 권장 API v2 집합을 소개합니다. API v0을 구현하지 않은 파트너에게 적용됩니다. API v0을 구현한 현재 파트너는 Actions Center에 문의하여 자세히 알아보세요.

아래에서 Proto 형식의 서비스 정의를 다운로드하여 API 구현을 시작합니다.

서비스 정의 다운로드

API 리소스

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

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

메서드

gRPC 서버의 경우 다음 API 메서드를 개발자 측에서 구현해야 필요합니다.

다음 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의 스켈레톤 구현

시작하려면 컴파일하고 설치할 수 있는 Java의 스켈레톤 gRPC 서버를 제공합니다. 샘플 > gRPC 참조 구현 섹션에서 확인해 보세요. 이 서버는 인증 및 상태 서비스를 비롯하여 통합을 지원하는 데 필요한 gRPC 메서드를 스텁 처리했습니다.

요구사항

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

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

예상치 못한 오류가 발생하면 표준 gRPC 오류 코드를 사용하여 클라이언트에 반환해야 합니다. 여기에 해당하는 대표적인 예는 다음과 같습니다.

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

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

반대로 비즈니스 로직 오류는 예약 실패에 캡처되고 RPC 응답으로 반환되어야 합니다. 리소스를 만들거나 업데이트할 때(예: RPC CreateBooking 및 UpdatingBooking 처리 시) 비즈니스 로직 오류가 발생할 수 있습니다. 여기에 해당하는 대표적인 예는 다음과 같습니다.

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 Internet Authority 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