cliente

Home > O cliente

O cliente (TRALClient)

Vale para a 1.1 em diante · Delphi e Lazarus · Nível: iniciante

Em uma frase: o TRALClient faz pedidos a qualquer servidor HTTP (RAL ou não), com o mesmo código para todos os motores.

Você vai precisar: o primeiro cliente funcionando.

O básico

Cliente.EngineType := 'Indy';                 // e a unit RALIndyClient no uses
Cliente.BaseURL.Text := 'https://api.empresa.com.br';

Motor (EngineType)	Unit no uses	Onde
'Indy'	RALIndyClient	Delphi e Lazarus
'mORMot2'	RALSynopseClient	Delphi e Lazarus
'netHTTP'	RALnetHTTPClient	Delphi; no Windows não precisa de DLL nenhuma
'fpHTTP'	RALfpHTTPClient	Lazarus
'OkHttp' 1.2 🚧	RALOkHttpClient	Delphi, Android
'MsQuic', 'Kwik' 1.2 🚧	RALMsQuicClient, RALKwikClient	só com servidor RAL MsQuic (QUIC)

Enviar dados

Preencha Cliente.Request e chame o método:

Cliente.Request.Clear;                                   // limpa o pedido anterior
Cliente.Request.AddQuery('cidade', 'Recife');            // ?cidade=Recife
Cliente.Request.AddHeader('X-Empresa', '12');            // cabeçalho
Cliente.Request.AddCookie('sessao', 'abc');              // cookie
Cliente.Request.AddBody('{"nome":"Ana"}', rctAPPLICATIONJSON); // corpo JSON
// ou campos de formulário:      Cliente.Request.AddField('nome', 'Ana');
// ou um arquivo (multipart):    Cliente.Request.AddFile('C:\foto.jpg');
Cliente.Post('/clientes', Resposta);

Métodos: Get, Post, Put, Patch, Delete.

Duas formas de chamar

Esperar a resposta (o programa para até ela chegar):

Cliente.Get('/clientes/7', Resposta);
try
  if Resposta.StatusCode = HTTP_OK then
    Memo1.Text := Resposta.ResponseText;
finally
  Resposta.Free;            // nessa forma a resposta é sua
end;

Falha de rede (servidor fora, tempo esgotado) levanta exceção: use try/except.

Com evento (a resposta chega num procedimento seu):

Cliente.Get('/clientes/7', AoResponder, ebMultiThread);

procedure TForm1.AoResponder(ASender: TObject; AResponse: TRALResponse;
  AException: StringRAL);
begin
  if AException <> '' then
    ShowMessage('Falhou: ' + AException)
  else
    Memo1.Text := AResponse.ResponseText;   // não guarde AResponse: é liberada depois
end;

Terceiro parâmetro	O que acontece
ebSingleThread	o evento roda antes de Get voltar. É o padrão desde a 1.2 🚧 (antes era o outro)
ebMultiThread	Get volta na hora; o evento roda depois, na thread principal. Use em botões, para a tela não travar

Vários servidores: troca automática

Uma URL por linha em BaseURL. Se o primeiro não responde, o cliente tenta o próximo:

Cliente.BaseURL.Text := 'https://servidor1:8000'#13'https://servidor2:8000';

Só repete em outro servidor quando é seguro: falha de conexão (com qualquer método) ou tempo esgotado em GET, PUT, DELETE. Um POST que já foi enviado não é repetido, para não gravar duas vezes.

Propriedades úteis

Propriedade	Padrão	O que faz
ConnectTimeout	30000	ms para conectar
RequestTimeout	10000	ms esperando a resposta
Authentication	vazio	login (Autenticação)
CompressType	ctGZip	comprime o que envia. Só vale com RALCompressZLib (gzip, deflate, zlib) no uses; sem a unit, vai sem compressão
CriptoOptions	desligado	cifra o corpo, entre RAL e RAL (Criptografia)
KeepAlive	ligado	mantém a conexão aberta entre pedidos
PoolConnection.Enabled	ligado (1.2 🚧)	reaproveita a conexão do mesmo servidor
ShareConnection	ligado (1.2 🚧)	clientes iguais dividem uma conexão (NetHTTP, OkHttp, QUIC)
HTTPVersion	rhvDefault	rhv2 pede HTTP/2 (HTTP/2)
MaxRedirects	3	quantos redirecionamentos seguir
SSL	o do motor	qual certificado aceitar (HTTPS no cliente)
UserAgent	RALClient <versão>	como o cliente se identifica

Eventos

Evento	Quando
OnResponse	a resposta de uma chamada com evento, quando não foi passado nenhum
OnBeforeExecute	antes de cada tentativa (1.1): acrescentar cabeçalho, cancelar sem rede
OnAfterExecute	depois de cada tentativa (1.1): log, tempo gasto
OnValidateServerCert	decidir se aceita o certificado do servidor

Saber por que falhou

Resposta.TransportError (na forma com evento) diz o tipo de falha, sem comparar texto:

Valor	Significa
rteNone	chegou uma resposta HTTP (até um 404 ou 500)
rteConnect	não conectou (servidor fora, DNS, firewall)
rteTimeout	conectou, mas não respondeu a tempo
rteCertificate	o certificado do servidor foi recusado
rteCancelled	OnBeforeExecute cancelou

Erros comuns

O que acontece	Causa	O que fazer
Engine X not found	a unit do motor não está no uses	acrescente-a
a tela trava durante o pedido	chamada sem ebMultiThread	passe ebMultiThread
Access violation depois do pedido	Resposta não foi liberada, ou foi liberada duas vezes, ou guardada do evento	na forma "esperar", Free uma vez; no evento, não guarde
o servidor recebe o corpo vazio	parâmetro criado com AddValue sem tipo	use AddBody/AddField
o corpo chega comprimido/ilegível	o servidor comprimiu num formato que o cliente não tem	RALCompressZLib no uses

Veja também

• HTTPS no cliente
• HTTP/2
• Android