Client gRPC per Delphi

2 giugno 2026 · Componenti

sgcWebSockets include ora un client gRPC nativo per Delphi e C++Builder. Il nuovo componente TsgcGRPCClient parla gRPC sul transport HTTP/2 della libreria stessa, quindi non c'è alcun runtime gRPC esterno, nessuna libreria C e nessuna DLL aggiuntiva da distribuire. Fa parte dell'edizione Enterprise e funziona su Windows, macOS, Linux, iOS e Android.

gRPC non è altro che messaggi Protocol Buffers incapsulati su HTTP/2. sgcWebSockets dispone già di uno stack HTTP/2 completo, quindi il client gRPC vi si costruisce direttamente sopra: incapsula i byte della richiesta, applica gli header e i timeout gRPC e fa il parsing dello status e dei trailer riportandoli in risultati tipizzati.

Costruito sul transport HTTP/2 nativo

Un canale gRPC è una connessione HTTP/2. Si crea un TsgcHTTP2Client, lo si punta su host e porta, quindi lo si assegna alla proprietà Client del componente gRPC. Il TLS è gestito dal client HTTP/2 tramite OpenSSL o Windows SChannel.

uses
  sgcHTTP2, sgcGRPC_Client, sgcGRPC_Classes, sgcGRPC_Types;

var
  HTTP2: TsgcHTTP2Client;
  GRPC: TsgcGRPCClient;
  oResponse: TsgcGRPCResponse;
begin
  HTTP2 := TsgcHTTP2Client.Create(nil);
  HTTP2.Host := 'grpc.example.com';
  HTTP2.Port := 443;
  HTTP2.TLS  := True;

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

  // metadata is sent on every call (auth, tracing...)
  GRPC.DefaultMetadata.Add('authorization', 'Bearer eyJ...');

  // unary call: the request is your serialized protobuf message as TBytes
  oResponse := GRPC.Call('helloworld.Greeter', 'SayHello', RequestBytes);
  if oResponse.StatusCode = grpcOK then
    Memo1.Text := oResponse.DataString
  else
    ShowMessage('gRPC error: ' + oResponse.StatusMessage);
end;

Tutti e quattro i tipi di chiamata

Il componente supporta ogni pattern di interazione gRPC, sincrono o asincrono:

Unaria. Call si blocca e restituisce un TsgcGRPCResponse; CallAsync ritorna immediatamente e scatena OnGRPCResponse.
Server streaming. ServerStreamingCall invia una richiesta e riceve un flusso di messaggi, ciascuno dei quali solleva OnGRPCStreamMessage, con OnGRPCStreamEnd alla chiusura.
Client streaming. OpenClientStream, poi SendStreamMessage per ogni messaggio, quindi CloseClientStream per leggere l'unica risposta.
Streaming bidirezionale. OpenBidiStream, SendBidiMessage e CloseBidiStream eseguono uno scambio full-duplex su un unico stream HTTP/2.

Una risposta trasporta tutto ciò che la chiamata ha restituito: StatusCode, StatusMessage, i byte grezzi Data (oppure DataString) e i Trailers.

Metadati, deadline e opzioni del canale

Gli header personalizzati viaggiano attraverso DefaultMetadata per l'intero canale, oppure per singola chiamata. Un timeout per chiamata viene tradotto nell'header standard grpc-timeout, e CancelCall interrompe uno stream in corso. Il canale stesso viene regolato tramite ChannelOptions.

// gzip compression and channel limits
GRPC.ChannelOptions.Compression := grpcGzip;
GRPC.ChannelOptions.MaxMessageSize := 16 * 1024 * 1024;

// abort a long-running stream
GRPC.CancelCall(StreamId);

Interceptor, retry e osservabilità

Una catena di Interceptors avvolge ogni chiamata, così è possibile aggiungere logging, refresh dell'autenticazione o tracing in un unico punto. RetryPolicy ritenta sui codici di status scelti, ServiceConfig applica una policy per metodo e MetricsCollector registra i contatori delle chiamate e le latenze.

GRPC.RetryPolicy.MaxAttempts := 4;
GRPC.RetryPolicy.RetryableStatusCodes :=
  GRPC.RetryPolicy.RetryableStatusCodes + [grpcUNAVAILABLE];

Usa i tuoi Protocol Buffers

Il client accetta e restituisce byte grezzi dei messaggi (TBytes), quindi non ti vincola a nessuna specifica libreria Protocol Buffers. Codifica la tua richiesta con qualsiasi strumento protobuf già in uso, passa i byte a Call e decodifica i byte della risposta allo stesso modo. Il componente gestisce per te il framing con length-prefix di gRPC, il flag di compressione, i codici di status e i trailer.

API gRPC di Google Cloud incluse

Oltre al client generico, sgcWebSockets include client tipizzati per i servizi gRPC di Google Cloud: Pub/Sub, Speech-to-Text, Translation, Vision, Natural Language, Cloud Storage, BigQuery e Vertex AI. Gestiscono l'autenticazione tramite service account e i messaggi di richiesta e risposta, così puoi chiamare metodi di alto livello invece di costruire i protobuf a mano.

Disponibilità

Il client gRPC è disponibile da subito nell'edizione sgcWebSockets Enterprise per Delphi e C++Builder. Un esempio pronto all'uso è incluso in Demos\21.GRPC\01.GRPC_Client, e il riferimento completo a proprietà, metodi ed eventi si trova nella pagina prodotto del Client gRPC.

Domande, feedback o aiuto per iniziare? Contattaci. Riceverai una risposta dalle persone che hanno scritto il codice.