TsgcOpenAPI_Client jest komponentem niewizualnym, który hermetyzuje główne metody i właściwości do wykonywania żądań HTTP na podstawie specyfikacji OpenAPI.
Każdy interfejs OpenAPI utworzony za pomocą parsera sgcOpenAPI posiada 2 metody
Przykład
Użyj usługi Abstractapi, aby pobrać lokalizację adresu IP.
GetOpenAPIClient.Retrieve_the_location_of_an_IP_address('your api', '80.258.15.2');
auth2Code: Stosowany do uwierzytelniania i autoryzacji w większości typów aplikacji, w tym w aplikacjach jednostronicowych, aplikacjach webowych i aplikacjach natywnych. Przepływ umożliwia aplikacjom bezpieczne pozyskiwanie tokenów access_token, które mogą być używane do uzyskiwania dostępu do chronionych zasobów, a także tokenów odświeżania do pozyskiwania kolejnych tokenów access_token oraz tokenów ID dla zalogowanego użytkownika.
auth2ClientCredentials: Ten typ przyznania dostępu jest powszechnie stosowany w interakcjach serwer-serwer, które muszą działać w tle bez bezpośredniej interakcji z użytkownikiem. Aplikacje tego typu są często określane jako procesy demoniczne lub konta usług.
Więcej informacji o OAuth2.
Umożliwia konfigurację sposobu łączenia z bezpiecznymi serwerami SSL/TLS przy użyciu protokołu HTTP/1
Generowani klienci domyślnie weryfikują certyfikat serwera, wcześniejsze wersje tego nie robiły. Zaufanie pochodzi z domyślnych ścieżek weryfikacji OpenSSL, więc na komputerze, na którym nie skonfigurowano magazynu CA, ustaw TLSOptions.RootCertFile na plik z zaufanymi certyfikatami głównymi. Aby połączyć się z punktem końcowym z certyfikatem samopodpisanym lub testowym, ustaw TLSOptions.VerifyCertificate := False.
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 tutaj podać.
VerifyCertificate: jeśli certyfikat musi być weryfikowany, należy włączyć tę właściwość. Klient OpenAPI włącza ją domyślnie, ustaw ją na False, aby zaakceptować certyfikat samopodpisany.
VerifyDepth: właściwość całkowitoliczbowa określająca maksymalną liczbę ogniw dozwolonych podczas weryfikacji certyfikatu X.509.
Version: domyślnie używa TLS 1.0; jeśli serwer wymaga wyższej wersji TLS, można ją tutaj wybrać.
IOHandler: wybierz bibliotekę, która będzie używana do połączenia z wykorzystaniem TLS.
iohOpenSSL: korzysta z biblioteki OpenSSL i jest domyślną opcją dla komponentów Indy. Wymaga wdrożenia bibliotek OpenSSL dla win32/win64.
iohSChannel: używa kanału Secure Channel — protokołu bezpieczeństwa zaimplementowanego przez Microsoft dla systemu Windows; nie wymaga wdrażania bibliotek openssl. Działa wyłącznie w systemie Windows 32/64 bity.
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: jest to wartość domyślna; biblioteki OpenSSL powinny znajdować się w tym samym folderze co plik binarny lub w znanej ścieżce.
oslpDefaultFolder: automatycznie ustawia ścieżkę openSSL, w której powinny znajdować się biblioteki dla wszystkich osobowości 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 podać pełną ścieżkę do folderu, 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 jest włączone, z wyjątkiem platformy OSX64 (po MacOS Monterey próba załadowania biblioteki bez wersji kończy się błędem).
oslsSymLinksLoadFirst: Załaduj dowiązania symboliczne przed próbą załadowania bibliotek wersji.
oslsSymLinksLoad: Ładuj dowiązania symboliczne po próbie załadowania bibliotek wersji.
oslsSymLinksDontLoad: nie ładuj dowiązań symbolicznych.
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 poniższych opcji:
scsnMY (wartość domyślna)
scsnCA
scsnRoot
scsnTrust
CertStorePath: ścieżka magazynu, w którym przechowywany jest certyfikat. Wybierz jedną z poniższych opcji:
scspStoreCurrentUser (domyślne)
scspStoreLocalMachine
Ta właściwość służy do konfiguracji połączeń przez serwer proxy.
Włączone: ustaw wartość true, aby włączyć połączenia przez serwer proxy.
Host: Adres serwera proxy
Port: port serwera proxy
UserName/Password: Uwierzytelnianie do połączenia z serwerem proxy, wyłącznie jeśli jest wymagane.
ProxyType: obsługiwane są następujące typy proxy:
Jeśli właściwość Log jest włączona, komunikaty gniazda są zapisywane do określonego pliku dziennika, co jest przydatne podczas debugowania.
Log: włącz, jeśli chcesz zapisywać żądania HTTP do pliku tekstowego.
LogFileName: pełna ścieżka do pliku.
Inne właściwości, które można wykorzystać do dostosowania klienta OpenAPI:
EncodeBodyAsUTF8: jeśli włączone, treść żądania jest kodowana jako UTF-8 (domyślnie true). Dokument JSON jest w UTF-8 zgodnie z RFC 8259, treść zakodowana jako ANSI zniekształca każdy znak spoza zakresu ASCII.
Klasy (DTO) generowane na podstawie specyfikacji udostępniają następujące właściwości pozwalające dostosować sposób ich zapisu do JSON:
JSONIgnoreEmptyStrings: domyślnie ma wartość False, więc pole zawierające pusty ciąg jest zapisywane jako "field": "". Pusty ciąg jest wartością i serwer nie odróżni go od pola, które nigdy nie zostało ustawione. Ustaw na True, aby pominąć puste ciągi w JSON, tak jak robiły to wcześniejsze wersje.
JSONIgnoreNullValues: domyślnie ma wartość True, więc wartość null nie jest zapisywana do JSON. Wartości null są sterowane wyłącznie tą właściwością, niezależnie od JSONIgnoreEmptyStrings. Ustaw na False, aby zapisać jawną wartość null, czego wymaga JSON Merge Patch (RFC 7386) do usunięcia składowej.
Wynik żądania jest zwracany w obiekcie TsgcOpenAPIResponse.
ResponseStream: strumień, do którego zapisywana jest treść odpowiedzi, przypisz własny strumień, aby zapisać pobierane dane bezpośrednio do niego.
OwnsResponseStream: strumień przypisany przez wywołującego nie jest już niszczony wraz z odpowiedzią, wywołujący zachowuje jego własność. Ustaw na True, aby przywrócić poprzednie zachowanie i pozwolić odpowiedzi zwolnić strumień.
Parametr zadeklarowany w specyfikacji jako in: cookie jest obsługiwany. Wszystkie parametry cookie żądania są wysyłane razem w jednym nagłówku Cookie, zgodnie z wymaganiem RFC 6265.
Domyślnie klient OpenAPI wykonuje żądania synchronicznie. Użyj API asynchronicznego, aby uruchomić żądanie w wątku działającym w tle i otrzymywać powiadomienia poprzez zdarzenia, co utrzymuje responsywność interfejsu użytkownika i umożliwia anulowanie żądania.
HTTP_REQUEST_Async: uruchamia żądanie w wątku roboczym. Klient przejmuje odpowiedzialność za obiekt żądania.
CancelAsync: anuluje trwające żądanie.
SynchronizeEvents: gdy True, zdarzenia są przekazywane do wątku głównego. Domyślnie ma wartość False, a zdarzenia są wywoływane w wątku roboczym.
Wynik jest dostarczany poprzez następujące zdarzenia:
OnResponse: żądanie zostało zakończone, odpowiedź jest przekazywana jako parametr.
OnError: żądanie zakończyło się niepowodzeniem, wyjątek jest przekazywany jako parametr.
OnCancel: żądanie zostało anulowane przez CancelAsync.
Klienta nie można zwolnić z wnętrza jego własnej procedury obsługi zdarzenia OnResponse, OnError lub OnCancel. Niszczenie go czeka na wątek roboczy, czyli dokładnie ten wątek, w którym działa procedura obsługi, więc aplikacja zawiesiłaby się. Zamiast tego zgłaszany jest czytelny błąd, zwolnij klienta po zakończeniu procedury obsługi zdarzenia.
Poniżej znajduje się lista zdarzeń, które można obsługiwać podczas korzystania z klienta OpenAPI.
OnBeforeRequest
Zdarzenie jest wywoływane przed wysłaniem żądania HTTP. Umożliwia dostosowanie nazw parametrów, nagłówków, zabezpieczeń itp. Poniżej znajduje się przykład pokazujący, jak zastąpić nazwy niektórych parametrów.
procedure OnBeforeRequestEvent(Sender: TObject; const aRequest: TsgcOpenAPIRequest);
var
i: Integer;
oParameter: TsgcOpenAPIParameter;
begin
for i := 0 to aRequest.Parameters.Count - 1 do
begin
oParameter := aRequest.Parameters[i];
if oParameter._Name = 'meta-modified-from' then
oParameter._name := 'eventDateTime-from';
if oParameter._Name = 'meta-modified-to' then
oParameter._name := 'eventDateTime-to';
end;
end;
OnUpload
To zdarzenie jest wywoływane po przesłaniu pliku; można je wykorzystać do śledzenia postępu przesyłania.
OnDownload
Zdarzenie to jest wywoływane po pobraniu pliku; można go używać do śledzenia postępu pobierania.
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 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.