gRPC API Proxy Oluşturma

gRPC servislerinizi Apinizer platformu üzerinden yönetebilir ve güvenli bir şekilde expose edebilirsiniz. Google tarafından geliştirilen yüksek performanslı RPC framework’ünü kullanabilir, Protocol Buffers (protobuf) formatında çalışabilirsiniz. Protobuf dosyasından gRPC API Proxy oluşturabilir, proto file import edebilir, service ve method tanımları yapabilir ve routing yapılandırması gerçekleştirebilirsiniz

Protobuf Formatı

gRPC API Proxy, Protocol Buffers (protobuf) formatında mesaj işleme yapar. Bu format, JSON’dan daha kompakt ve hızlıdır.

HTTP/2 Protokolü

gRPC, HTTP/2 protokolü üzerinde çalışır ve çoklu akış (multiplexing) desteği sağlar.

Streaming Desteği

Unary, Server Streaming, Client Streaming ve Bidirectional Streaming metodlarını destekler.

Yüksek Performans

Binary protobuf formatı sayesinde JSON’a göre daha yüksek performans sağlar.

​

gRPC API Proxy Oluşturma Yöntemleri

gRPC API Proxy oluşturmak için birkaç yöntem mevcuttur:

Protobuf (.proto) Dosyasından Import

En yaygın yöntem, protobuf (.proto) dosyasından import etmektir. Bu yöntem, servislerinizi, metodlarınızı ve mesaj tiplerinizi otomatik olarak içe aktarır.

Manuel Oluşturma

Protobuf dosyası olmadan da manuel olarak gRPC API Proxy oluşturabilirsiniz. Bu durumda servisleri ve metodları manuel olarak tanımlamanız gerekir.

Mevcut API Proxy'den Kopyalama

Mevcut bir gRPC API Proxy’yi kopyalayarak yeni bir proxy oluşturabilirsiniz. Bu yöntem, benzer servisler için zaman kazandırır.

​

Protobuf Dosyasından Import

1. API Proxy Oluşturma Sayfasına Gidin

   Sol taraftaki ana menüde Geliştirme → API Proxy’ler (Development → API Proxies) ögesi seçilir. Açılan arayüzde sağ üstteki +Create butonuna tıklanır ve gRPC API seçeneği seçilir.

2. Protobuf Dosyasını Yükleyin

   Protobuf dosyasını yüklemek için üç yöntem mevcuttur:

   Yöntem 1: Dosya Yükleme

   Dosya Yükle (Upload File) butonuna tıklanır. Bilgisayarınızdan .proto dosyası seçilir. Dosya otomatik olarak parse edilir ve servis bilgileri görüntülenir.

   Protobuf Dosyası Formatı Protobuf dosyası, gRPC servislerinizi tanımlayan bir dosyadır. Dosya içinde service, rpc, message gibi tanımlar bulunur.

   Yöntem 2: URL'den Yükleme

   URL Gir bağlantısına tıklanır. Protobuf dosyasının URL’si girilir ve Parse butonuna tıklanır. Dosya parse edilir ve servis bilgileri görüntülenir.

   Kimlik Doğrulama ve SSL Spec URL’si kimlik doğrulama gerektiriyorsa, Spec Authorization Kullan seçeneğini etkinleştirerek özel header’lar veya Basic Auth (kullanıcı adı/şifre) bilgilerini girebilirsiniz. SSL / Sertifika Ayarları bölümünde Bağlantı Zaman Aşımı, SSL/TLS Ayarlarını Özelleştir, SSL Doğrulamayı Atla ve Sunucu Sertifikası Doğrulaması ayarlarını yapılandırabilirsiniz. Detay için API Proxy Oluşturma sayfasına bakınız.

   Yöntem 3: Metin Olarak Yapıştırma

   Metin Olarak Yapıştır (Paste as Text) seçeneği seçilir. Protobuf içeriği metin alanına yapıştırılır ve Parse butonuna tıklanır. İçerik parse edilir ve servis bilgileri görüntülenir.

3. Servis Bilgilerini Kontrol Edin

   Parse işlemi tamamlandıktan sonra, aşağıdaki bilgiler görüntülenir:

   Package

   Protobuf package adı

   Servisler

   Tüm gRPC servisleri

   Metodlar

   Her servis için RPC metodları

   Mesaj Tipleri

   Request ve response mesaj tipleri

   Streaming Tipi

   Unary, Server Streaming, Client Streaming veya Bidirectional Streaming

