> 核心功能: 本技能提供中文交互、化工作流场景等能力。

> 核心功能: 本技能提供（API、等核心能力等能力。

API 集成开发助手

提供完整的 API 集成能力,从 RESTful 到 GraphQL,帮助 AI Agent 快速接入第三方服务,扩展能力边界.
范围外（本技能不做）: 逆向工程闭源 API、API 代理服务器部署、API Key 生成与分发、API 监控告警.

请求格式

付费版扩展能力

安装与配置

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

能力矩阵

• RESTful 调用: GET/POST/PUT/DELETE 方法封装,支持 JSON 请求与响应处理
• 认证管理: API Key / OAuth2 / JWT / Basic Auth 四种认证方式
• GraphQL 查询: 按需查询、强类型、单一端点、实时订阅
• 错误处理: HTTP 状态码体系（200/201/400/401/404/500）与异常恢复
• OAuth2 令牌: client_credentials 授权模式获取 access_token
• 安全调用: raise_for_status() 异常检测与分状态码处理

核心知识

1. RESTful API

HTTP 方法:
| 方法 | 用途 | 典型状态码 |
|:---:|:---:|:---:|
| GET | 获取资源 | 200 |
| POST | 创建资源 | 201 |
| PUT | 更新资源（完整） | 200 |
| DELETE | 删除资源 | 200/204 |

HTTP 状态码:
| 状态码 | 说明 |
|:------|------:|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 请求错误（参数缺失/格式错误） |
| 401 | 未授权（Token 缺失/过期） |
| 404 | 资源不存在 |
| 500 | 服务器错误 |

2. 认证方式

3. GraphQL

特点:
- 按需查询: 客户端指定所需字段,减少冗余数据传输
- 强类型: Schema 定义类型系统,编译时校验
- 单一端点: 所有操作通过 /graphql 端点完成
- 实时订阅: 支持 WebSocket 订阅,数据变更实时推送

使用说明

Step 1: 确定集成目标

明确需要接入的第三方服务、认证方式与数据需求.

Step 2: 选择认证方式

• 内部服务: API Key
• 第三方平台: OAuth2（client_credentials 或 authorization_code）
• 微服务间: JWT
• 遗留系统: Basic Auth

Step 3: 实现 RESTful 调用

使用 requests 库封装通用调用函数,处理 JSON 请求与响应.

Step 4: 实现认证管理

根据选择的认证方式,实现令牌获取与刷新逻辑.

Step 5: 实现错误处理

使用 raise_for_status() 检测异常,按状态码分类处理.

Step 6: 测试与集成

验证调用链路,确保认证、请求、响应、错误处理正常工作.
结果验证: 任务完成后,查看输出确认状态。成功时返回摘要和数据;失败时根据错误信息排查,参考恢复章节获取修复步骤.

案例展示

案例1: RESTful 通用调用封装

场景: 开发者需要封装通用的 RESTful API 调用函数

import requests
# ...
def call_api(endpoint, method='GET', data=None, headers=None):
    response = requests.request(
        method=method,
        url=endpoint,
        json=data,
        headers=headers
    )
    response.raise_for_status()
    return response.json()

说明: 通用调用函数支持 GET/POST/PUT/DELETE,json=data 自动序列化请求体,raise_for_status() 在 4xx/5xx 时抛出 HTTPError.

案例2: OAuth2 令牌获取

场景: 开发者需要通过 client_credentials 模式获取 access_token

import requests
# ...
def get_oauth_token(client_id, client_secret):
        'https://api.example.com/oauth/token',
        data={
            'grant_type': 'client_credentials',
            'client_id': client_id,
            'client_secret': client_secret
        }
    )
    response.raise_for_status()
    return response.json()['access_token']

说明: 使用 grant_type=client_credentials 获取 access_token。Token 有效期由服务端决定（通常 1-2 小时）,过期后需重新获取或使用 refresh_token 刷新.

案例3: 安全错误处理

场景: 开发者需要按状态码分类处理 API 错误

def safe_api_call(endpoint):
    try:
        return call_api(endpoint)
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 404:
            return {'error': 'Resource not found'}
        elif e.response.status_code == 401:
            return {'error': 'Unauthorized, token may be expired'}
        else:
            return {'error': str(e)}

