跳到主要内容

鉴权

服务只使用一种鉴权方式：在请求头中携带 BuQuant 账号签发的短时访问令牌。

Authorization: Bearer <ACCESS_TOKEN>

取得访问令牌​

用 BuQuant 账号的登录会话向账号服务换取令牌：

curl "$ACCOUNT_URL/api/auth/token" -H "Authorization: Bearer $SESSION_TOKEN"
# {"token": "<ACCESS_TOKEN>"}

令牌有效期 5 分钟，携带你账号当前的数据权益。到期前重新换取即可；BuQuant Studio 会自动完成这一步。令牌刷新不影响已取得的分页游标与下载票据。数据权益按数据包发放，例如 history.cn_equity.daily 覆盖股票、ETF 与指数的数据集，reference.global 覆盖交易日历、交易规则与时段等参照数据（所有账号都有）；每返回一页查询结果，服务按该数据集所属的数据包计量一次。

哪些接口需要凭据​

接口凭据
GET /v1/health、GET /v1/openapi.json不需要
GET /v1/datasets、GET /v1/datasets/{datasetId}必须；目录只列出令牌权益覆盖的数据集
POST /v1/datasets/{datasetId}/query、POST /v1/datasets/{datasetId}/preparations、POST /v1/downloads必须

与鉴权和限流相关的错误​

状态错误码含义与处理
401unauthorized缺少令牌、令牌无效或已过期。重新换取令牌后重试。
403forbidden令牌有效，但权益不覆盖该数据集，或账号的额度、状态不允许本次访问；下载时权益与准备时不一致也会返回该错误。
429rate-limit-exceeded同一凭据的请求频率超过服务设定的上限。稍后重试。
429rate-limited账号服务暂不允许本次计量访问，例如额度或频率受限。稍后重试或联系服务提供方。
429concurrency-limit-exceeded同一凭据同时执行的查询、准备或下载过多。等进行中的请求完成后重试。
503service-unavailable验签公钥、计量或交付记录暂时不可用。稍后重试。

错误响应的结构见版本与错误。

使用建议​

  • 令牌只放在请求头里，不要放进 URL 或查询串：代理与日志可能记录完整 URL。
  • 令牌只有 5 分钟有效；不要把登录会话发给数据服务，也不要长期保存令牌。