API集成开发助手

API 集成开发助手。掌握 RESTful API 调用、GraphQL 查询支持、API 认证管理（API Key/OAuth2/JWT/Basic Auth）与错误处理等核心能力。提供 Python requests 调用模板、OAuth2 client_credentials 令牌获取、 HTTP 状态码...

天轰穿@thcjp

Install

openclaw skills install @thcjp/api-integration

功能说明: 本技能涵盖中文交互、化工作流场景等核心能力。

API 集成开发助手

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

请求格式

参数名	类型	必填	说明
input	string	是	API集成开发助手处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

付费版扩展能力

能力	免费版	付费版
基础功能	支持	支持
API集成开发助手GraphQL查询	不支持	支持
API集成开发助手JWT认证管理	不支持	支持
API集成开发助手与错误处理	不支持	支持
代码静态分析与质量评分	不支持	支持
依赖缺陷检测与升级建议	不支持	支持

安装与配置

运行环境

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

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

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

可用性分类

分类: MD+EXEC（）

API Key配置方式:

bash

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

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

核心知识

1. RESTful API

HTTP 方法:

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

HTTP 状态码:

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

2. 认证方式

方式	说明	安全性	典型场景
API Key	简单密钥,请求头传递	中	内部服务、开发环境
OAuth2	授权框架,`access_token` + `refresh_token`	高	第三方平台、SaaS 集成
JWT	Token 认证,含签名与过期时间	高	微服务、SPA 应用
Basic Auth	基础认证,用户名密码 Base64	低	遗留系统、测试环境

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 调用函数

python

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

python

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 错误

python

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 按需查询用户数据

python

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 头获取建议等待时间.

功能边界

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

输出规范

json

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

创新优势

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
RESTful API 调用	30分钟	2分钟	28分钟	10%
GraphQL 查询构建	1小时	15分钟	45分钟	15%
OAuth2 令牌获取	30分钟	5分钟	25分钟	5%
错误处理与日志记录	1小时	20分钟	40分钟	20%
API 测试与验证	2小时	30分钟	1.5小时	10%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
功能全面性	高	低	中	高
易用性	高	低	中	高
性能	中	低	中	高
成本	低	高	中	高
支持与维护	高	低	中	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
手动集成复杂	需要手动编写大量代码，复杂度高	项目进度	提供自动化集成工具	提高效率30%
认证管理繁琐	认证过程复杂，易出错	应用安全	简化认证流程，减少错误	提高安全性10%
错误处理困难	错误信息不明确，难以定位问题	应用稳定性	提供错误处理机制	提高稳定性20%

诊断与修复

错误现象	可能原因	诊断步骤	解决方案
无法连接API	网络问题	检查网络连接	修复网络连接
认证失败	Token过期	刷新Token	刷新Token
API返回错误	请求参数错误	检查请求参数	修正请求参数
处理结果异常	数据格式错误	检查数据格式	修正数据格式
调用超时	API响应慢	检查API状态	联系API提供商

安全免责声明

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

安全风险防范

风险项	等级	防护措施	验证方法
API密钥泄露	高	通过环境变量配置，禁止硬编码	定期检查代码和配置文件
命令执行风险	高	仅执行白名单命令，避免拼接用户输入	使用沙箱环境测试
网络通信安全	中	使用HTTPS协议，验证SSL证书	定期检查证书有效期
敏感数据暴露	高	输出结果中不包含密钥、令牌等敏感信息	日志脱敏审查
未授权访问	中	限制访问权限，实施认证机制	定期审计访问日志

错误处理框架

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

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置