说明: HTTPError 异常中包含 response.status_code,按 404/401 等状态码分类处理。401 时提示 Token 过期,404 时提示资源不存在.

案例4: GraphQL 查询

场景: 开发者需要通过 GraphQL 按需查询用户数据

import requests
# ...
def graphql_query(endpoint, query, token):
        endpoint,
        json={'query': query},
        headers={'Authorization': f'Bearer {token}'}
    )
    response.raise_for_status()
    return response.json()['data']
# ...
# 按需查询: 仅获取 id 和 name 字段
result = graphql_query(
    'https://api.example.com/graphql',
    '{ users { id name } }',
    'access_token_未指定'
)

说明: GraphQL 通过单一端点 /graphql 发送查询,客户端指定所需字段（id、name）,服务端仅返回请求的字段,减少冗余数据.

异常管理

问答集成

Q1: API Key 和 OAuth2 该选哪个?

A: API Key 适合内部服务与开发环境,简单但安全性中等;OAuth2 适合第三方平台与 SaaS 集成,提供 access_token + refresh_token 机制,安全性高。对安全要求高的场景推荐 OAuth2.

Q2: OAuth2 的 access_token 过期了怎么办?

A: 使用 refresh_token 向令牌端点发起刷新请求,获取新的 access_token。refresh_token 有效期通常比 access_token 长（如 7 天 vs 2 小时）。若 refresh_token 也过期,需重新走完整授权流程.

Q3: GraphQL 和 RESTful 有什么区别?

A: RESTful 使用多个端点（/users、/orders）,每个端点返回固定字段;GraphQL 使用单一端点（/graphql）,客户端按需指定字段。GraphQL 减少冗余数据传输,但学习成本较高。RESTful 更成熟、缓存友好.

Q4: raise_for_status() 有什么作用?

A: raise_for_status() 在 HTTP 状态码为 4xx/5xx 时抛出 requests.exceptions.HTTPError 异常。不调用则需手动检查 response.status_code。推荐在调用后立即使用,配合 try/except 进行错误处理.

Q5: Basic Auth 为什么安全性低?

A: Basic Auth 将用户名密码以 Base64 编码传输,非加密,易被中间人截获。仅在 HTTPS 环境下使用,且不推荐用于生产环境。生产环境推荐 JWT 或 OAuth2.

Q6: 如何处理 API 速率限制?

A: 检查响应头 X-RateLimit-Remaining,当剩余次数不足时降低请求频率。收到 429 状态码时,使用指数退避重试（2s/4s/8s），最多 3 次。同时检查 Retry-After 头获取建议等待时间.

功能边界

1. 需网络连接: API 调用需可访问目标服务端点,无网络环境无法使用
2. 需有效凭证: API Key / OAuth2 Token 等凭证需自行获取与管理
3. 不代发请求: 提供调用模板与知识,不代理执行实际 API 请求
4. 以 Python 为主: 示例使用 Python requests 库,不提供其他语言 SDK
5. 不含 API 文档: 不包含具体服务的端点参考,需查阅各服务官方文档
6. 不含 模拟 服务: 不提供 模拟 API 服务器,测试需对接真实或自建 模拟

快速开始

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 详细的输入输出格式请参考下方章节说明。

输出规范

{
  "success": true,
  "data": {
    "result": "API集成开发助手处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "api-integration"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}

创新优势

效率提升量化分析

差异化对比

核心痛点解决

诊断与修复

安全免责声明

1. [与「API集成开发助手」相关的安全注意事项]
   - 确保API Key和Token等敏感信息不被泄露。
   - 定期更新API Key和Token，防止被滥用。
   - 对API调用进行日志记录，以便追踪和审计。
   - 避免在代码中硬编码敏感信息。
   - 对API调用进行异常处理，防止信息泄露。

安全风险防范

功能介绍

• 自动化执行: 掌握RESTful调用、GraphQL查询、OAuth2/JWT认证管理与错误处理,连接第三方服务扩展能力
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据

技术支持

Q1: API集成开发助手支持哪些输入格式？

A1: 掌握RESTful调用、GraphQL查询、OAuth2/JWT认证管理与错误处理,连接第三方服务扩展能力。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

错误处理框架

针对API集成开发助手使用中可能遇到的常见问题,提供以下排查方案:

API集成开发助手通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块