HTTP/1

TsgcHTTP1Client jest komponentem niewiizualnym, dziedziczącym po komponencie TIdHTTP indy, i dodającym kilka nowych właściwości.

Ten komponent znajduje się w jednostce sgcHTTP.

TLSOptions

Umożliwia konfigurowanie sposobu łączenia się z bezpiecznymi serwerami SSL/TLS przy użyciu protokołu HTTP/1.

 

ALPNProtocols: lista protokołów ALPN, które zostaną wysłane do serwera.

RootCertFile: ścieżka do pliku certyfikatu głównego.

CertFile: ścieżka do pliku certyfikatu.

KeyFile: ścieżka do pliku klucza certyfikatu.

Password: jeśli certyfikat jest zabezpieczony hasłem, należy je tu podać.

VerifyCertificate: jeśli certyfikat musi być weryfikowany, należy włączyć tę właściwość. Do dostosowania weryfikacji SSL należy użyć zdarzenia OnSSLVerifyPeer.

VerifyDepth: właściwość całkowitoliczbowa określająca maksymalną liczbę ogniw dozwolonych podczas weryfikacji certyfikatu X.509.

Wersja: domyślnie używa TLS 1.0. Jeśli serwer wymaga wyższej wersji TLS, można ją tutaj wybrać.

Preset: stosuje zestaw bezpiecznych ustawień domyślnych w jednym przypisaniu. Przy tlspCustom (wartość domyślna) każda opcja zachowuje wartość skonfigurowaną ręcznie. Ustawienie tlspSecureDefaults włącza VerifyCertificate, podnosi Version do co najmniej TLS 1.2 (gdy skonfigurowana była niższa lub nieokreślona wersja) i włącza weryfikację nazwy hosta certyfikatu serwera.

Proxy: w tej sekcji można określić, czy połączenie ma odbywać się przez serwer proxy. Obsługiwane są następujące serwery proxy:

pxyHTTP: Serwer proxy HTTP.

pxySocks4: Serwer proxy SOCKS4.

pxySocks4A: Serwer proxy SOCKS4A.

pxySocks5: Serwer proxy SOCKS5.

IOHandler: wybierz bibliotekę, której chcesz użyć do połączenia przez TLS.

iohOpenSSL: korzysta z biblioteki OpenSSL i jest domyślnym wyborem dla komponentów Indy. Wymaga wdrożenia bibliotek OpenSSL dla win32/win64.

iohSChannel: używa Secure Channel — protokołu bezpieczeństwa zaimplementowanego przez Microsoft dla systemu Windows. Nie wymaga wdrożenia bibliotek OpenSSL. Działa wyłącznie w systemie Windows 32/64-bit.

OpenSSL_Options: konfiguracja bibliotek OpenSSL.

APIVersion: pozwala określić, które API OpenSSL będzie używane.

oslAPI_1_0: używa API 1.0 OpenSSL; jest to najnowsza wersja obsługiwana przez Indy

oslAPI_1_1: używa interfejsu API 1.1 OpenSSL, wymaga niestandardowej biblioteki Indy i umożliwia korzystanie z bibliotek OpenSSL 1.1.1 (z obsługą TLS 1.3).

oslAPI_3_0: korzysta z API OpenSSL 3.0, wymaga naszej niestandardowej biblioteki Indy i umożliwia używanie bibliotek OpenSSL 3.0.0 (z obsługą TLS 1.3).

LibPath: tutaj można skonfigurować lokalizację bibliotek OpenSSL

oslpNone: wartość domyślna. Biblioteki OpenSSL powinny znajdować się w tym samym folderze co plik binarny lub w znanych ścieżkach systemowych.

oslpDefaultFolder: automatycznie ustawia ścieżkę OpenSSL, w której biblioteki powinny się znajdować dla wszystkich rodzajów projektów IDE.

oslpCustomFolder: jeśli ta opcja jest wybrana, należy zdefiniować pełną ścieżkę we właściwości LibPathCustom.

