使用全新的账户 API 自动化您的 eSeGeCe 下载

2026年6月4日 · 应用

到目前为止，获取已注册的构建版本意味着您需要登录账户，打开 Downloads，选择一个产品并点击下载。偶尔操作一次没什么问题，但当您想从构建脚本、CI 流水线或自动部署工具中拉取最新的安装程序时，这就显得很不方便了。

因此，我们为您的账户新增了一个小型 REST API，它采用 OpenAPI 3.0 描述，位于 /api/v1 之下。您只需用平时的账户凭据完成一次身份验证，获取一个令牌，然后即可列出并下载订阅授权范围内的文件。它复用了与网页 Downloads 页面相同的授权与签名逻辑，因此您看到的文件始终与在浏览器中看到的一致。而且由于整个服务由 sgcWebSockets OpenAPI 服务器提供，我们还能交付一个基于 sgcOpenAPI 构建的开箱即用 Delphi 客户端。

1. 身份验证

将您的账户用户名和密码发送至 POST /api/v1/login。您将得到一个短期有效的 Bearer 访问令牌（以及一个刷新令牌）。在之后的每次调用中，都要在 Authorization 标头中传递该访问令牌。

curl -X POST https://www.esegece.com/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

响应中携带令牌和一份简要的个人资料：

{
  "token_type": "Bearer",
  "access_token": "…",
  "refresh_token": "…",
  "expires_in": 3600,
  "user": { "username": "…", "name": "…", "email": "…" }
}

当访问令牌过期时，使用您的刷新令牌调用 POST /api/v1/refresh 以获取一对新令牌，或者直接重新登录。POST /api/v1/logout 会吊销您不再需要的令牌。

2. 列出您可以下载的文件

GET /api/v1/downloads 会返回您的账户可下载的文件。省略版本即为最新发布版，传递 ?version=2026.5.0 可指定特定版本，或传递 ?version=beta 获取当前的 beta 版本。使用 GET /api/v1/products/versions 可发现可用的版本及其发布日期。

curl "https://www.esegece.com/api/v1/downloads" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

每一项描述一个文件，并包含一个短期有效的已签名 url，用于流式传输文件字节：

{
  "files": [
    {
      "product": "sgcWebSockets",
      "version": "2026.5.0",
      "kind": "release",
      "filename": "sgcWebSockets_2026.5.0.exe",
      "date": "2026-05-15",
      "url": "https://www.esegece.com/api/v1/dl?t=…"
    }
  ],
  "version": "2026.5.0"
}

3. 下载每个文件

每一项都带有一个开箱即用的 url。只需对它发起 GET 请求并保存字节即可 — 该链接经过签名且短期有效，因此请在下载前不久再请求文件列表。

curl -L -o setup.exe "URL_FROM_THE_LIST"

使用 sgcOpenAPI 的 Delphi 客户端

由于该 API 采用 OpenAPI 描述，您只需几行代码就能用 sgcOpenAPI 客户端在 Delphi 中驱动它：登录、设置 Bearer 令牌，然后列出（并下载）您的文件。您也可以让 sgcOpenAPI 代码生成器指向该规范，生成一个完全类型化的客户端。

uses
  sgcHTTP_OpenAPI_Client;

var
  oClient: TsgcOpenAPI_Client;
  oReq: TsgcOpenAPIRequest;
  oResp: TsgcOpenAPIResponse;
  vToken: string;
begin
  oClient := TsgcOpenAPI_Client.Create(nil);
  oReq := TsgcOpenAPIRequest.Create;
  oResp := TsgcOpenAPIResponse.Create;
  try
    oClient.SetBaseURL('https://www.esegece.com');

    // 1) Log in -> Bearer token
    oReq.Method := oapiHttpPOST;
    oReq.Endpoint := '/api/v1/login';
    oReq.ContentType := 'application/json';
    oReq.Body := '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}';
    oClient.HTTP_REQUEST(oReq, oResp);
    vToken := GetJSONValueFromNode('access_token', oResp.ResponseText);
    oClient.Authentication.Token.BearerToken := vToken;

    // 2) List the files for the latest release
    oReq.Method := oapiHttpGET;
    oReq.Endpoint := '/api/v1/downloads';
    oReq.Body := '';
    oReq.Security := oapiSecurityToken;
    oClient.HTTP_REQUEST(oReq, oResp);
    Writeln(oResp.ResponseText);
  finally
    oResp.Free;
    oReq.Free;
    oClient.Free;
  end;
end;

我们提供了该程序的完整版本 — 它会登录、列出每一个授权文件并将它们全部下载 — 作为可从您的账户下载的 .dpr 文件。

交互式文档及其位置

登录您的账户，打开侧边栏中的 API 条目（/my-account/api）。在那里您会找到一份并排展示 Delphi 与 curl 示例的 Quickstart、位于 /api/v1/docs 的交互式 Swagger UI、位于 /api/v1/openapi.json 的原始 OpenAPI 规范，以及可下载的 Delphi 客户端。该页面支持账户门户提供的所有语言。

关于安全性的说明：令牌短期有效且可吊销，登录受速率限制，并且每个请求都会根据您账户的授权进行检查 — 这与网页 Downloads 页面完全一致。子账户会继承其父账户的下载内容，正如它们在浏览器中那样。

有疑问、反馈，或需要帮助将其接入您的构建流程？联系我们 — 您将得到编写这些代码的人的回复。