TsgcOpenAPI_Client est un composant non visuel qui encapsule les principales méthodes et propriétés pour effectuer des requêtes HTTP à partir d'une spécification OpenAPI.
Chaque interface OpenAPI créée avec sgcOpenAPI Parser dispose de 2 méthodes
Exemple
Utilisez l'API Abstractapi pour récupérer la localisation d'une adresse IP.
GetOpenAPIClient.Retrieve_the_location_of_an_IP_address('your api', '80.258.15.2');
auth2Code : Utilisé pour effectuer l'authentification et l'autorisation dans la majorité des types d'applications, y compris les applications à page unique, les applications web et les applications installées nativement. Le flux permet aux applications d'acquérir en toute sécurité des access_tokens pouvant être utilisés pour accéder aux ressources sécurisées, ainsi que des jetons d'actualisation pour obtenir des access_tokens supplémentaires, et des jetons d'identifiant pour l'utilisateur connecté.
auth2ClientCredentials : Ce type de subvention est couramment utilisé pour les interactions serveur à serveur qui doivent s'exécuter en arrière-plan, sans interaction immédiate avec un utilisateur. Ces types d'applications sont souvent appelés démons ou comptes de service.
En savoir plus sur OAuth2.
Permet de configurer comment se connecter à des serveurs SSL/TLS sécurisés en utilisant le protocole HTTP/1
Les clients générés vérifient le certificat du serveur par défaut, ce qui n'était pas le cas dans les versions antérieures. La confiance provient des chemins de vérification par défaut d'OpenSSL, donc sur une machine où aucun magasin d'autorités de certification n'est configuré, définissez TLSOptions.RootCertFile avec le fichier contenant les certificats racine de confiance. Pour vous connecter à un point de terminaison auto-signé ou de test, définissez TLSOptions.VerifyCertificate := False.
ALPNProtocols : liste des protocoles ALPN qui seront envoyés au serveur.
RootCertFile : chemin vers le fichier de certificat racine.
CertFile : chemin vers le fichier de certificat.
KeyFile : chemin vers le fichier de clé du certificat.
Password : si le certificat est protégé par un mot de passe, définissez-le ici.
VerifyCertificate : si le certificat doit être vérifié, activez cette propriété. Le client OpenAPI l'active par défaut, définissez-la sur False pour accepter un certificat auto-signé.
VerifyDepth : est une propriété Integer représentant le nombre maximum de liens autorisés lors de la vérification du certificat X.509.
Version : par défaut utilise TLS 1.0 ; si le serveur nécessite une version TLS supérieure, elle peut être sélectionnée ici.
IOHandler : sélectionnez la bibliothèque que vous utiliserez pour la connexion TLS.
iohOpenSSL: utilise la bibliothèque OpenSSL et est la valeur par défaut pour les composants Indy. Nécessite le déploiement des bibliothèques openssl pour win32/win64.
iohSChannel : utilise Secure Channel qui est un protocole de sécurité implémenté par Microsoft pour Windows, ne nécessite pas de déployer des bibliothèques openssl. Fonctionne uniquement en Windows 32/64 bits.
OpenSSL_Options : configuration des bibliothèques openSSL.
APIVersion : permet de définir quelle API OpenSSL sera utilisée.
oslAPI_1_0 : utilise l'API 1.0 OpenSSL, la dernière version prise en charge par Indy
oslAPI_1_1 : utilise l'API 1.1 OpenSSL, nécessite notre bibliothèque Indy personnalisée et permet d'utiliser les bibliothèques OpenSSL 1.1.1 (avec prise en charge de TLS 1.3).
oslAPI_3_0 : utilise l'API OpenSSL 3.0, nécessite notre bibliothèque Indy personnalisée et permet d'utiliser les bibliothèques OpenSSL 3.0.0 (avec prise en charge de TLS 1.3).
LibPath : ici vous pouvez configurer l'emplacement des bibliothèques openSSL
oslpNone : c'est la valeur par défaut ; les bibliothèques OpenSSL doivent se trouver dans le même dossier que le binaire ou dans un chemin connu.
oslpDefaultFolder : définit automatiquement le chemin openSSL où les bibliothèques doivent être situées pour toutes les personnalités de l'IDE.
oslpCustomFolder : si cette option est sélectionnée, définissez le chemin complet dans la propriété LibPathCustom.
LibPathCustom : lorsque LibPath = oslpCustomFolder, définissez ici le chemin complet où se trouvent les bibliothèques openSSL.
UnixSymLinks : activer ou désactiver le chargement des liens symboliques sous les systèmes Unix (activé par défaut, sauf sous OSX64) :
oslsSymLinksDefault : activés par défaut sauf sous OSX64 (après MacOS Monterey, le chargement de la bibliothèque sans version échoue.).
oslsSymLinksLoadFirst : Charger d'abord les liens symboliques avant de tenter de charger les bibliothèques de version.
oslsSymLinksLoad : Charger les liens symboliques après avoir tenté de charger les bibliothèques de version.
oslsSymLinksDontLoad : ne pas charger les SymLinks.
SChannel_Options : vous permet d'utiliser un certificat depuis le magasin de certificats Windows.
CertHash : il s'agit du hachage du certificat. Vous pouvez trouver le hachage du certificat en exécutant une commande dir dans PowerShell.
CipherList : vous pouvez définir ici les chiffrements à utiliser (séparés par ":"). Exemple : CALG_AES_256:CALG_AES_128
CertStoreName : le nom du magasin où le certificat est stocké. Sélectionnez l'un des éléments suivants :
scsnMY (la valeur par défaut)
scsnCA
scsnRoot
scsnTrust
CertStorePath : le chemin du magasin où est stocké le certificat. Sélectionnez l'une des valeurs ci-dessous :
scspStoreCurrentUser (valeur par défaut)
scspStoreLocalMachine
Utilisez cette propriété pour configurer les connexions via un proxy.
Enabled : définir sur true pour activer les connexions proxy.
Host : adresse du serveur proxy
Port : Port du serveur proxy
UserName/Password : Authentification pour se connecter au proxy, uniquement si requise.
ProxyType : les proxys suivants sont pris en charge :
Si la propriété Log est activée, elle enregistre les messages socket dans un fichier journal spécifié, utile pour le débogage.
Log : activez si vous souhaitez sauvegarder les requêtes HTTP dans un fichier texte.
LogFileName: chemin complet vers le fichier journal.
Autres propriétés pouvant être utilisées pour personnaliser le client OpenAPI :
EncodeBodyAsUTF8 : si activé, le corps de la requête est encodé en UTF-8 (par défaut true). Un document JSON est en UTF-8 selon la RFC 8259, un corps encodé en ANSI déforme tous les caractères hors de la plage ASCII.
Les classes (DTO) générées à partir de la spécification exposent les propriétés suivantes pour personnaliser leur écriture en JSON :
JSONIgnoreEmptyStrings : par défaut, la valeur est False, donc un champ contenant une chaîne vide est écrit sous la forme "field": "". Une chaîne vide est une valeur et le serveur ne peut pas la distinguer d'un champ qui n'a jamais été défini. Définissez-la sur True pour laisser les chaînes vides hors du JSON, ce que faisaient les versions antérieures.
JSONIgnoreNullValues : par défaut, la valeur est True, donc un null n'est pas écrit dans le JSON. Les valeurs null sont contrôlées par cette seule propriété, elle est indépendante de JSONIgnoreEmptyStrings. Définissez-la sur False pour écrire un null explicite, ce dont un JSON Merge Patch (RFC 7386) a besoin pour supprimer un membre.
Le résultat d'une requête est renvoyé dans un objet TsgcOpenAPIResponse.
ResponseStream : flux dans lequel le corps de la réponse est écrit, affectez votre propre flux pour y enregistrer directement un téléchargement.
OwnsResponseStream : un flux affecté par l'appelant n'est plus détruit avec la réponse, l'appelant en conserve la propriété. Définissez-la sur True pour rétablir le comportement précédent et laisser la réponse libérer le flux.
Un paramètre déclaré avec in: cookie dans la spécification est pris en charge. Tous les paramètres de cookie d'une requête sont envoyés ensemble dans un seul en-tête Cookie, comme l'exige la RFC 6265.
Par défaut, le client OpenAPI exécute les requêtes de manière synchrone. Utilisez l'API asynchrone pour exécuter une requête sur un thread d'arrière-plan et être notifié via des événements, ce qui maintient l'interface utilisateur réactive et permet d'annuler la requête.
HTTP_REQUEST_Async : exécute la requête sur un thread de travail. Le client devient propriétaire de l'objet de requête.
CancelAsync : annule la requête en cours.
SynchronizeEvents : lorsque True, les événements sont transférés vers le thread principal. Par défaut, la valeur est False et les événements se déclenchent dans le thread de travail.
Le résultat est transmis via les événements suivants :
OnResponse : la requête s'est terminée, la réponse est passée en paramètre.
OnError : la requête a échoué, l'exception est passée en paramètre.
OnCancel : la requête a été annulée par CancelAsync.
Le client ne peut pas être libéré depuis son propre gestionnaire d'événement OnResponse, OnError ou OnCancel. Sa destruction attend le thread de travail, qui est précisément le thread exécutant le gestionnaire, l'application se bloquerait donc. Une erreur explicite est levée à la place, libérez le client une fois que le gestionnaire d'événement a rendu la main.
Trouvez ci-dessous la liste des événements que vous pouvez gérer lors de l'utilisation du client OpenAPI.
OnBeforeRequest
Cet événement est appelé avant l'exécution de la requête HTTP. Il permet de personnaliser les noms de paramètres, les en-têtes, la sécurité... Voici un exemple illustrant comment remplacer le nom de certains paramètres.
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
Cet événement est appelé lorsqu'un fichier est téléchargé ; vous pouvez l'utiliser pour connaître la progression du téléchargement.
OnDownload
Cet événement est appelé lorsqu'un fichier est téléchargé ; vous pouvez l'utiliser pour connaître la progression du téléchargement.
OnSSLVerifyPeer
Si la vérification du certificat est activée, dans cet événement vous pouvez vérifier et décider d'accepter ou non le certificat du serveur.
OnSSLGetHandler
Cet événement est déclenché avant la création du gestionnaire SSL, vous pouvez créer ici votre propre gestionnaire SSL (doit hériter de TIdServerIOHandlerSSLBase ou TIdIOHandlerSSLBase) et définir les propriétés nécessaires
OnSSLAfterCreateHandler
Si aucun objet SSL personnalisé n'a été créé, il est créé par défaut à l'aide du gestionnaire OpenSSL. Vous pouvez accéder aux propriétés du gestionnaire SSL et les modifier si nécessaire.