CNB API 技能文档

技能概述

本技能提供 CNB (Cloud Native Build) Open API 的完整调用能力，支持所有 API 接口的调用和操作。每个 API 都有详细的文档说明，包含请求参数、响应格式和调用示例。

> 重要规则（必须遵守）：
> 1. 必须实际执行：访问 CNB API 时，必须通过 exec_command 工具实际执行 curl 命令，不要只在回复中描述或展示 curl 命令。用户需要的是 API 返回的结果，不是命令本身。
> 2. 使用 curl + Authorization：不要使用 web_fetch 工具，因为 web_fetch 无法携带认证信息。
> 3. 使用环境变量：始终使用 $CNB_TOKEN 和 $CNB_API_ENDPOINT 环境变量引用，不要使用 <CNB_TOKEN> 占位符。
> 4. 主动执行：不要询问用户"是否需要我执行"，直接执行 curl 获取结果并分析。
> 5. 必须: 执行 curl 命令时必须使用 -w '%header{traceparent}' 获取 trace 信息，当请求失败时，务必返回 traceparent header, traceparent 信息仅记录在命令输出的日志中用于问题排查，不要在回复中展示给用户。

页面 URL 解析规则

当用户提供 CNB 平台的页面链接时，需要从 URL 中提取参数来构造 API 请求：

示例：用户给了 https://{host}/{org}/{repo}/-/build/logs/{sn}
- 提取 repo = {org}/{repo}，sn = {sn}
- 先执行：curl ... "${CNB_API_ENDPOINT}/{org}/{repo}/-/build/status/{sn}" 获取构建状态
- 如需详细日志，再调用 stage 接口

基础配置

API 基础地址： 从环境变量 CNB_API_ENDPOINT 获取，默认为 https://api.cnb.cool

认证方式： Bearer Token

环境变量：
- CNB_TOKEN：身份认证令牌（必须）
- CNB_API_ENDPOINT：API 请求基础地址（可选，默认为 https://api.cnb.cool）

请求头要求：
- Accept: application/vnd.cnb.api+json
- Authorization: Bearer $CNB_TOKEN

API 接口索引

activities 服务

1. 获取访问令牌

在调用任何 API 之前，需要先获取有效的 CNB_TOKEN。

2. 构造请求

所有请求都需要包含以下基础头信息：

Accept: application/vnd.cnb.api+json
Authorization: Bearer $CNB_TOKEN

3. 处理响应

API 返回标准的 JSON 格式响应。请根据 HTTP 状态码判断请求是否成功：

• 200: 请求成功
• 400: 请求参数错误
• 401: 未授权
• 403: 禁止访问
• 404: 资源不存在
• 500: 服务器内部错误

调用示例

基础 GET 请求示例

curl -w '%header{traceparent}' -X GET \
  "${CNB_API_ENDPOINT}/api/endpoint" \
  -H "Accept: application/vnd.cnb.api+json" \
  -H "Authorization: Bearer $CNB_TOKEN"

带参数的 POST 请求示例

curl -w '%header{traceparent}' -X POST \
  "${CNB_API_ENDPOINT}/api/endpoint" \
  -H "Accept: application/vnd.cnb.api+json" \
  -H "Authorization: Bearer $CNB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

注意事项

1. 所有 API 调用都需要有效的认证令牌
2. 请求和响应数据格式为 JSON
3. 请根据具体 API 文档中的参数要求构造请求
4. 建议在生产环境中添加适当的错误处理和重试机制

本文档基于 Swagger 文件自动生成：https://api.cnb.cool/swagger.json