4. Routing Yapılandırması

   Client Route (Relative Path)

   Client Route, API Proxy’nin dış dünyaya açılan endpoint’idir. İstemciler bu endpoint üzerinden gRPC servisine erişir.

   Örnek:

   Relative Path: /grpc/user-service
   

   Bu durumda gRPC servisine şu şekilde erişilir:

   {apinizer-gateway}/grpc/user-service
   

   Upstream Target (Backend Address)

   Upstream Target, backend gRPC servisinizin adresidir. API Proxy, istekleri bu adrese yönlendirir.

   Yapılandırma Formatı:

   host:port
   

   Örnek:

   backend-grpc.example.com:50051
   

   gRPC Port gRPC servisleri genellikle 50051 gibi özel portlarda çalışır. Backend servisinizin port numarasını doğru belirttiğinizden emin olun.

5. gRPC Routing Yapılandırması

   gRPC için özel routing yapılandırması yapılabilir. Daha fazla bilgi için gRPC Routing sayfasına bakılabilir.

6. API Proxy'yi Kaydedin

   Tüm bilgiler kontrol edilir. Relative Path alanı doldurulur (zorunlu). Upstream Target bilgisi girilir (host:port formatında). Sağ üstteki Kaydet butonuna tıklanır.

gRPC API Proxy başarıyla oluşturuldu!

​

Protobuf Dosyası Yapısı

Protobuf dosyası genellikle şu yapıya sahiptir:

syntax = "proto3";

package com.example.service;

// Mesaj tanımları
message UserRequest {
  string user_id = 1;
}

message UserResponse {
  string user_id = 1;
  string name = 2;
  string email = 3;
}

// Servis tanımı
service UserService {
  // Unary RPC
  rpc GetUser(UserRequest) returns (UserResponse);
  
  // Server Streaming RPC
  rpc ListUsers(UserRequest) returns (stream UserResponse);
  
  // Client Streaming RPC
  rpc CreateUsers(stream UserRequest) returns (UserResponse);
  
  // Bidirectional Streaming RPC
  rpc ChatUsers(stream UserRequest) returns (stream UserResponse);
}

​

gRPC Metod Tipleri

gRPC dört farklı metod tipini destekler:

Unary RPC

Tek bir request, tek bir response. En yaygın kullanılan metod tipidir.

Örnek:

rpc GetUser(UserRequest) returns (UserResponse);

Server Streaming RPC

Tek bir request, çoklu response. Sunucu bir stream gönderir.

Örnek:

rpc ListUsers(UserRequest) returns (stream UserResponse);

Client Streaming RPC

Çoklu request, tek bir response. İstemci bir stream gönderir.

Örnek:

rpc CreateUsers(stream UserRequest) returns (UserResponse);

Bidirectional Streaming RPC

Çoklu request, çoklu response. Her iki taraf da stream gönderir.

Örnek:

rpc ChatUsers(stream UserRequest) returns (stream UserResponse);

​

Import Sonrası Yapılandırma

API Proxy oluşturulduktan sonra, aşağıdaki yapılandırmalar yapılabilir:

gRPC Routing Yapılandırması

gRPC Routing, metodların nasıl yönlendirileceğini belirler.

Politikalar Ekleme

API Proxy’ye güvenlik, doğrulama, dönüştürme gibi politikalar eklenebilir.

gRPC için bazı politikalar özel olarak uygulanabilir. Örneğin, protobuf mesajlarını doğrulama veya dönüştürme politikaları.

Test Etme

gRPC API Proxy test edilebilir. Apinizer Test Console, gRPC test desteği sağlar.

Yükleme ve Sürüm

API Proxy ortam(lar)a deploy edilebilir.

​

Yaygın Senaryolar

Senaryo 1: Internal gRPC Servisini Expose Etme

Internal bir gRPC servisini dış dünyaya expose etmek için:

1. Proto Dosyasını Yükleyin

   gRPC servisinizin .proto dosyası yüklenir.

2. Relative Path Belirleyin

   Relative Path belirlenir (örneğin: /grpc/user-service).

