Delphi'de gRPC İstemcisi Nasıl Kullanılır

2 Haziran 2026 · Bileşenler

TsgcGRPCClient bileşeni, gRPC'yi herhangi bir harici çalışma zamanı olmadan Delphi ve C++Builder'a getirir. sgcWebSockets Enterprise sürümünün bir parçasıdır ve Windows, macOS, Linux, iOS ve Android üzerinde çalışır. Bu kılavuz, istemcinin nasıl çalıştığını, nasıl yapılandırılacağını ve dört gRPC çağrı türünün her birinin Delphi'den nasıl yapılacağını açıklar.

Nasıl çalışır

gRPC, HTTP/2 üzerinde çerçevelenmiş Protocol Buffers mesajlarıdır. Her mesaj, bir HTTP/2 akışında uzunluk önekli bir yük (payload) olarak gönderilir, istek content-type: application/grpc ve grpc-timeout gibi üst bilgiler taşır ve nihai durum grpc-status ve grpc-message trailer'ları olarak gelir.

sgcWebSockets zaten eksiksiz bir HTTP/2 yığını içerir, bu nedenle TsgcGRPCClient bir TsgcHTTP2Client taşıması üzerine oturur. Ona serileştirilmiş istek baytlarınızı verirsiniz; çerçeveleme, üst bilgi ve zaman aşımı işini yapar, HTTP/2 akışını açar ve yanıt ile trailer'ları türlü bir TsgcGRPCResponse'a geri ayrıştırır. İstemci ham TBytes ile çalıştığından, onu halihazırda kullandığınız herhangi bir Protocol Buffers kütüphanesiyle eşleştirebilirsiniz.

İstemcinin kurulması

Bir gRPC kanalı, bir HTTP/2 bağlantısıdır. Bir TsgcHTTP2Client oluşturun, onu ana bilgisayara ve bağlantı noktasına yönlendirin, ardından gRPC bileşeninin Client özelliğine atayın. TLS için, HTTP/2 istemcisi OpenSSL veya Windows SChannel kullanır; yerel bir düz metin sunucusu (h2c) için TLS'yi False olarak ayarlayın.

uses
  sgcHTTP2, sgcGRPC_Client, sgcGRPC_Classes, sgcGRPC_Types;

var
  HTTP2: TsgcHTTP2Client;
  GRPC: TsgcGRPCClient;
begin
  HTTP2 := TsgcHTTP2Client.Create(nil);
  HTTP2.Host := 'grpc.example.com';
  HTTP2.Port := 443;
  HTTP2.TLS  := True;                 // False for a local h2c server
  HTTP2.TLSOptions.IOHandler := iohOpenSSL;  // or iohSChannel on Windows

  GRPC := TsgcGRPCClient.Create(nil);
  GRPC.Client := HTTP2;
end;

Kanalın yapılandırılması

Kanal genelindeki ayarlar ChannelOptions içinde bulunur. Mesaj başına gzip sıkıştırmasını açabilir, hat (wire) içerik türünü seçebilir ve mesaj ile meta veri boyutu sınırlarını yükseltebilirsiniz.

// gzip-compress outgoing messages
GRPC.ChannelOptions.Compression := grpcGzip;          // grpcNoCompression, grpcGzip, grpcDeflate, grpcSnappy

// application/grpc+proto (default) or application/grpc+json
GRPC.ChannelOptions.ContentType := grpcProto;         // or grpcJSON

// raise the limits for large messages
GRPC.ChannelOptions.MaxMessageSize  := 16 * 1024 * 1024;
GRPC.ChannelOptions.MaxMetadataSize := 64 * 1024;

Meta veriler ve kimlik doğrulama

Özel üst bilgiler gRPC meta verisi olarak taşınır. Bunları her çağrıda göndermek için DefaultMetadata'ya ekleyin; burası bir yetkilendirme belirteci veya izleme üst bilgisi için olağan yerdir.

GRPC.DefaultMetadata.Add('authorization', 'Bearer eyJ...');
GRPC.DefaultMetadata.Add('x-api-key', 'my-api-key');

Son tarihler ve iptal

Çağrı başına bir zaman aşımı, standart grpc-timeout üst bilgisi olarak gönderilir, böylece sunucu istemcinizle aynı anda vazgeçebilir. Devam eden bir akış çağrısı, akış açıldığında döndürülen akış kimliği iletilerek CancelCall ile herhangi bir zamanda durdurulabilir.

Tekli (Unary) çağrılar

Tekli bir çağrı, bir istek gönderir ve bir yanıt alır. Call, yanıt gelene kadar bloklar ve StatusCode, StatusMessage, ham Data baytları (veya DataString) ve Trailers ile birlikte bir TsgcGRPCResponse döndürür.

var
  oResponse: TsgcGRPCResponse;
begin
  oResponse := GRPC.Call('helloworld.Greeter', 'SayHello', RequestBytes);
  if oResponse.StatusCode = grpcOK then
    Memo1.Text := oResponse.DataString
  else
    ShowMessage('gRPC error ' + oResponse.StatusMessage);
end;

Kullanıcı arayüzünü duyarlı tutmak için CallAsync kullanın. Hemen döner ve yanıtı OnGRPCResponse olayı aracılığıyla iletir.