LibPathCustom: gdy LibPath = oslpCustomFolder, należy tu podać pełną ścieżkę do katalogu, w którym znajdują się biblioteki OpenSSL.

UnixSymLinks: włącz lub wyłącz ładowanie dowiązań symbolicznych w systemach Unix (domyślnie włączone, z wyjątkiem OSX64):

oslsSymLinksDefault: domyślnie dowiązania symboliczne są włączone, z wyjątkiem OSX64 (macOS Monterey i nowsze wersje nie działają przy próbie załadowania biblioteki bez numeru wersji).

oslsSymLinksLoadFirst: wczytaj najpierw dowiązania symboliczne, przed próbą załadowania bibliotek z numerem wersji.

oslsSymLinksLoad: ładuje dowiązania symboliczne po próbie załadowania bibliotek z wersją.

oslsSymLinksDontLoad: nie ładuj dowiązań symbolicznych.

MinVersion: tutaj należy ustawić minimalną wersję, której klient użyje do połączenia z bezpiecznym serwerem. Domyślnie wartość wynosi tlsUndefined, co oznacza, że minimalna wersja jest taka sama jak ustawiona we właściwości Version. Przykład: aby klient łączył się wyłącznie przy użyciu TLS 1.2 lub TLS 1.3, należy ustawić następujące wartości.

 

SSLOptions.Version := tls1_3;

SSLOptions.OpenSSL_Options.MinVersion := tls1_2;

X509Checks: użyj tej właściwości, aby włączyć dodatkowe weryfikacje certyfikatu X509:

Mode: wybierz, które opcje będą walidowane

oslx509chHostName: weryfikuje certyfikat nazwy hosta.

oslx509chIPAddress: weryfikuje adres IP certyfikatu.

HostName: ustaw nazwę hosta, jeśli różni się od żądania.

IPAddress: ustawia adres IP, jeśli różni się od adresu z żądania.

 

SChannel_Options: umożliwia korzystanie z certyfikatu z magazynu certyfikatów systemu Windows.

CertHash: to skrót certyfikatu. Skrót certyfikatu można znaleźć, uruchamiając polecenie dir w programie PowerShell.

CipherList: w tym miejscu można określić, które szyfry będą używane (oddzielone znakiem ":"). Przykład: CALG_AES_256:CALG_AES_128

CertStoreName: nazwa magazynu, w którym przechowywany jest certyfikat. Należy wybrać jedną z następujących wartości:

scsnMY (wartość domyślna)

scsnCA

scsnRoot

scsnTrust

CertStorePath: ścieżka magazynu, w którym przechowywany jest certyfikat. Należy wybrać jedną z następujących opcji:

scspStoreCurrentUser (domyślne)

scspStoreLocalMachine

 

Dziennik

Gdy właściwość Log jest włączona, zapisuje komunikaty gniazda do wskazanego pliku dziennika, co jest przydatne podczas debugowania.

 

LogOptions.FileName: pełna ścieżka do pliku.

 

Uwierzytelnianie

Umożliwia uwierzytelnianie przy użyciu OAuth2 lub JWT.

 

 

RetryOptions

Automatycznie ponawia nieudane żądania HTTP, używając wykładniczego backoffu z opcjonalnym jitterem. Ponawianie jest domyślnie wyłączone, więc zachowanie pozostaje niezmienione, dopóki Enabled nie zostanie ustawione na true. Żądanie jest ponawiane, gdy kod stanu odpowiedzi znajduje się w StatusCodes lub gdy wystąpi przejściowy błąd sieci (zamknięte połączenie, błąd gniazda, przekroczenie limitu czasu połączenia lub odczytu).

Enabled: włącza automatyczne ponawianie nieudanych żądań. Domyślnie false.

MaxRetries: maksymalna liczba ponownych prób po żądaniu początkowym. Domyślnie 3.

InitialInterval: opóźnienie w milisekundach przed pierwszą ponowną próbą. Domyślnie 500.

