Rezervasyon sunucusunu uygulama: API v2

Sizin tarafınızda bir rezervasyon sunucusu oluşturmak, İşlem Merkezi'nin kullanıcı adına sizinle randevu/rezervasyon oluşturmasına olanak tanır.

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

Tüm yeni iş ortaklarının gRPC API yerine REST API arayüzünü kullanması gerektiğini lütfen unutmayın.

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

Yeni iş ortaklarımızdan, önerilen API v2 grubunu uygulamalarını rica ediyoruz. İş ortakları, altyapıları için en uygun URL ve PORT'u seçebilir.

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

API uygulamasını başlatmak için aşağıdaki proto biçimindeki hizmet tanımını indirin.

Hizmet tanımını indirme

API kaynakları

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

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

Yöntemler

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

Aşağıdaki 5 yöntem, gerekli BookingService RPC grubunu 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 iş ortağına kullanıcının adını, soyadını, telefon numarasını ve e-posta adresini gönderir. İşlem Merkezi'nin, kullanıcının hesabını iş ortağının sisteminde aramasına imkan olmadığından, bu işlem iş ortağı açısından konuk ödemesi olarak değerlendirilmelidir. Nihai rezervasyon, iş ortağının rezervasyon sisteminden gelen rezervasyonlar gibi iş ortağının satıcılarına sistemlerinde gösterilmelidir.

Java'da İskelet Uygulama

Başlamak için derlenip yüklenebilecek Java'da bir iskelet gRPC sunucusu sağlarız. Sana Özel > gRPC Referans Uygulaması bölümünde bulabilirsiniz. Bu sunucu, kimlik doğrulama ve sağlık hizmeti dahil olmak üzere entegrasyonu desteklemek için gereken gRPC yöntemlerini stub'a eklemiştir.

Şartlar

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

İş ortağı arka uç, gRPC isteklerini işlediğinde iki tür hata oluşabilir: yanlış verilerden kaynaklanan beklenmedik hatalar ve rezervasyon oluşturma veya güncelleme işleminin yapılamadığını belirten iş mantığı hataları (ör. istenen alana erişilemiyorsa 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ını veya durum kodlarının tam listesini inceleyin.

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

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

Tekilleştirme

Ağ üzerinden iletişim her zaman güvenilir değildir ve yanıt alınmazsa Google Reserve, RPC'leri yeniden deneyebilir. Bu nedenle, durumu değiştiren tüm RPC'lerin (CreateBooking, UpdateBooking) tekil olması gerekir. Bu RPC'ler için istek mesajları, isteği benzersiz şekilde tanımlamak ve iş ortağının yeniden denenen bir RPC'yi (tek bir rezervasyon oluşturma amacıyla) iki ayrı rezervasyondan ayırt etmesine olanak tanımak için tekilleştirme 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ışı kapsamında 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 iş ortağı arka ucunun, aynı istek tekrar gönderilirse yeniden deneyeceğini unutmayın.

Tekrarlanabilirlik koşulu, tekilleştirme jetonları içeren tüm yöntemler için geçerlidir.

gRPC sunucusu güvenliği ve kimlik doğrulaması

İşlem Merkezi'nden arka uç sunucunuza yapılan çağrıların, sertifika tabanlı karşılıklı istemci/sunucu kimlik doğrulamasıyla SSL/TLS kullanılarak güvence altına alınması gerekir. Bunun için gRPC uygulamanız için geçerli bir sunucu sertifikası kullanılması ve geçerli bir istemci sertifikasının kabul edilmesi gerekir.

Sunucu sertifikası: İş ortağı sunucusunda, sunucunun alan adıyla ilişkili geçerli bir sunucu sertifikası bulunmalıdır (Kabul edilen kök CA'ların listesini inceleyin). GRPC sunucu uygulamaları, kök sertifikaya giden bir sertifika zinciri sunmayı bekler. Bunu yapmanın en kolay yolu, iş ortağının web barındırıcısı tarafından sağlanan ara sertifikaları PEM biçiminde sunucu sertifikasına (ayrıca PEM biçiminde) 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ı: İş ortağıyla kimlik doğrulamamızı (Google olarak) sağlamak için Google Internet Authority G2 tarafından verilen bir istemci sertifikası (CA sertifikası) sağlarız. Bu sertifika aşağıdaki özelliklere sahiptir:

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 güvenilir bir istemci kök sertifikası grubuna dayanır. Bu güvenilir kök grubunu Mozilla gibi bir yetkiliden edinmeyi seçebilir veya Google İnternet Yetkilisi G2 tarafından şu anda önerilen kök grubunu yükleyebilirsiniz. Her iki durumda da, zaman zaman kök sertifikalarını manuel olarak güncellemeniz gerekebilir.

gRPC Durum Denetleme Protokolü'nü uygulama

GRPC Durum Denetleme 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, sağlık kontrolü çağrılarındaki hizmetin adı API v2 için ext.maps.booking.partner.v2.BookingService, API v0 için ise ext.maps.booking.partner.v0.BookingService olur. Sağlık kontrolü, diğer uç noktalarla aynı URL ve PORT üzerinde çalışmalıdır.

Diğer sürümler

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