GRPC.OnGRPCResponse := GRPCResponse;
GRPC.CallAsync('helloworld.Greeter', 'SayHello', RequestBytes);

procedure TForm1.GRPCResponse(Sender: TObject; const Response: TsgcGRPCResponse);
begin
  if Response.StatusCode = grpcOK then
    Memo1.Text := Response.DataString;
end;

Sunucu akışı

Sunucu akışıyla bir istek gönderirsiniz ve sunucu bir mesaj akışı döndürür. Her mesaj OnGRPCStreamMessage olayını tetikler ve OnGRPCStreamEnd, nihai durumla birlikte bir kez tetiklenir.

GRPC.OnGRPCStreamMessage := GRPCStreamMessage;
GRPC.OnGRPCStreamEnd := GRPCStreamEnd;

GRPC.ServerStreamingCall('chat.Feed', 'Subscribe', RequestBytes);

procedure TForm1.GRPCStreamMessage(Sender: TObject; aStreamId: Integer;
  const aData: TBytes);
begin
  Memo1.Lines.Add(DecodeMessage(aData));
end;

İstemci akışı

İstemci akışı, bunun ayna görüntüsüdür: bir mesaj akışı gönderirsiniz ve sunucu bir kez yanıt verir. Akışı açın, her mesajı gönderin, ardından tek yanıtı okumak için onu kapatın.

var
  vStreamId: Integer;
  oResponse: TsgcGRPCResponse;
begin
  vStreamId := GRPC.OpenClientStream('upload.Service', 'Send');
  GRPC.SendStreamMessage(vStreamId, ChunkBytes1);
  GRPC.SendStreamMessage(vStreamId, ChunkBytes2);
  oResponse := GRPC.CloseClientStream(vStreamId);
  if oResponse.StatusCode = grpcOK then
    ShowMessage('Upload accepted');
end;

Çift yönlü akış

Çift yönlü akış, tek bir HTTP/2 akışı üzerinde tam çift yönlü (full-duplex) bir alışveriş çalıştırır: her iki taraf da istedikleri zaman gönderir. Akışı açın, gerektiğinde mesaj gönderin, gelen mesajları OnGRPCStreamMessage içinde işleyin ve bittiğinde kapatın.

var
  vStreamId: Integer;
begin
  vStreamId := GRPC.OpenBidiStream('chat.Room', 'Connect');
  GRPC.SendBidiMessage(vStreamId, EncodeMessage('hello'));
  // ... incoming messages arrive on OnGRPCStreamMessage ...
  GRPC.CloseBidiStream(vStreamId);
end;

Durum kodları ve hata işleme

Her yanıt, grpcOK'tan standart gRPC kümesine kadar (grpcNOT_FOUND, grpcUNAVAILABLE, grpcDEADLINE_EXCEEDED, grpcUNAUTHENTICATED ve gerisi) türlü bir StatusCode taşır. Asenkron ve akış çağrıları için, OnGRPCError OK olmayan bir gRPC durumunu, OnGRPCException ise bir taşıma veya bağlantı hatasını bildirir.

GRPC.OnGRPCError := GRPCError;

procedure TForm1.GRPCError(Sender: TObject; aStreamId: Integer;
  aStatusCode: TsgcGRPCStatusCode; const aStatusMessage: string);
begin
  Memo1.Lines.Add(Format('gRPC error %d: %s', [Ord(aStatusCode), aStatusMessage]));
end;

Otomatik yeniden deneme

İstemci, başarısız çağrıları sizin için yeniden deneyebilir. RetryPolicy'yi etkinleştirin, deneme sayısını ve geri çekilmeyi (backoff) ayarlayın ve yeniden denemeyi tetiklemesi gereken durum kodlarını listeleyin. Bu, geçici grpcUNAVAILABLE hataları için tipik yapılandırmadır.

GRPC.RetryPolicy.Enabled := True;
GRPC.RetryPolicy.MaxAttempts := 4;
GRPC.RetryPolicy.InitialBackoff := 200;     // ms
GRPC.RetryPolicy.BackoffMultiplier := 2.0;
GRPC.RetryPolicy.RetryableStatusCodes :=
  GRPC.RetryPolicy.RetryableStatusCodes + [grpcUNAVAILABLE, grpcRESOURCE_EXHAUSTED];

Günlük tutma veya bir belirteci yenileme gibi kesişen mantık için, her çağrıyı tek bir yerde saran Interceptors zincirine bir giriş ekleyin.

Bundan sonra nereye

Bu genel istemcinin üzerine, sgcWebSockets, Google Cloud gRPC hizmetleri (Pub/Sub, Speech-to-Text, Translation, Vision, Natural Language, Cloud Storage, BigQuery ve Vertex AI) için türlü istemciler içerir, böylece protobuf'ları elle bir araya getirmek yerine üst düzey metotları çağırırsınız. Çalıştırılmaya hazır bir örnek Demos\21.GRPC\01.GRPC_Client içinde yer alır ve tam referans gRPC Client ürün sayfasında bulunur.

Sorularınız mı var veya başlarken yardıma mı ihtiyacınız var? Bize ulaşın. Kodu yazan kişilerden bir yanıt alacaksınız.