MaxInterval: maksymalne opóźnienie w milisekundach między ponownymi próbami. Domyślnie 30000.

Multiplier: współczynnik stosowany do opóźnienia po każdej próbie. Domyślnie 2.0, co podwaja opóźnienie przy każdej ponownej próbie: 500, 1000, 2000...

Jitter: losowy współczynnik od 0 do 1 stosowany do każdego opóźnienia (0.2 zmienia każde opóźnienie o maksymalnie 20%), co zapobiega ponawianiu prób przez wielu klientów dokładnie w tym samym momencie. Domyślnie 0.2.

HonorRetryAfter: gdy serwer odpowiada nagłówkiem Retry-After (jako sekundy lub jako data HTTP, zwykle z odpowiedzią 429 lub 503), klient czeka przez czas wskazany przez serwer zamiast obliczonego opóźnienia backoffu. Domyślnie true.

StatusCodes: rozdzielana przecinkami lista kodów stanu HTTP, które wyzwalają ponowną próbę. Domyślnie "429,502,503,504".

Przykład: ponawianie próby maksymalnie 5 razy, zaczynając od 1 sekundy między próbami.

oHTTP := TsgcHTTP1Client.Create(nil);
oHTTP.RetryOptions.Enabled := True;
oHTTP.RetryOptions.MaxRetries := 5;
oHTTP.RetryOptions.InitialInterval := 1000;
ShowMessage(oHTTP.Get('https://www.esegece.com'));

Klienci dostawców AI (OpenAI, Anthropic, Gemini i pozostałe klienty API LLM) używają tego samego mechanizmu ponawiania poprzez właściwość RetryOptions w swoich Options.

Żądania asynchroniczne

Domyślnie HTTP1Client używa żądań blokujących, więc po wywołaniu metody żądania HTTP klient czeka na odpowiedź od serwera. Alternatywnie można użyć metod asynchronicznych do wykonywania żądań HTTP w wątku pomocniczym, co pozwala uniknąć blokowania wątku wywołującego. Zaimplementowane są następujące metody asynchroniczne:

 

• GetAsync
• PostAsync
• PutAsync
• OptionsAsync
• DeleteAsync

 

Po wywołaniu tych metod kod nie czeka na odpowiedź, lecz przechodzi do kolejnej linii, a odpowiedź może być obsługiwana za pomocą zdarzenia OnAsyncResponse.

 

procedure OnAsyncResultEvent(Sender: TObject; const aRequest:
    TsgcHTTPAsyncRequest; const aResponse: TIdHTTPResponse);

Jeśli podczas przetwarzania żądania asynchronicznego wystąpi błąd, wyjątek zostanie zgłoszony w zdarzeniu OnAsyncException.

 

Futures

W Delphi 2010 i nowszych klient implementuje również asynchroniczne żądania w stylu future, które nie wymagają żadnej procedury obsługi zdarzeń:

• GetFuture
• PostFuture

function GetFuture(const AURL: string): IsgcFuture<string>;
function PostFuture(const AURL: string; aData: TStream): IsgcFuture<string>;

Żądanie jest wykonywane w wątku w tle, a zwrócony future rozwiązuje się do treści odpowiedzi: należy wywołać Await, aby zablokować do nadejścia odpowiedzi, ThenProc, aby przetworzyć ją w kontynuacji, oraz OnError, aby obsłużyć błędy. Wywołanie Cancel przerywa bazowe żądanie HTTP, zamiast pozwolić na jego wykonanie do końca.

oHTTP := TsgcHTTP1Client.Create(nil);
oHTTP.GetFuture('https://www.esegece.com')
  .ThenProc(procedure(const aBody: string)
    begin
      Log(aBody);
    end)
  .OnError(procedure(E: Exception)
    begin
      Log(E.Message);
    end);

Przykłady

Wysyła żądanie metodą GET do serwera HTTPs z użyciem TLS 1.2

