gRPC API Proxy Oluşturma
gRPC API Proxy, Protocol Buffers (protobuf) formatında mesaj işleme yapar. Bu format, JSON'dan daha kompakt ve hızlıdır.
gRPC, HTTP/2 protokolü üzerinde çalışır ve çoklu akış (multiplexing) desteği sağlar.
Unary, Server Streaming, Client Streaming ve Bidirectional Streaming metodlarını destekler.
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
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.
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.
Parse işlemi tamamlandıktan sonra, aşağıdaki bilgiler görüntülenir:
Protobuf package adı
Tüm gRPC servisleri
Her servis için RPC metodları
Request ve response mesaj tipleri
Unary, Server Streaming, Client Streaming veya Bidirectional Streaming
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.
gRPC için özel routing yapılandırması yapılabilir. Daha fazla bilgi için gRPC Routing sayfasına bakılabilir.
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:
Tek bir request, tek bir response. En yaygın kullanılan metod tipidir.
Örnek:
rpc GetUser(UserRequest) returns (UserResponse);
Tek bir request, çoklu response. Sunucu bir stream gönderir.
Örnek:
rpc ListUsers(UserRequest) returns (stream UserResponse);
Çoklu request, tek bir response. İstemci bir stream gönderir.
Örnek:
rpc CreateUsers(stream UserRequest) returns (UserResponse);
Ç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, metodların nasıl yönlendirileceğini belirler.
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ı.
gRPC API Proxy test edilebilir. Apinizer Test Console, gRPC test desteği sağlar.
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:
gRPC servisinizin .proto dosyası yüklenir.
Relative Path belirlenir (örneğin: /grpc/user-service).
Upstream Target olarak internal servisin adresi kullanılır (örneğin: internal-grpc.example.com:50051).
mTLS, Authentication gibi güvenlik politikaları eklenir.
API Proxy kaydedilir ve deploy edilir.
Senaryo 2: gRPC Servis Versiyonlama
Farklı versiyonlar için ayrı API Proxy'ler oluşturmak için:
Her versiyon için ayrı .proto dosyası kullanılır.
Farklı Relative Path'ler kullanılır (örneğin: /grpc/v1/user-service, /grpc/v2/user-service).
Her versiyon için ayrı politikalar tanımlanır.
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:
gRPC API Proxy oluşturulur.
REST dönüştürme politikaları eklenir.
gRPC metodları REST endpoint'lerine map edilir.
Request/Response dönüştürmeleri yapılandırılır.
En İyi Uygulamalar
Protobuf dosyanızın geçerli ve güncel olduğundan emin olun. Geçersiz dosyalar import sırasında hata verebilir.
Relative Path'ler için tutarlı bir isimlendirme kuralı kullanın. Örneğin: /grpc/{servis-adı}/{versiyon}
Backend adreslerini environment variable olarak tanımlayın. Bu, farklı ortamlar için esneklik sağlar.
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 metodları için performans optimizasyonları yapın. Büyük veri akışları için buffer ayarlarını optimize edin.
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
servicetanı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).