Ana içeriğe atla

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:
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.
Protobuf dosyası olmadan da manuel olarak gRPC API Proxy oluşturabilirsiniz. Bu durumda servisleri ve metodları manuel olarak tanımlamanız gerekir.
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:
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.
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.
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, 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 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

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.
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.
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

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.
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.
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.
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