Rezervasyon sunucusunu uygulama: API v2

Kendi tarafınızda bir rezervasyon sunucusu ayarladığınızda İşlemler Merkezi, kullanıcı adına sizinle randevu/rezervasyon oluşturabilir.

gRPC'ye dayalı bir API arayüzü uygulama

Lütfen unutmayın: Tüm yeni iş ortakları gRPC API yerine REST API arayüzünü kullanmalıdır.

gRPC'ye dayalı bir API arayüzü uygulayın. Bu sayede Google, rezervasyon istekleri gönderebilir. API yüzeyi, gRPC'nin protobuf tabanlı IDL'si kullanılarak tanımlanır.

Yeni iş ortaklarımızdan, önerilen bir API v2 grubunu uygulamalarını istiyoruz. İş ortakları, altyapıları için en uygun URL'yi ve bağlantı noktasını seçebilir.

Bu bölümde, önerilen bir API v2 grubu tanıtılmaktadır. Bu, API v0'ı uygulamamış iş ortakları için geçerlidir. API v0'ı uygulayan mevcut iş ortaklarımız daha fazla bilgi için lütfen İşlemler Merkezi ile iletişime geçsin.

API uygulamasını kullanmaya başlamak için aşağıdaki hizmet tanımını proto biçiminde indirin.

Hizmet tanımını indirin

API kaynakları

Lütfen bu uygulamada kullanılacak aşağıdaki kaynak türleri hakkında bilgi edinin:

  • Slot: bir envanter yuvası
  • Rezervasyon: Envanter aralığı için randevu

Yöntemler

gRPC sunucusu için aşağıdaki API yöntemlerinin sizin tarafınızda uygulanması gerekir:

Bu 5 yöntem, gerekli BookingService RPC'lerini tanımlar:

// 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) {}
}

Akış: Rezervasyon oluşturma

Şekil 1: Bir slottan rezervasyon oluşturma

Google, rezervasyon oluştururken kullanıcının verdiği adı, soyadını, telefon numarasını ve e-posta adresini iş ortağına gönderir. İşlemler Merkezi'nin kullanıcının hesabını iş ortağının sisteminde arama yolu olmadığından bu, iş ortağının bakış açısıyla misafir ödemesi olarak değerlendirilmelidir. Son rezervasyon, iş ortağının sisteminde iş ortağının satıcılarına, iş ortağının rezervasyon sisteminden gelen rezervasyonlar gibi gösterilmelidir.

Java'da İskelet Uygulama

Başlamak için Java'da derlenip yüklenebilen bir iskelet gRPC sunucusu sağlıyoruz. Bu bölümü Örnekler > gRPC Referans Uygulaması bölümünde bulabilirsiniz. Bu sunucuda, kimlik doğrulama ve sağlık hizmeti de dahil olmak üzere entegrasyonu desteklemek için gereken gRPC yöntemleri bulunur.

Şartlar

gRPC hatası ve iş mantığı hatası

Bir iş ortağı arka ucu gRPC isteklerini işlerken iki tür hata oluşabilir: yanlış verilerden kaynaklanan beklenmedik hatalar ve bir rezervasyon oluşturma veya güncelleme yetersizliğini gösteren iş mantığı hataları (ör. istenen zaman aralığı kullanılamıyorsa) (Rezervasyon Hatası bölümüne bakın).

Karşılaşılan beklenmedik hatalar, standart gRPC hata kodları kullanılarak istemciye döndürülmelidir. İlgili örnekler aşağıdakileri kapsar, ancak bunlarla sınırlı değildir:

  • INVALID_ARGUMENT, CheckAvailability ve CreateLease gibi RPC'lerde kullanılır ve sağlanan yuva geçersiz bilgiler içeriyorsa döndürülmelidir.
  • NOT_FOUND, CreateBooking ve ListBookings gibi RPC'lerde kullanılır ve sağlanan tanımlayıcı iş ortağı tarafından bilinmiyorsa döndürülmelidir.

Her yöntemin standart gRPC hata kodları için referansına veya durum kodu listesinin tamamına bakın.

