StackStorm API 接口详解与使用指南

概述

StackStorm 是一个强大的事件驱动自动化平台，其 API 提供了与 StackStorm 系统交互的标准接口。本文档将深入解析 StackStorm API 的核心功能和使用方法，帮助开发者快速掌握 API 的使用技巧。

API 基础信息

StackStorm API 遵循 RESTful 设计原则，使用 JSON 作为数据交换格式。当前 API 版本为 1.0.0，主要提供以下功能：

• 动作管理（Actions）
• 规则管理（Rules）
• 执行管理（Executions）
• 用户认证与授权
• 系统状态查询

认证机制

StackStorm 提供两种认证方式，开发者可根据使用场景选择合适的方式：

1. 认证令牌（Authentication Token）

适用于短期交互式会话，具有时效性。获取和使用令牌的流程如下：

# 获取令牌
curl -X POST -u '用户名:密码' https://$ST2_HOSTNAME/auth/v1/tokens

# 使用令牌（头部方式）
curl -H "X-Auth-Token: 令牌值" https://$ST2_HOSTNAME/api/v1/actions

# 使用令牌（查询参数方式）
curl "https://$ST2_HOSTNAME/api/v1/actions?x-auth-token=令牌值"

2. API 密钥（API Key）

适用于长期集成的应用场景，无过期时间限制。API 密钥的管理方式：

# 创建 API 密钥
st2 apikey create -k -m '{"used_by": "应用描述"}'

# 使用 API 密钥（头部方式）
curl -H "St2-Api-Key: 密钥值" https://$ST2_HOSTNAME/api/v1/actions

# 使用 API 密钥（查询参数方式）
curl "https://$ST2_HOSTNAME/api/v1/actions?st2-api-key=密钥值"

核心 API 端点详解

1. 根端点 /api/v1/

提供 API 的基本信息，包括版本号和文档链接。

请求示例：

curl -H "X-Auth-Token: 令牌值" https://$ST2_HOSTNAME/api/v1/

2. 用户端点 /api/v1/user

获取当前认证用户的元数据信息。

请求示例：

curl -H "X-Auth-Token: 令牌值" https://$ST2_HOSTNAME/api/v1/user

3. 动作管理端点 /api/v1/actions

获取动作列表

支持多种过滤条件：

• pack: 按包名过滤
• name: 按动作名过滤
• tags: 按标签过滤
• limit/offset: 分页控制

请求示例：

curl -H "X-Auth-Token: 令牌值" \
"https://$ST2_HOSTNAME/api/v1/actions?pack=chatops&limit=10"

创建新动作

需要提供完整的动作定义 JSON。

请求示例：

curl -X POST -H "X-Auth-Token: 令牌值" \
-H "Content-Type: application/json" \
-d '{"name":"sample_action","pack":"examples","runner_type":"local-shell-cmd","parameters":{"cmd":{"type":"string"}},"entry_point":"","enabled":true}' \
https://$ST2_HOSTNAME/api/v1/actions

4. 单个动作端点 /api/v1/actions/{ref_or_id}

通过引用或ID获取特定动作的详细信息。

请求示例：

curl -H "X-Auth-Token: 令牌值" \
https://$ST2_HOSTNAME/api/v1/actions/core.local

最佳实践

1. 错误处理：所有 API 调用都应检查 HTTP 状态码，4xx 表示客户端错误，5xx 表示服务器错误。

2. 分页查询：对于可能返回大量数据的查询，务必使用 limit 和 offset 参数实现分页。

3. 属性过滤：使用 include_attributes 和 exclude_attributes 参数优化返回数据，减少网络传输。

4. 调试技巧：使用 st2 --debug 命令查看底层 API 调用，有助于理解 API 工作方式。

5. 安全建议：

   • 生产环境务必配置有效的 SSL 证书
   • 避免在 URL 中传递认证令牌（优先使用头部方式）
   • 定期轮换 API 密钥

常见问题

1. 认证失败：检查令牌是否过期或密钥是否被撤销，确认认证头格式正确。

2. 数据冲突：创建资源时遇到 409 冲突错误，通常是因为名称或唯一标识已存在。

3. 性能问题：对于大型部署，建议使用过滤条件限制返回数据量，避免全量查询。

4. JSON 格式：所有 POST 请求体必须是有效的 JSON，Content-Type 头必须设置为 application/json。

通过本文档，开发者应能掌握 StackStorm API 的核心功能和使用方法。实际开发中，建议结合具体业务需求，合理设计 API 调用策略，充分发挥 StackStorm 自动化平台的强大功能。