OpenAPI | 客户端

TsgcOpenAPI_Client 是一个非可视化组件，封装了根据 OpenAPI 规范发出 HTTP 请求的主要方法和属性。

 

使用 sgcOpenAPI 解析器创建的每个 OpenAPI 接口都有 2 个方法

 

1. GetOpenAPIClient：这是一个单例函数，返回主类的实例；若实例不存在，则自动创建。
2. FreeOpenAPIClient：如果主类已创建则释放它。

 

示例

使用 Abstractapi 检索 IP 地址的地理位置信息。

GetOpenAPIClient.Retrieve_the_location_of_an_IP_address('your api', '80.258.15.2');

 

 

身份验证

• Basic：使用用户名/密码作为 HTTP 标头进行身份验证。
  • UserName：用户名。
  • Password：密码。
• OAuth2：使用 OAuth2 进行身份验证，支持两种授权类型：

  • auth2Code：用于在大多数应用程序类型中执行身份验证和授权。该流程使应用能够安全获取 access_token、刷新令牌以及已登录用户的 ID 令牌。

  • auth2ClientCredentials：此授权类型通常用于必须在后台运行、无需与用户立即交互的服务器到服务器交互。

  • 了解更多关于 OAuth2。

• JWT：使用 JWT 进行身份验证。了解有关 JWT 的更多信息。
• Token：您可以传入 Bearer 令牌或任何其他自定义令牌值。

 

TLSOptions

允许配置如何使用 HTTP/1 协议连接到安全 SSL/TLS 服务器

 

生成的客户端默认会验证服务器的证书，早期版本不会验证。信任关系来自 OpenSSL 的默认验证路径，因此在未配置 CA 存储的计算机上，请将 TLSOptions.RootCertFile 设置为包含受信任根证书的文件。要连接到自签名或测试端点，请设置 TLSOptions.VerifyCertificate := False。

 

ALPNProtocols：将发送到服务器的 ALPN 协议列表。

RootCertFile：根证书文件的路径。

CertFile：证书文件的路径。

KeyFile：证书密钥文件的路径。

Password：如果证书有密码保护，请在此处设置。

VerifyCertificate：如果必须验证证书，请启用此属性。OpenAPI 客户端默认启用它，将其设置为 False 可接受自签名证书。

VerifyDepth：一个整数属性，表示对 X.509 证书执行验证时允许的最大链路数。

Version：默认使用 TLS 1.0，如果服务器需要更高的 TLS 版本，可在此处选择。

IOHandler：选择将用于 TLS 连接的库。

iohOpenSSL：使用 OpenSSL 库，是 Indy 组件的默认选项。需要为 win32/win64 部署 OpenSSL 库。

iohSChannel：使用由 Microsoft 为 Windows 实现的安全通道安全协议，无需部署 openssl 库。仅适用于 Windows 32/64 位。

OpenSSL_Options：OpenSSL 库的配置。

APIVersion：允许定义将使用哪个 OpenSSL API 版本。

oslAPI_1_0： 使用 API 1.0 OpenSSL，这是 Indy 支持的最新版本

oslAPI_1_1：使用 OpenSSL API 1.1，需要我们定制的 Indy 库，并支持 OpenSSL 1.1.1 库（含 TLS 1.3 支持）。

oslAPI_3_0：使用 API 3.0 OpenSSL，需要我们的自定义 Indy 库，并允许使用 OpenSSL 3.0.0 库（支持 TLS 1.3）。

LibPath： 在此处您可以配置 openSSL 库的位置

oslpNone：这是默认值，OpenSSL 库应与二进制文件位于同一文件夹中，或位于已知路径中。

oslpDefaultFolder：自动设置所有 IDE 版本应查找 OpenSSL 库的路径。

oslpCustomFolder： 如果选择此选项，请在属性 LibPathCustom 中定义完整路径。

LibPathCustom：当 LibPath = oslpCustomFolder 时，在此处定义 openSSL 库所在的完整路径。

UnixSymLinks： 启用或禁用在 Unix 系统下加载符号链接（默认启用，OSX64 除外）：

oslsSymLinksDefault： 默认情况下启用，但在 OSX64 下除外（MacOS Monterey 之后，不带版本号尝试加载库会失败）。

oslsSymLinksLoadFirst：先加载符号链接，然后再尝试加载版本库。

oslsSymLinksLoad： 在尝试加载版本库后加载符号链接。

oslsSymLinksDontLoad：不加载符号链接。

SChannel_Options：允许您使用 Windows 证书存储中的证书。

