Rezervasyon sunucusunu uygulama: API v2

Kendi tarafınızda bir Rezervasyon sunucusu oluşturmak, Actions Center'ın kullanıcı adına sizinle randevu / rezervasyon / rezervasyon oluşturmasına olanak tanır.

gRPC'ye dayalı bir API arayüzü uygulayın

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

gRPC'yi temel alan 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 ve bağlantı noktasını seçebilir.

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

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

Hizmet tanımını indirin

API kaynakları

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

Yöntemler

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

Bu 5 yöntem, gerekli ReservationService 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şturun

Şekil 1: Slot'tan 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. Actions Center'da iş ortağının sisteminde kullanıcının hesabını aramak mümkün olmadığından bu işlem, iş ortağı açısından giriş yapmadan ödeme olarak düşünülmelidir. Son rezervasyon, iş ortağının rezervasyon sistemine gelen rezervasyonlar gibi, iş ortağının sistemlerindeki satıcılara da gösterilmelidir.

Java'da İskelet Uygulaması

Başlamak için Java'da derlenebilecek ve yüklenebilecek iskelet gRPC sunucusu sağlıyoruz. Örnekler > gRPC Referans Uygulaması bölümüne göz atın. Bu sunucu, kimlik doğrulama ve durum hizmeti dahil olmak üzere entegrasyonu desteklemek için gereken gRPC yöntemlerini parçalara ayırır.

Koşullar

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

İş ortağı arka ucu gRPC isteklerini işlediğinde iki tür hata ortaya çıkabilir: yanlış verilerden kaynaklanan beklenmedik hatalar ve rezervasyon oluşturamadığını veya güncelleyemediğini belirten iş mantığı hataları (Rezervasyon Başarısızlığı bölümüne bakın) (ör. istenen slot kullanılamadığında).

Karşılaşılması durumunda beklenmedik hataların, standart gRPC hata kodları kullanılarak istemciye döndürülmesi gerekir. Bunlarla sınırlı olmamakla birlikte aşağıda bazı örnekleri bulabilirsiniz:

  • INVALID_ARGUMENT, CheckAvailability ve CreateLease gibi RPC'lerde kullanılır ve sağlanan alan geçersiz bilgiler içeriyorsa döndürülmelidir.
  • NOT_FOUND, CreateReservation ve ListReservations 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 tam durum kodu listesine bakın.

Aksine, iş mantığı hataları Rezervasyon Hatası bölümünde yakalanmalı ve RPC yanıtında iade edilmelidir. Bir kaynak oluşturulurken veya güncellenirken (ör. RPC'leri CreateReservation ve UpdateReservation'ı işlerken) iş mantığı hatalarıyla karşılaşabilirsiniz. Bunlarla sınırlı olmamakla birlikte aşağıda bazı örnekleri bulabilirsiniz:

  • İstenen alan artık kullanılabilir değilse SLOT_UNAVAILABLE kullanılır.
  • Sağlanan kredi kartı türü kabul edilmiyorsa PAYMENT_ERROR_CARD_TYPE_REJECTED kullanılır.

Boşta kalma

Ağ üzerinden iletişim her zaman güvenilir değildir ve Google Reserve, herhangi bir yanıt alınmadığı takdirde RPC'leri yeniden deneyebilir. Bu nedenle, mutasyon durumundaki tüm RPC'ler (CreateReservation, UpdateReservation) eşgüçlü olmalıdır. Bu RPC'ler için istek mesajları, isteği benzersiz bir şekilde tanımlamak ve iş ortağının yeniden denenen bir RPC ile (tek rezervasyon oluşturma amacıyla) iki ayrı rezervasyon arasında ayrım yapabilmesini sağlayan kimliksiz durum jetonları içerir.

Bunlarla sınırlı olmamakla birlikte aşağıda bazı örnekleri bulabilirsiniz:

  • 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ı CreateReservationRequest ikinci kez alınırsa (idempotency_token dahil) aynı CreateReservationResponse döndürülmelidir. İkinci bir rezervasyon oluşturulmaz ve mümkünse kullanıcıdan tam olarak bir kez ödeme alınır. CreateReservation denemesi başarısız olursa iş ortağı arka ucu, aynı istek tekrar gönderilirse tekrar denemelidir.

Boşta kalma gereksinimi, yalnızlık jetonları içeren tüm yöntemler için geçerlidir.

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

Actions Center'dan arka ucunuza yapılan çağrıların sertifika tabanlı, karşılıklı istemci/sunucu kimlik doğrulamasıyla SSL/TLS kullanılarak güvenliğinin sağlanması gerekir. Bu, gRPC uygulamanız için geçerli bir sunucu sertifikasının kullanılmasını ve geçerli bir istemci sertifikasını kabul etmenizi gerektirir.

Sunucu sertifikası: İş ortağı sunucusunda, sunucunun alan adıyla ilişkilendirilmiş geçerli bir sunucu sertifikası bulunmalıdır (kabul edilen kök CA'ların listesine göz atın). 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 (aynı zamanda PEM biçiminde) sunucu sertifikasına eklemektir.

Sunucu sertifikası, bağlantı zamanı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ğımızın kimliğini doğrulayabilmemiz için Google İnternet Yetkilisi G2 (CA sertifikası) tarafından verilmiş, aşağıdaki özelliklere sahip bir istemci sertifikası sağlarız:

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

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

Sunucu, istemci sertifikasını doğrulamak için bir dizi güvenilir istemci kök sertifikasından yararlanır. Bu güvenilir kökler grubunu Mozilla gibi bir yetkiliden almayı veya şu anda Google InternetAuthority G2 tarafından önerilen kök kümesi grubunu yüklemeyi seçebilirsiniz. Her iki durumda da kök sertifikaları zaman zaman 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, durum denetimi çağrılarındaki hizmetin adı API v2 için ext.maps.booking.partner.v2.BookingService veya API v0 için ext.maps.booking.partner.v0.BookingService olur. Durum denetimi, diğer uç noktalarla aynı URL ve BAĞLANTI NOKTAsında ç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