Aksine, iş mantığı hataları Booking Failure içinde yakalanmalı ve RPC yanıtında döndürülmelidir. Bir kaynak oluşturulurken veya güncellenirken (ör. CreateBooking ve UpdatingBooking RPC'lerinin işlenmesi sırasında) işletme mantığı hatalarıyla karşılaşılabilir. İlgili örnekler aşağıdakileri kapsar, ancak bunlarla sınırlı değildir:

  • İstenen yer artık kullanılamıyorsa SLOT_UNAVAILABLE kullanılır.
  • Sağlanan kredi kartı türü kabul edilmediğinde PAYMENT_ERROR_CARD_TYPE_REJECTED kullanılır.

İdempotency

Ağ üzerinden iletişim her zaman güvenilir değildir ve yanıt alınmazsa Google Reserve, RPC'leri yeniden denemeye çalışabilir. Bu nedenle, durumu değiştiren tüm RPC'ler (CreateBooking, UpdateBooking) idempotent olmalıdır. Bu RPC'ler için istek mesajları, isteği benzersiz şekilde tanımlamak ve iş ortağının yeniden denenmiş bir RPC (tek bir rezervasyon oluşturma amacıyla) ile iki ayrı rezervasyon arasında ayrım yapmasına olanak tanımak için idempotentlik jetonları içerir.

İlgili örnekler aşağıdakileri kapsar, ancak bunlarla sınırlı değildir:

  • Başarılı bir CreateBooking RPC yanıtı, oluşturulan rezervasyonu içerir ve bazı durumlarda ödeme, rezervasyon akışının bir parçası olarak işlenir. Tam olarak aynı CreateBookingRequest ikinci kez alınırsa (idempotency_token dahil), aynı CreateBookingResponse döndürülmelidir. İkinci bir rezervasyon oluşturulmaz ve varsa kullanıcıdan tam olarak bir kez ödeme alınır. CreateBooking girişimi başarısız olursa aynı istek tekrar gönderildiğinde iş ortağı arka ucunun yeniden denemesi gerektiğini unutmayın.

İdempotency (Aynı işlemi birden fazla kez yapmanın aynı sonucu vermesi) koşulu, idempotency jetonları içeren tüm yöntemler için geçerlidir.

gRPC sunucusu güvenliği ve kimlik doğrulama

İşlemler Merkezi'nden arka uçunuza yapılan çağrıların, sertifikaya dayalı karşılıklı istemci/sunucu kimlik doğrulamasıyla SSL/TLS kullanılarak güvenli hale getirilmesi gerekir. Bu işlem için gRPC uygulamanızda geçerli bir sunucu sertifikası kullanmanız ve geçerli bir istemci sertifikasını kabul etmeniz gerekir.

Sunucu sertifikası: İş ortağı sunucusu, sunucunun alan adıyla ilişkili geçerli bir sunucu sertifikasıyla donatılmalıdır (Kabul edilen kök CA'ların bu listesine bakın). GRPC sunucu uygulamaları, kök sertifikaya kadar uzanan bir sertifika zinciri sunmayı bekler. Bunu yapmanın en kolay yolu, iş ortağının web barındırıcısı tarafından PEM biçiminde sağlanan ara sertifikaları, sunucu sertifikasına (bu da PEM biçimindedir) eklemektir.

Sunucu sertifikası bağlantı sırasında doğrulanır ve kendinden imzalı sertifikalar kabul edilmez. Sertifika geçerli olduğu sürece gerçek sertifika içeriği kontrol edilmez. Sertifikanızın geçerliliğini aşağıdaki komutla kontrol edebilirsiniz:

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

İstemci sertifikası: Google olarak iş ortağında kimliğimizi doğrulamak için aşağıdaki özelliklere sahip, Google Internet Authority G2 tarafından verilmiş bir istemci sertifikası (CA sertifikası) sağlıyoruz:

Alan Değer
CN mapsbooking.businesslink-3.net
SAN DNS:mapsbooking.businesslink-3.net

Bu istemci sertifikası olmadan yapılan bağlantı denemeleri iş ortağı sunucusu tarafından reddedilmelidir.

Sunucu, istemci sertifikasını doğrulamak için bir dizi güvenilir istemci kök sertifikasına güvenir. Bu güvenilir kökleri Mozilla gibi bir yetkiliden almayı veya Google Internet Authority G2 tarafından şu anda önerilen kök kümesini yüklemeyi seçebilirsiniz. Her iki durumda da zaman zaman kök sertifikaları manuel olarak güncellemeniz gerekebilir.

gRPC durum denetimi protokolünü uygulama

GRPC Durum Denetimi Protokolü'nü uygulayın. Bu protokol, Google'ın gRPC uygulamanızın arka uç durumunu izlemesini sağlar. Hizmet spesifikasyonu, GRPC dağıtımının bir parçasıdır. GRPC adlandırma kuralına göre, hizmetin adının sağlık durumu kontrolü çağrılarında API v2 için ext.maps.booking.partner.v2.BookingService, API v0 için ise ext.maps.booking.partner.v0.BookingService olması gerekir. Durum denetimi, diğer uç noktalarla aynı URL ve bağlantı noktasında çalıştırılmalıdır.

Diğer sürümler

API'nin diğer sürümlerine ait dokümanlar için aşağıdaki sayfalara bakın: * API v3 * API v0