3. Upstream Target Ayarlayın

   Upstream Target olarak internal servisin adresi kullanılır (örneğin: internal-grpc.example.com:50051).

4. Güvenlik Politikaları Ekleyin

   mTLS, Authentication gibi güvenlik politikaları eklenir.

5. Kaydedin ve Deploy Edin

   API Proxy kaydedilir ve deploy edilir.

Senaryo 2: gRPC Servis Versiyonlama

Farklı versiyonlar için ayrı API Proxy’ler oluşturmak için:

1. Her Versiyon İçin Ayrı Proto Dosyası

   Her versiyon için ayrı .proto dosyası kullanılır.

2. Farklı Relative Path'ler

   Farklı Relative Path’ler kullanılır (örneğin: /grpc/v1/user-service, /grpc/v2/user-service).

3. Ayrı Politikalar

   Her versiyon için ayrı politikalar tanımlanır.

4. Geçiş Stratejisi

   Versiyonlar arasında geçiş stratejisi belirlenir.

Senaryo 3: gRPC'den REST'e Dönüştürme

gRPC servisini REST API olarak expose etmek için:

1. gRPC API Proxy Oluşturun

   gRPC API Proxy oluşturulur.

2. REST Dönüştürme Politikaları

   REST dönüştürme politikaları eklenir.

3. Metodları Map Edin

   gRPC metodları REST endpoint’lerine map edilir.

4. Dönüştürmeleri Yapılandırın

   Request/Response dönüştürmeleri yapılandırılır.

​

En İyi Uygulamalar

Protobuf Dosyası Kalitesi

Protobuf dosyanızın geçerli ve güncel olduğundan emin olun. Geçersiz dosyalar import sırasında hata verebilir.

Relative Path Stratejisi

Relative Path’ler için tutarlı bir isimlendirme kuralı kullanın. Örneğin: /grpc/{servis-adı}/{versiyon}

Backend Adresi

Backend adreslerini environment variable olarak tanımlayın. Bu, farklı ortamlar için esneklik sağlar.

mTLS Güvenliği

gRPC için mutlaka mTLS (mutual TLS) güvenliği kullanın. gRPC servisleri genellikle internal network’te çalışır ve güvenlik kritiktir.

Streaming Performansı

Streaming metodları için performans optimizasyonları yapın. Büyük veri akışları için buffer ayarlarını optimize edin.

Error Handling

gRPC error kodlarını (status codes) doğru şekilde handle edin. gRPC, HTTP status kodlarından farklı bir error sistemi kullanır.

​

Sorun Giderme

Import Hatası

Sorun: Protobuf dosyası import edilemiyor.

Çözüm:

• Protobuf dosyasının geçerli syntax’a sahip olduğundan emin olun (proto2 veya proto3).
• Dosyanın tüm bağımlılıklarının (import edilen dosyalar) mevcut olduğundan emin olun.
• URL erişilebilirliğini kontrol edin.
• Dosya boyutunun limit içinde olduğundan emin olun.

Servisler Görünmüyor

Sorun: Import sonrası servisler görünmüyor.

Çözüm:

• Protobuf dosyasında service tanımlarının doğru olduğundan emin olun.
• Package adının doğru tanımlandığını kontrol edin.
• RPC metodlarının doğru şekilde tanımlandığını kontrol edin.

Routing Hatası

Sorun: İstekler backend’e yönlendirilmiyor.

Çözüm:

• Upstream Target adresinin doğru formatda olduğundan emin olun (host:port).
• Backend gRPC servisinizin erişilebilir olduğunu kontrol edin.
• gRPC Routing yapılandırmasını kontrol edin.
• Port numarasının doğru olduğundan emin olun.

Streaming Hatası

Sorun: Streaming metodları çalışmıyor.

Çözüm:

• Streaming metodlarının doğru tanımlandığını kontrol edin.
• HTTP/2 desteğinin aktif olduğundan emin olun.
• Timeout ayarlarını kontrol edin (streaming için daha uzun timeout gerekebilir).

​

Sonraki Adımlar

gRPC Routing

gRPC Routing yapılandırmasını öğrenin

Politika Yönetimi

Politikalar eklemeyi öğrenin

mTLS Güvenliği

mTLS güvenliği hakkında bilgi edinin

Yükleme ve Sürüm

Deployment yapmayı öğrenin