TsgcOpenAPI_Client ist eine nicht-visuelle Komponente, die die wichtigsten Methoden und Eigenschaften kapselt, um HTTP-Anfragen aus einer OpenAPI-Spezifikation zu stellen.
Jede mit dem sgcOpenAPI-Parser erstellte OpenAPI-Schnittstelle hat 2 Methoden
Beispiel
Verwenden Sie die Abstractapi, um die Lokalisierung einer IP-Adresse abzurufen.
GetOpenAPIClient.Retrieve_the_location_of_an_IP_address('your api', '80.258.15.2');
auth2Code: Wird verwendet, um Authentifizierung und Autorisierung in den meisten Anwendungstypen durchzuführen, einschließlich Single-Page-Anwendungen, Webanwendungen und nativ installierten Anwendungen. Der Flow ermöglicht es Apps, access_tokens sicher zu erwerben, die zum Zugriff auf gesicherte Ressourcen verwendet werden können, sowie Refresh-Tokens, um zusätzliche access_tokens zu erhalten, und ID-Tokens für den angemeldeten Benutzer.
auth2ClientCredentials: Dieser Grant-Typ wird häufig für Server-zu-Server-Interaktionen verwendet, die im Hintergrund laufen müssen, ohne unmittelbare Interaktion mit einem Benutzer. Diese Arten von Anwendungen werden oft als Daemons oder Service-Konten bezeichnet.
Lesen Sie mehr über OAuth2.
Ermöglicht die Konfiguration, wie eine Verbindung zu sicheren SSL/TLS-Servern über das HTTP/1-Protokoll hergestellt wird
Die generierten Clients überprüfen das Zertifikat des Servers standardmäßig, frühere Versionen taten das nicht. Die Vertrauensstellung stammt aus den Standard-Verifizierungspfaden von OpenSSL. Setzen Sie daher auf einem Rechner, auf dem kein CA-Speicher konfiguriert ist, TLSOptions.RootCertFile auf die Datei mit den vertrauenswürdigen Root-Zertifikaten. Um sich mit einem selbstsignierten oder einem Test-Endpunkt zu verbinden, setzen Sie TLSOptions.VerifyCertificate := False.
ALPNProtocols: Liste der ALPN-Protokolle, die an den Server gesendet werden.
RootCertFile: Pfad zur Root-Zertifikatdatei.
CertFile: Pfad zur Zertifikatsdatei.
KeyFile: Pfad zur Zertifikatsschlüsseldatei.
Password: wenn das Zertifikat mit einem Passwort gesichert ist, setzen Sie es hier.
VerifyCertificate: wenn das Zertifikat überprüft werden muss, aktivieren Sie diese Eigenschaft. Der OpenAPI-Client aktiviert sie standardmäßig, setzen Sie sie auf False, um ein selbstsigniertes Zertifikat zu akzeptieren.
VerifyDepth: ist eine Integer-Eigenschaft, die die maximale Anzahl von Verknüpfungen darstellt, die zulässig sind, wenn die Überprüfung für das X.509-Zertifikat durchgeführt wird.
Version: Verwendet standardmäßig TLS 1.0; wenn der Server eine höhere TLS-Version erfordert, kann diese hier ausgewählt werden.
IOHandler: Wählen Sie aus, welche Bibliothek Sie für die Verbindung über TLS verwenden.
iohOpenSSL: verwendet die OpenSSL-Bibliothek und ist der Standard für Indy-Komponenten. Erfordert das Bereitstellen der OpenSSL-Bibliotheken für win32/win64.
iohSChannel: verwendet Secure Channel, ein von Microsoft für Windows implementiertes Sicherheitsprotokoll, das die Bereitstellung von OpenSSL-Bibliotheken nicht erfordert. Funktioniert nur unter Windows 32/64 Bit.
OpenSSL_Options: Konfiguration der OpenSSL-Bibliotheken.
APIVersion: ermöglicht die Definition, welche OpenSSL-API verwendet wird.
oslAPI_1_0: verwendet API 1.0 OpenSSL, es ist die neueste von Indy unterstützte
oslAPI_1_1: verwendet API-1.1-OpenSSL, erfordert unsere benutzerdefinierte Indy-Bibliothek und ermöglicht die Verwendung von OpenSSL-1.1.1-Bibliotheken (mit TLS-1.3-Unterstützung).
oslAPI_3_0: verwendet API 3.0 OpenSSL, erfordert unsere benutzerdefinierte Indy-Bibliothek und ermöglicht die Verwendung von OpenSSL-3.0.0-Bibliotheken (mit TLS-1.3-Unterstützung).
LibPath: hier können Sie konfigurieren, wo sich die openSSL-Bibliotheken befinden
oslpNone: dies ist der Standard, die OpenSSL-Bibliotheken sollten sich im selben Ordner befinden, in dem sich die Binärdatei befindet, oder in einem bekannten Pfad.
oslpDefaultFolder: legt automatisch den OpenSSL-Pfad fest, in dem sich die Bibliotheken für alle IDE-Personalities befinden sollten.
oslpCustomFolder: wenn dies die ausgewählte Option ist, definieren Sie den vollständigen Pfad in der Eigenschaft LibPathCustom.
LibPathCustom: wenn LibPath = oslpCustomFolder, definieren Sie hier den vollständigen Pfad, in dem sich die OpenSSL-Bibliotheken befinden.
UnixSymLinks: aktiviert oder deaktiviert das Laden von SymLinks unter Unix-Systemen (standardmäßig aktiviert, außer unter OSX64):
oslsSymLinksDefault: standardmäßig aktiviert, außer unter OSX64 (nach MacOS Monterey schlägt der Versuch fehl, die Bibliothek ohne Version zu laden.).
oslsSymLinksLoadFirst: SymLinks laden und vor dem Versuch, die Versionsbibliotheken zu laden, ausführen.
oslsSymLinksLoad: Lädt SymLinks, nachdem versucht wurde, die Versionsbibliotheken zu laden.
oslsSymLinksDontLoad: lädt die SymLinks nicht.
SChannel_Options: ermöglicht die Verwendung eines Zertifikats aus dem Windows-Zertifikatspeicher.
CertHash: ist der Zertifikats-Hash. Sie können den Zertifikats-Hash finden, indem Sie einen dir-Befehl in PowerShell ausführen.
CipherList: hier können Sie festlegen, welche Cipher verwendet werden (getrennt durch ":"). Beispiel: CALG_AES_256:CALG_AES_128
CertStoreName: der Speichername, in dem das Zertifikat abgelegt ist. Wählen Sie einen der folgenden aus:
scsnMY (der Standardwert)
scsnCA
scsnRoot
scsnTrust
CertStorePath: der Store-Pfad, unter dem das Zertifikat gespeichert ist. Wählen Sie einen der folgenden aus:
scspStoreCurrentUser (der Standard)
scspStoreLocalMachine
Verwenden Sie diese Eigenschaft, um die Verbindungen über einen Proxy zu konfigurieren.
Enabled: auf true setzen, um Proxy-Verbindungen zu aktivieren.
Host: Proxy-Serveradresse
Port: Proxy-Server-Port
UserName/Password: Authentifizierung zur Verbindung mit dem Proxy, nur falls erforderlich.
ProxyType: die folgenden Proxys werden unterstützt:
Wenn die Eigenschaft Log aktiviert ist, speichert sie Socket-Nachrichten in einer angegebenen Protokolldatei, was zum Debuggen nützlich ist.
Log: aktivieren Sie dies, wenn Sie die HTTP-Anfragen in einer Textdatei speichern möchten.
LogFileName: vollständiger Pfad zum Dateinamen.
Weitere Eigenschaften, die zur Anpassung des OpenAPI-Clients verwendet werden können:
EncodeBodyAsUTF8: wenn aktiviert, wird der Anfrage-Body als UTF-8 codiert (standardmäßig true). Ein JSON-Dokument ist gemäß RFC 8259 UTF-8, ein als ANSI codierter Body verstümmelt jedes Zeichen außerhalb des ASCII-Bereichs.
Die aus der Spezifikation generierten Klassen (DTOs) stellen die folgenden Eigenschaften bereit, um anzupassen, wie sie in JSON geschrieben werden:
JSONIgnoreEmptyStrings: standardmäßig ist der Wert False, ein Feld mit einer leeren Zeichenkette wird also als "field": "" geschrieben. Eine leere Zeichenkette ist ein Wert, und der Server kann sie nicht von einem Feld unterscheiden, das nie gesetzt wurde. Setzen Sie den Wert auf True, um die leeren Zeichenketten aus dem JSON wegzulassen, so wie es frühere Versionen gemacht haben.
JSONIgnoreNullValues: standardmäßig ist der Wert True, ein Null wird also nicht in das JSON geschrieben. Die Nullwerte werden ausschließlich über diese Eigenschaft gesteuert, sie ist unabhängig von JSONIgnoreEmptyStrings. Setzen Sie den Wert auf False, um ein explizites Null zu schreiben, was ein JSON Merge Patch (RFC 7386) benötigt, um ein Element zu löschen.
Das Ergebnis einer Anfrage wird in einem TsgcOpenAPIResponse-Objekt zurückgegeben.
ResponseStream: Stream, in den der Body der Antwort geschrieben wird, weisen Sie Ihren eigenen Stream zu, um einen Download direkt darin zu speichern.
OwnsResponseStream: ein vom Aufrufer zugewiesener Stream wird nicht mehr zusammen mit der Antwort freigegeben, der Aufrufer behält den Besitz. Setzen Sie den Wert auf True, um das vorherige Verhalten wiederherzustellen und die Antwort den Stream freigeben zu lassen.
Ein in der Spezifikation als in: cookie deklarierter Parameter wird unterstützt. Alle Cookie-Parameter einer Anfrage werden gemeinsam in einem einzigen Cookie-Header gesendet, wie es RFC 6265 verlangt.
Standardmäßig führt der OpenAPI-Client Anfragen synchron aus. Verwenden Sie die asynchrone API, um eine Anfrage in einem Hintergrundthread auszuführen und über Ereignisse benachrichtigt zu werden; das hält die Benutzeroberfläche reaktionsfähig und ermöglicht das Abbrechen der Anfrage.
HTTP_REQUEST_Async: führt die Anfrage in einem Worker-Thread aus. Der Client übernimmt den Besitz des Anfrageobjekts.
CancelAsync: bricht die laufende Anfrage ab.
SynchronizeEvents: Wenn True, werden die Ereignisse an den Hauptthread übergeben. Standardmäßig ist der Wert False, und die Ereignisse werden im Worker-Thread ausgelöst.
Das Ergebnis wird über die folgenden Ereignisse bereitgestellt:
OnResponse: Die Anfrage wurde abgeschlossen, die Antwort wird als Parameter übergeben.
OnError: Die Anfrage ist fehlgeschlagen, die Ausnahme wird als Parameter übergeben.
OnCancel: Die Anfrage wurde durch CancelAsync abgebrochen.
Der Client kann nicht innerhalb seines eigenen OnResponse-, OnError- oder OnCancel-Ereignisses freigegeben werden. Das Freigeben wartet auf den Worker-Thread, also genau auf den Thread, der den Handler ausführt, die Anwendung würde daher hängen bleiben. Stattdessen wird eine eindeutige Fehlermeldung ausgelöst, geben Sie den Client frei, sobald der Ereignishandler zurückgekehrt ist.
Nachfolgend die Liste der Ereignisse, die Sie bei Verwendung des OpenAPI-Clients behandeln können.
OnBeforeRequest
Dieses Ereignis wird aufgerufen, bevor die HTTP-Anfrage aufgerufen wird. Ermöglicht das Anpassen der Parameternamen, Header, Sicherheit... Unten finden Sie ein Beispiel, wie der Name einiger Parameter ersetzt wird.
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
Dieses Ereignis wird aufgerufen, wenn eine Datei hochgeladen wird; Sie können dieses Ereignis verwenden, um den Fortschritt des Uploads zu verfolgen.
OnDownload
Dieses Ereignis wird aufgerufen, wenn eine Datei heruntergeladen wird; Sie können dieses Ereignis verwenden, um den Fortschritt des Downloads zu verfolgen.
OnSSLVerifyPeer
Wenn die Zertifikatsprüfung aktiviert ist, können Sie in diesem Ereignis überprüfen und entscheiden, ob das Server-Zertifikat akzeptiert werden soll.
OnSSLGetHandler
Dieses Ereignis wird ausgelöst, bevor der SSL-Handler erstellt wird; Sie können hier Ihren eigenen SSL-Handler erstellen (muss von TIdServerIOHandlerSSLBase oder TIdIOHandlerSSLBase abgeleitet sein) und die benötigten Eigenschaften setzen
OnSSLAfterCreateHandler
Wenn kein benutzerdefiniertes SSL-Objekt erstellt wurde, wird standardmäßig eines mit dem OpenSSL-Handler erstellt. Sie können auf die Eigenschaften des SSL-Handlers zugreifen und sie bei Bedarf ändern