CertHash：是证书哈希值。您可以在 PowerShell 中运行 dir 命令找到证书哈希值。

CipherList：在此设置将使用的密码套件（以":"分隔）。示例：CALG_AES_256:CALG_AES_128

CertStoreName：存储证书的存储名称。从以下选项中选择：

scsnMY（默认值）

scsnCA

scsnRoot

scsnTrust

CertStorePath：存储证书的存储路径。请从以下选项中选择：

scspStoreCurrentUser（默认值）

scspStoreLocalMachine

 

 

 

代理选项

使用此属性配置通过代理的连接。

 

Enabled： 设为 true 以启用代理连接。

Host：代理服务器地址

Port：代理服务器端口

UserName/Password：连接代理的身份验证信息，仅在需要时填写。

ProxyType：支持以下代理类型：

• HTTP
• Socks4
• Socks4A
• Socks5

日志

若 Log 属性已启用，则将套接字消息保存到指定的日志文件，便于调试。

 

Log：如果希望将 HTTP 请求保存到文本文件，请启用此选项。

LogFileName：文件名的完整路径。

 

属性

可用于自定义 OpenAPI 客户端的其他属性：

 

EncodeBodyAsUTF8: 若启用，请求正文将以 UTF-8 编码（默认为 true）。根据 RFC 8259，JSON 文档采用 UTF-8 编码，以 ANSI 编码的正文会破坏 ASCII 范围以外的所有字符。

 

JSON 序列化

从规范生成的类（DTO）公开以下属性，用于自定义它们写入 JSON 的方式：

 

JSONIgnoreEmptyStrings：默认为 False，因此保存空字符串的字段会被写为 "field": ""。空字符串本身就是一个值，服务器无法把它与从未设置过的字段区分开。将其设置为 True 可以把空字符串排除在 JSON 之外，这是早期版本的行为。

JSONIgnoreNullValues：默认为 True，因此 null 不会写入 JSON。null 只由此属性控制，它与 JSONIgnoreEmptyStrings 无关。将其设置为 False 可写入显式的 null，JSON Merge Patch (RFC 7386) 删除成员时需要这样做。

 

响应

请求的结果在 TsgcOpenAPIResponse 对象中返回。

 

ResponseStream：写入响应正文的流，可以指定您自己的流，将下载内容直接保存到其中。

OwnsResponseStream：由调用方指定的流不再随响应一起销毁，调用方保留所有权。将其设置为 True 可恢复以前的行为，让响应释放该流。

 

Cookie 参数

支持在规范中声明为 in: cookie 的参数。按照 RFC 6265 的要求，一个请求的所有 cookie 参数会在单个 Cookie 标头中一起发送。

 

异步请求

默认情况下，OpenAPI 客户端同步执行请求。使用异步 API 可在后台线程上执行请求并通过事件接收通知，这能保持用户界面的响应性并允许取消请求。

HTTP_REQUEST_Async：在工作线程上执行请求。客户端接管请求对象的所有权。

CancelAsync：取消正在进行的请求。

SynchronizeEvents：为 True 时，事件被封送到主线程。默认值为 False，事件在工作线程中触发。

结果通过以下事件传递：

OnResponse：请求已完成，响应作为参数传递。

OnError：请求失败，异常作为参数传递。

OnCancel：请求已被 CancelAsync 取消。

不能在客户端自身的 OnResponse、OnError 或 OnCancel 事件处理程序内部释放该客户端。销毁它需要等待工作线程，而该线程正是运行处理程序的线程，因此应用程序会挂起。此时会引发一个明确的错误，请在事件处理程序返回之后再释放客户端。

事件

以下是使用 OpenAPI 客户端时可以处理的事件列表。

 

 

OnBeforeRequest

 

在调用 HTTP 请求之前调用此事件。允许自定义参数名称、标头、安全性……以下是如何替换某些参数名称的示例。

 

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

 

当文件上传时调用此事件，您可以使用此事件了解上传进度。

 

OnDownload

 

当文件下载时调用此事件，您可以使用此事件了解下载进度。

 

OnSSLVerifyPeer

 

如果启用了证书验证，在此事件中您可以验证并决定是否接受服务器证书。

 

OnSSLGetHandler

 

此事件在创建 SSL 处理程序之前引发，您可以在此创建自己的 SSL 处理程序（需要继承自 TIdServerIOHandlerSSLBase 或 TIdIOHandlerSSLBase）并设置所需的属性。

 

OnSSLAfterCreateHandler

 

如果未创建自定义 SSL 对象，则默认使用 OpenSSL 处理程序创建。您可以访问 SSL 处理程序属性并根据需要修改