跳到主要内容
Sursa Developers

GET/v1/catalog/services/{service_id}/icon

获取服务的图标

get_catalog_service_icon

返回服务图标：随 Sursa 一起提供的 128×128 透明背景 WebP 图片。响应永远不会改变：Cache-Control: public, max-age=31536000, immutable，ETag 由目录版本和 ID 组合而成（在 If-None-Match 中发送它可得到 304）。v 参数（目录版本，已包含在 icon_url 中）用于在浏览器缓存中区分不同版本。对于没有图标的条目（icon: false），此接口返回 404 catalog.icon_not_found，界面会显示名称首字母。如果部署从外部地址提供图标，icon_url 会指向该地址，而此接口仍然可用。

身份验证

在 Authorization 请求头中传入 API 密钥：Authorization: Bearer <密钥>。

路径参数

  • service_idstring (uuid)必填

    服务目录条目的 ID（UUID）。

查询参数

  • vstring | null

    用于缓存的目录版本（包含在 ServiceRef.icon_url 中）。

请求头参数

  • X-View-Asstring

    仅适用于具有 admin 角色的 API 密钥。以数据权限档案 <profile>[:viewer|verifier|editor] 的身份发出请求，例如 employee:viewer。部署密钥不能使用此头（403）。

Cookie 参数

  • kb_view_asstring

    会话的“View as”模式 Cookie。POST /auth/view-as 设置该 Cookie，DELETE /auth/view-as 将其清除。

响应

200图标文件；如果 `If-None-Match` 匹配，则返回 304。

响应头

  • ETag

    徽标文件的指纹。在 If-None-Match 中发送此值，徽标未更改时返回 304。

  • Cache-Control

    响应的缓存规则。

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

image/webp

string (binary)
304图标未更改（`If-None-Match` 与 `ETag` 匹配）。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

401未发送凭据（既没有会话 Cookie，也没有 API 密钥），或未找到该密钥。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

403不允许执行该操作：角色权限不足、无权访问合集或卡片、请求在“View as”模式下执行，或组织已被暂停或删除（`detail` 为对象，包含 `code: org_suspended | org_deleted`）。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

404对象不存在或您无权访问。对于访问受限的对象，API 不会确认其是否存在。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

422校验错误：请求体或参数不符合定义的结构（`detail` 为校验错误列表），或参数值超出范围（`detail` 为消息）。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

429请求过多（`api.rate_limited`）、组织每分钟、每天或每月的配额已用完（`api.quota_exceeded`；`error.details` 中包含 `quota`、`limit` 和 `reset_at`）、已达到组织的限额，或回答服务繁忙（`answers.engine_busy`）。请等待 `Retry-After` 头中给出的时间。

响应头

  • Retry-After

    重试请求前需要等待的秒数。

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

错误码

除所有请求通用的错误码外，此接口还可能在 error.code 中返回以下错误码。

速率限制

响应带有 RateLimit 和 RateLimit-Policy 头，以及旧版的 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头。429 响应带有以秒为单位的 Retry-After：等待后重试。

← catalog · API 参考