Azkaban AJAX API 使用指南：从认证到项目管理

Azkaban AJAX API 使用指南：从认证到项目管理

azkaban Azkaban workflow manager. 项目地址: https://gitcode.com/gh_mirrors/az/azkaban

Azkaban 是一个流行的开源工作流调度系统，它提供了一套完整的 AJAX API 接口，允许开发者通过编程方式与系统交互，而不必依赖 Web 界面。本文将详细介绍 Azkaban 的核心 API 使用方法，帮助开发者快速掌握自动化管理 Azkaban 的技巧。

一、API 基础规范

在使用 Azkaban API 前，开发者需要了解以下基础规范：

1. 请求头要求：

   • Content-Type: application/x-www-form-urlencoded
   • X-Requested-With: XMLHttpRequest

2. 会话机制：

   • 所有 API 调用（除认证外）都需要有效的 session.id
   • 会话默认有效期为 24 小时
   • 同一用户的新会话会覆盖旧会话

3. 参数传递方式：

   • 可以通过请求参数直接传递 session.id
   • 也可以通过 Cookie azkaban.browser.session.id 传递

二、核心 API 详解

1. 用户认证 API

功能：获取有效的会话 ID，这是使用其他 API 的前提。

请求方式：

• 方法：POST
• URL：/?action=login

请求参数： | 参数名 | 必填 | 说明 | |--------|------|------| | action=login | 是 | 固定值，表示登录动作 | | username | 是 | Azkaban 用户名 | | password | 是 | 对应用户密码 |

响应示例（成功）：

{
  "status": "success",
  "session.id": "c001aba5-a90f-4daf-8f11-62330d034c0a"
}

响应示例（失败）：

{
  "error": "Invalid username/password"
}

CURL 示例：

curl -k -X POST --data "action=login&username=azkaban&password=azkaban" https://localhost:8443

2. 获取用户项目列表 API

功能：查询指定用户拥有的所有项目列表。

请求方式：

• 方法：GET
• URL：/index?ajax=fetchuserprojects

请求参数： | 参数名 | 必填 | 说明 | |--------|------|------| | session.id | 是 | 用户会话 ID | | ajax=fetchuserprojects | 是 | 固定值，表示获取用户项目动作 | | user | 否 | 要查询的用户名，默认为当前会话用户 |

响应结构：

{
  "projects": [
    {
      "projectId": 123,
      "projectName": "my_project",
      "createdBy": "username",
      "createdTime": 1500671590922,
      "userPermissions": {},
      "groupPermissions": {}
    }
  ]
}

CURL 示例：

curl -k -X GET "https://localhost:8443/index?ajax=fetchuserprojects&user=alice&session.id=9089beb2-576d-47e3-b040-86dbdc7f523e"

3. 创建项目 API

功能：在 Azkaban 中创建一个新项目。

请求方式：

• 方法：POST
• URL：/manager?action=create

请求参数： | 参数名 | 必填 | 说明 | |--------|------|------| | session.id | 是 | 用户会话 ID | | action=create | 是 | 固定值，表示创建项目动作 | | name | 是 | 项目名称 | | description | 是 | 项目描述（不能为空） |

响应示例（成功）：

{
  "status": "success",
  "path": "manager?project=aaaa",
  "action": "redirect"
}

CURL 示例：

curl -k -X POST --data "session.id=9089beb2-576d-47e3-b040-86dbdc7f523e&name=myproject&description=测试项目" https://localhost:8443/manager?action=create

4. 删除项目 API

功能：删除指定的项目。

请求方式：

• 方法：GET
• URL：/manager?delete=true

请求参数： | 参数名 | 必填 | 说明 | |--------|------|------| | session.id | 是 | 用户会话 ID | | delete=true | 是 | 固定值，表示删除动作 | | project | 是 | 要删除的项目名称 |

CURL 示例：

curl -k --get --data "session.id=bca1d75d-6bae-4163-a5b0-378a7d7b5a91&delete=true&project=test-project" https://localhost:8443/manager

5. 上传项目 ZIP 文件 API

功能：上传项目 ZIP 文件到指定项目。

请求方式：

• 方法：POST
• Content-Type：multipart/mixed
• URL：/manager?ajax=upload

请求参数： | 参数名 | 必填 | 说明 | |--------|------|------| | session.id | 是 | 用户会话 ID | | ajax=upload | 是 | 固定值，表示上传动作 | | project | 是 | 目标项目名称 | | file | 是 | ZIP 文件（类型应为 application/zip） |

响应示例：

{
  "error": "Installation Failed.\nError unzipping file.",
  "projectId": "192",
  "version": "1"
}

CURL 示例：

curl -k -i -X POST \
  --form 'session.id=e7a29776-5783-49d7-afa0-b0e688096b5e' \
  --form 'ajax=upload' \
  --form 'file=@myproject.zip;type=application/zip' \
  --form 'project=MyProject' \
  https://localhost:8443/manager

6. 获取项目流列表 API

功能：查询指定项目中的所有工作流（flow）ID。

请求方式：

• 方法：GET
• URL：/manager?ajax=fetchprojectflows

请求参数： | 参数名 | 必填 | 说明 | |--------|------|------| | session.id | 是 | 用户会话 ID | | ajax=fetchprojectflows | 是 | 固定值，表示获取项目流动作 | | project | 是 | 项目名称 |

响应示例：

{
  "project": "MyProject",
  "projectId": 123,
  "flows": [
    {"flowId": "main_flow"},
    {"flowId": "sub_flow"}
  ]
}

CURL 示例：

curl -k --get --data "session.id=bca1d75d-6bae-4163-a5b0-378a7d7b5a91&ajax=fetchprojectflows&project=MyProject" https://localhost:8443/manager

三、最佳实践建议

1. 错误处理：始终检查 API 响应中的 error 字段，处理可能的异常情况
2. 会话管理：建议在会话即将过期前主动重新认证，避免操作中断
3. 批量操作：对于大量项目或流的操作，考虑实现批处理逻辑
4. 权限控制：确保 API 调用使用的账号具有足够的权限执行相应操作
5. 日志记录：记录关键 API 调用的请求和响应，便于问题排查

通过掌握这些核心 API，开发者可以实现 Azkaban 的自动化管理，包括项目创建、配置、工作流部署等全生命周期管理，大大提高工作效率。

azkaban Azkaban workflow manager. 项目地址: https://gitcode.com/gh_mirrors/az/azkaban