TsgcOpenAPI_Client es un componente no visual que encapsula los principales métodos y propiedades para realizar solicitudes HTTP a partir de una especificación OpenAPI.
Cada interfaz OpenAPI creada con sgcOpenAPI Parser tiene 2 métodos
Ejemplo
Use Abstractapi para recuperar la localización de una dirección IP.
GetOpenAPIClient.Retrieve_the_location_of_an_IP_address('your api', '80.258.15.2');
auth2Code: Se utiliza para realizar autenticación y autorización en la mayoría de los tipos de aplicaciones, incluidas las de página única, las aplicaciones web y las instaladas de forma nativa. El flujo permite a las aplicaciones adquirir de forma segura access_tokens que pueden usarse para acceder a recursos protegidos, así como tokens de actualización para obtener access_tokens adicionales y tokens de ID para el usuario que ha iniciado sesión.
auth2ClientCredentials: Este tipo de concesión se utiliza habitualmente para interacciones de servidor a servidor que deben ejecutarse en segundo plano, sin interacción inmediata con un usuario. Este tipo de aplicaciones suele denominarse daemons o cuentas de servicio.
Más información sobre OAuth2.
Permite configurar cómo conectarse a servidores seguros SSL/TLS usando el protocolo HTTP/1
Los clientes generados verifican el certificado del servidor de forma predeterminada, las versiones anteriores no lo hacían. La confianza proviene de las rutas de verificación predeterminadas de OpenSSL, así que en una máquina donde no haya ningún almacén de CA configurado, establezca TLSOptions.RootCertFile con el archivo que contiene los certificados raíz de confianza. Para conectarse a un extremo autofirmado o de prueba, establezca TLSOptions.VerifyCertificate := False.
ALPNProtocols: lista de los protocolos ALPN que se enviarán al servidor.
RootCertFile: ruta al archivo de certificado raíz.
CertFile: ruta al archivo de certificado.
KeyFile: ruta al archivo de clave del certificado.
Password: si el certificado está protegido con contraseña, configúrela aquí.
VerifyCertificate: si se debe verificar el certificado, habilite esta propiedad. El cliente OpenAPI la habilita de forma predeterminada, establézcala en False para aceptar un certificado autofirmado.
VerifyDepth: es una propiedad Integer que representa el número máximo de enlaces permitidos al realizar la verificación del certificado X.509.
Version: por defecto utiliza TLS 1.0; si el servidor requiere una versión TLS superior, puede seleccionarse aquí.
IOHandler: seleccione qué biblioteca utilizará para la conexión mediante TLS.
iohOpenSSL: utiliza la biblioteca OpenSSL y es la opción predeterminada para los componentes Indy. Requiere desplegar las bibliotecas OpenSSL para win32/win64.
iohSChannel: utiliza Secure Channel, que es un protocolo de seguridad implementado por Microsoft para Windows, no requiere desplegar bibliotecas OpenSSL. Solo funciona en Windows 32/64 bits.
OpenSSL_Options: configuración de las bibliotecas OpenSSL.
APIVersion: permite definir qué API de OpenSSL se utilizará.
oslAPI_1_0: utiliza API 1.0 de OpenSSL, la última versión compatible con Indy
oslAPI_1_1: utiliza la API 1.1 de OpenSSL, requiere nuestra biblioteca Indy personalizada y permite usar las bibliotecas OpenSSL 1.1.1 (con soporte para TLS 1.3).
oslAPI_3_0: usa la API 3.0 de OpenSSL, requiere nuestra biblioteca Indy personalizada y permite usar las bibliotecas OpenSSL 3.0.0 (con soporte TLS 1.3).
LibPath: aquí puede configurar dónde se encuentran las bibliotecas openSSL
oslpNone: es el valor predeterminado; las bibliotecas openSSL deben estar en la misma carpeta donde se encuentra el binario o en una ruta conocida.
oslpDefaultFolder: establece automáticamente la ruta de openSSL donde deben ubicarse las bibliotecas para todas las personalidades del IDE.
oslpCustomFolder: si esta es la opción seleccionada, defina la ruta completa en la propiedad LibPathCustom.
LibPathCustom: cuando LibPath = oslpCustomFolder, defina aquí la ruta completa donde se encuentran las bibliotecas openSSL.
UnixSymLinks: habilita o deshabilita la carga de SymLinks en sistemas Unix (por defecto está habilitado, excepto en OSX64):
oslsSymLinksDefault: están habilitados por defecto excepto en OSX64 (tras MacOS Monterey, falla al intentar cargar la biblioteca sin versión.).
oslsSymLinksLoadFirst: Cargar los SymLinks antes de intentar cargar las bibliotecas de versión.
oslsSymLinksLoad: Cargar SymLinks después de intentar cargar las bibliotecas de versión.
oslsSymLinksDontLoad: no carga los SymLinks.
SChannel_Options: permite usar un certificado del almacén de certificados de Windows.
CertHash: es el Hash del certificado. Puede encontrar el Hash del certificado ejecutando un comando dir en powershell.
CipherList: aquí puede establecer qué cifrados se utilizarán (separados por ":"). Ejemplo: CALG_AES_256:CALG_AES_128
CertStoreName: el nombre del almacén donde se guarda el certificado. Seleccione una de las siguientes opciones:
scsnMY (el predeterminado)
scsnCA
scsnRoot
scsnTrust
CertStorePath: la ruta del almacén donde se guarda el certificado. Seleccione una de las siguientes:
scspStoreCurrentUser (el valor predeterminado)
scspStoreLocalMachine
Use esta propiedad para configurar las conexiones a través de un proxy.
Enabled: establézcalo en true para habilitar las conexiones a través de proxy.
Host: Dirección del servidor proxy
Port: Puerto del servidor proxy
UserName/Password: Autenticación para conectarse al proxy, solo si es necesario.
ProxyType: se admiten los siguientes proxies:
Si la propiedad Log está habilitada, guarda los mensajes del socket en un archivo de registro especificado, lo que resulta útil para la depuración.
Log: actívelo si desea guardar las solicitudes HTTP en un archivo de texto.
LogFileName: ruta completa al nombre del archivo.
Otras propiedades que se pueden usar para personalizar el cliente OpenAPI:
EncodeBodyAsUTF8: si está habilitado, el cuerpo de la solicitud se codifica como UTF-8 (de forma predeterminada true). Un documento JSON es UTF-8 según RFC 8259, un cuerpo codificado como ANSI altera todos los caracteres fuera del rango ASCII.
Las clases (DTO) generadas a partir de la especificación exponen las siguientes propiedades para personalizar cómo se escriben en JSON:
JSONIgnoreEmptyStrings: de forma predeterminada es False, por lo que un campo que contiene una cadena vacía se escribe como "field": "". Una cadena vacía es un valor y el servidor no puede distinguirla de un campo que nunca se ha establecido. Establézcala en True para dejar las cadenas vacías fuera del JSON, que es lo que hacían las versiones anteriores.
JSONIgnoreNullValues: de forma predeterminada es True, por lo que un null no se escribe en el JSON. Los null se controlan únicamente con esta propiedad, es independiente de JSONIgnoreEmptyStrings. Establézcala en False para escribir un null explícito, que es lo que necesita un JSON Merge Patch (RFC 7386) para eliminar un miembro.
El resultado de una solicitud se devuelve en un objeto TsgcOpenAPIResponse.
ResponseStream: stream donde se escribe el cuerpo de la respuesta, asigne su propio stream para guardar una descarga directamente en él.
OwnsResponseStream: un stream asignado por el llamador ya no se destruye con la respuesta, el llamador conserva la propiedad. Establézcala en True para restaurar el comportamiento anterior y dejar que la respuesta libere el stream.
Se admite un parámetro declarado como in: cookie en la especificación. Todos los parámetros de cookie de una solicitud se envían juntos en una única cabecera Cookie, tal como exige RFC 6265.
De forma predeterminada, el cliente OpenAPI ejecuta las solicitudes de forma síncrona. Utilice la API asíncrona para ejecutar una solicitud en un hilo en segundo plano y recibir notificaciones a través de eventos, lo que mantiene la interfaz de usuario receptiva y permite cancelar la solicitud.
HTTP_REQUEST_Async: ejecuta la solicitud en un hilo de trabajo. El cliente asume la propiedad del objeto de la solicitud.
CancelAsync: cancela la solicitud en curso.
SynchronizeEvents: cuando es True, los eventos se redirigen al hilo principal. De forma predeterminada es False y los eventos se disparan en el hilo de trabajo.
El resultado se entrega a través de los siguientes eventos:
OnResponse: la solicitud se completó, la respuesta se pasa como parámetro.
OnError: la solicitud falló, la excepción se pasa como parámetro.
OnCancel: la solicitud fue cancelada por CancelAsync.
El cliente no se puede liberar desde dentro de su propio manejador de eventos OnResponse, OnError u OnCancel. Destruirlo espera al hilo de trabajo, que es el mismo hilo que ejecuta el manejador, por lo que la aplicación se quedaría bloqueada. En su lugar se lanza un error claro, libere el cliente una vez que el manejador de eventos haya retornado.
A continuación encontrará la lista de eventos que puede gestionar al usar el cliente OpenAPI.
OnBeforeRequest
Este evento se invoca antes de que se realice la solicitud HTTP. Permite personalizar los nombres de parámetros, encabezados, seguridad... A continuación se muestra un ejemplo de cómo reemplazar el nombre de algunos parámetros.
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
Este evento se llama cuando se carga un archivo; puede usar este evento para conocer el progreso de la carga.
OnDownload
Este evento se llama cuando se descarga un archivo; puede usarlo para conocer el progreso de la descarga.
OnSSLVerifyPeer
Si la verificación del certificado está habilitada, en este evento puede verificar y decidir si acepta el certificado del servidor.
OnSSLGetHandler
Este evento se genera antes de crear el controlador SSL; aquí puede crear su propio controlador SSL (debe heredar de TIdServerIOHandlerSSLBase o TIdIOHandlerSSLBase) y establecer las propiedades necesarias.
OnSSLAfterCreateHandler
Si no se ha creado ningún objeto SSL personalizado, se crea por defecto utilizando el controlador OpenSSL. Puede acceder a las propiedades del controlador SSL y modificarlas si es necesario.