oHTTP := TsgcHTTP1Client.Create(nil);
Try
  oHTTP.TLSOptions.Version := tls1_2;
  ShowMessage(oHTTP.Get('https://www.google.es'));
Finally
  oHTTP.Free;
End;

Wysłanie żądania metodą GET do serwera HTTPS z użyciem openSSL 1.1 i TLS 1.3

oHTTP := TsgcHTTP1Client.Create(nil);
Try
  oHTTP.TLSOptions.OpenSSL_Options.APIVersion := oslAPI_1_1;
  oHTTP.TLSOptions.Version := tls1_3;
  ShowMessage(oHTTP.Get('https://www.google.es'));
Finally
  oHTTP.Free;
End;

Należy zażądać metody Asynchronous POST i odczytać odpowiedź przy użyciu zdarzenia OnAsyncResultEvent.

 

procedure OnAsyncExceptionEvent(Sender: TObject; const aThread:
    TsgcThread; const E: Exception);
begin
  Log(E.Message);
end;
procedure OnAsyncResultEvent(Sender: TObject; const aRequest:
    TsgcHTTPAsyncRequest; const aResponse: TIdHTTPResponse);
begin
  if aResponse.ResponseCode = 200 then
    Log('ok', aRequest.Response)
  else 
    Log('error', aRequest.Response);
end;
oHTTP := TsgcHTTP1Client.Create(nil);
oHTTP.OnAsyncResult := OnAsyncResultEvent;
oHTTP.OnAsyncException := OnAsyncResultEvent;
oRequest := TStringStream.Create('body');
oResponse := TStringStream.Create('');
oHTTP.PostAsync('https://localhost/test', oRequest, oResponse);

 

Wysyłanie żądania GET do serwera HTTPs przy użyciu SChannel dla Windows.

oHTTP := TsgcHTTP1Client.Create(nil);
Try
  oHTTP.TLSOptions.IOHandler := iohSChannel;
  oHTTP.TLSOptions.Version := tls1_2;
  ShowMessage(oHTTP.Get('https://www.google.es'));
Finally
  oHTTP.Free;
End;

Żądanie metody SSE w celu pobierania zdarzeń danych

 

oHTTP := TsgcHTTP1Client.Create(nil);
oHTTP.OnSSEMessage := OnSSEMessageEvent;
oHTTP.GetSSE('https://www.yoursite.com/sse');
 
procedure OnSSEMessageEvent(Sender: TObject; const aMessage: string; var Cancel: Boolean);
begin
  ShowMessage(aMessage);
end;

 

Zdarzenia

OnSSEMessage

 

Zdarzenie jest wywoływane po odebraniu nowej wiadomości SSE.

 

OnSSLVerifyPeer

 

Jeśli weryfikacja certyfikatu jest włączona, w tym zdarzeniu można zweryfikować certyfikat serwera i zdecydować, czy go zaakceptować.

 

OnSSLGetHandler

 

To zdarzenie jest wywoływane przed utworzeniem procedury obsługi SSL. Można tu utworzyć własną procedurę obsługi SSL (musi ona dziedziczyć po TIdServerIOHandlerSSLBase lub TIdIOHandlerSSLBase) i ustawić wymagane właściwości.

 

OnSSLAfterCreateHandler

 

Jeśli nie utworzono niestandardowego obiektu SSL, zostanie on domyślnie utworzony przy użyciu procedury obsługi OpenSSL. Można uzyskać dostęp do właściwości procedury obsługi SSL i modyfikować je w razie potrzeby.

 

OnAsyncResult

 

Zdarzenie jest wywoływane po otrzymaniu odpowiedzi na metodę asynchroniczną (przy użyciu metod GetAsync, PutAsync...). Należy użyć parametru Response, aby poznać wynik żądania.

 

OnAsyncException

 

Jeśli podczas przetwarzania żądania asynchronicznego wystąpi błąd, to zdarzenie jest wywoływane z podniesionym wyjątkiem.