统一服务热线 4006-8899-23
English
定制开发

禅道PHP-SDK帮助手册-第一章 分享链接 /book/api/365.html

作者：雷勇 最后编辑：刘振华 于 2023-12-22 10:36:13 浏览量：3645
摘要：本篇将介绍如何在PHP编程语言中集成与使用此SDK，只需要简单的进行配置和引用便可使用。

本篇目录

一、配置参数

禅道 PHP-SDK 文件位于【禅道项目目录/sdk/php/】下。使用 SDK 之前，需要在引用的禅道 SDK 文件中填写一些必要配置信息。禅道安装部署的域名、禅道用户账户、禅道用户密码、禅道配置的参数请求方式。

const ztUrl        = 'http://zentao.*****.com';    // 禅道部署域名
const ztAccount    = 'admin';                      // 禅道登录账户
const ztPassword   = '123456';                     // 禅道登录密码
const ztAccessMode = 'PATH_INFO';                  // 禅道参数请求方式[ GET | PATH_INFO ]

二、禅道SDK可用API列表

  • 获取部门列表
  • 批量添加部门
  • 获取用户列表
  • 添加单个用户可选信息
  • 添加单个用户
  • 获取产品列表
  • 添加单个产品可选信息
  • 添加单个产品
  • 获取项目列表
  • 添加单个项目可选信息
  • 添加单个项目
  • 获取任务列表
  • 添加单个任务可选信息
  • 添加单个任务
  • 完成单个任务可选信息
  • 完成单个任务
  • 获取Bug列表
  • 添加单个Bug可选信息
  • 添加单个Bug
  • 解决单个Bug可选信息
  • 解决单个Bug

三、使用说明与示例

 3.1使用说明

在使用前，确保配置的相关信息填写无误，同时确保登录账户有足够的权限以及登录账户无需进行弱密码重置。所有请求的 API 结果都以 JSON 格式返回，可以根据请求结果中的 status 状态来判断是否请求成功，如果请求失败，部分API会给出相应的提示。在请求 API 的过程中，以 4.1获取部门列表 举例，$params 包含了可传的请求参数，可以为空数组，但必须传递此变量。$extraFields 自定义返回字段，可以根据所需字段结果，进行返回，可自定义字段不限于示例中的字段，此变量可以不传。

 3.2使用示例

以下将以 zentaoPHP 框架中引用作为示例，将 SDK 文件放置在框架目录 tools/zentao/ 下。其它主流框架，如 ThinkPHP、Laravel 等可根据实际需求放置框架目录中，存放目录尽量遵守框架规范。

/**
 * 获取部门列表
 * 
 * @access public
 * @return void
 */
public function getDeptList()
{
    include_once('../../tools/zentao/zentao.php');
    $zentao      = new zentao();    // 实例化类,如果实例化错误,可修改为 "\new zentao();"
    $params      = array('deptID' => 1);    // 请求参数
    $extraFields = array('title', 'deptID', 'parentDepts', 'sons', 'tree');    // 自定义返回字段
    $result      = $zentao->getDeptList($params, $extraFields);    // 调用SDK方法
    echo $result;
}

四、API使用详解

 4.1获取部门列表

方法说明

请求此方法，可以获取当前已添加部门列表数据，根据部门列表数据，后续可用于添加下级部门。
使用示例 
public function getDeptList() {
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $params      = array('deptID' => 1);    // 请求参数
    $extraFields = array('title', 'deptID', 'parentDepts', 'sons', 'tree');    // 自定义返回字段
    $result      = $zentao->getDeptList($params, $extraFields);
    return $result;
}
请求方式 GET
方法名称

getDeptList
请求参数

参数名称 参数类型 是否必填 参数描述

deptID

 int 选填参数 某部门ID

响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
        //当前禅道项目导航位置
        "title": "维护部门-禅道项目管理",
        //当前部门ID
        "deptID": "1",
        //当前部门信息
        "parentDepts": [
            {
                "id": "1",
                "name": "经理",
                "parent": "0",
                "path": ",1,",
                "grade": "1",
                "order": "0",
                "position": "",
                "function": "",
                "manager": ""
            }
        ],
        //当前部门的直属下级部门列表
        "sons": [
            {
                "id": "11",
                "name": "产品经理",
                "parent": "1",
                "path": ",1,11,",
                "grade": "2",
                "order": "10",
                "position": "",
                "function": "",
                "manager": ""
            },
            {
                "id": "12",
                "name": "项目经理",
                "parent": "1",
                "path": ",1,12,",
                "grade": "2",
                "order": "20",
                "position": "",
                "function": "",
                "manager": ""
            }
        ],
        //所有部门列表树
        "tree": [
            {
                "id": "1",
                "name": "经理",
                "parent": "0",
                "path": ",1,",
                "grade": "1",
                "order": "0",
                "position": "",
                "function": "",
                "manager": "",
                "managerName": "",
                "children": [
                    {
                        "id": "11",
                        "name": "产品经理",
                        "parent": "1",
                        "path": ",1,11,",
                        "grade": "2",
                        "order": "10",
                        "position": "",
                        "function": "",
                        "manager": "",
                        "managerName": ""
                    },
                    {
                        "id": "12",
                        "name": "项目经理",
                        "parent": "1",
                        "path": ",1,12,",
                        "grade": "2",
                        "order": "20",
                        "position": "",
                        "function": "",
                        "manager": "",
                        "managerName": ""
                    }
                ],
                "actions": {
                    "delete": false
                }
            },
            {
                "id": "2",
                "name": "开发",
                "parent": "0",
                "path": ",2,",
                "grade": "1",
                "order": "1",
                "position": "",
                "function": "",
                "manager": "",
                "managerName": ""
            },
            {
                "id": "3",
                "name": "测试",
                "parent": "0",
                "path": ",3,",
                "grade": "1",
                "order": "2",
                "position": "",
                "function": "",
                "manager": "",
                "managerName": ""
            },
            {
                "id": "4",
                "name": "市场",
                "parent": "0",
                "path": ",4,",
                "grade": "1",
                "order": "3",
                "position": "",
                "function": "",
                "manager": "",
                "managerName": ""
            },
            {
                "id": "8",
                "name": "客户",
                "parent": "0",
                "path": ",8,",
                "grade": "1",
                "order": "13",
                "position": "",
                "function": "",
                "manager": "",
                "managerName": ""
            }
        ]
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.2批量添加部门

方法说明

请求此方法，可以批量添加部门。
使用示例 
public function addDept()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao = new \zentao();
    $params = array(
        'parentDeptID' => '1',
        'depts'        => array('Department D', 'Department F')
    );    // 请求参数
    $result = $zentao->addDept($params);
    return $result;
}
请求方式
 POST
方法名称 addDept
请求参数
参数名称 参数类型 是否必填 参数描述

parentDeptID

 int

选填参数

所属上级部门ID

depts

array

 必填参数

新增部门名称，示例：'depts' => array('Department D', 'Department F')
响应结果 success error 
{
    "status": 1,
    "msg": "success",
    "result": []
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.3获取用户列表

方法说明

请求此方法，可以根据不同的部门获取该部门下的用户列表信息。
使用示例
 
public function getUserList()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $params      = array('deptID' => 1);    // 请求参数
    $extraFields = array('title', 'users');    // 自定义返回字段
    $result      = $zentao->getUserList($params, $extraFields);
    return $result;
}
请求方式 GET
方法名称

getUserList
请求参数

参数名称 参数类型 是否必填 参数描述

deptID

 int 选填参数

某部门ID

响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
        //当前禅道项目导航位置
        "title": "组织视图首页-部门结构",
        //某个部门所属用户详情列表【不传参则列出所有用户详情列表】
        "users": [
            {
                "id": "16",//用户ID
                "dept": "48",//部门ID
                "account": "Jack6",//用户账号
                "role": "dev",//用户权限
                "realname": "jack6",//真实姓名
                "nickname": "",//用户昵称
                "commiter": "http://jack2019.com",
                "avatar": "",
                "birthday": "0000-00-00",//生日日期
                "gender": "m",//性别【m男/f女】
                "email": "jack2019@gmail.com",//邮箱地址
                "skype": "",
                "qq": "",
                "mobile": "",
                "phone": "",
                "weixin": "",
                "dingding": "",
                "slack": "",
                "whatsapp": "",
                "address": "",
                "zipcode": "",
                "join": "2019-11-11",//入职日期
                "visits": "0",
                "ip": "",
                "last": "0",
                "fails": "0",
                "locked": "0000-00-00 00:00:00",
                "ranzhi": "",
                "score": "0",
                "scoreLevel": "0",
                "deleted": "0",
                "clientStatus": "offline",
                "clientLang": "zh-cn"
            }
        ]
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.4添加单个用户可选信息

方法说明

添加用户时如果需要为新用户分配部门、职位、权限，请求该方法即可返回相关可用数据。
使用示例
 
public function getUserCreateParams()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $extraFields = array('title', 'depts', 'groupList', 'roleGroup');    // 返回自定义字段
    $result      = $zentao->getUserCreateParams(array(), $extraFields);
    return $result;
}
请求方式
 GET
方法名称

getUserCreateParams
请求参数
参数名称
 参数类型
 是否必填
 参数描述
无需传参


响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
        //当前禅道项目导航位置
        "title": "组织视图-添加用户",
        //所属部门列表【添加部门传递key|用户所属部门】
        "depts": {
            "0": "/",
            "1": "/经理",
            "2": "/开发",
            "3": "/测试",
            "4": "/市场",
            "8": "/客户",
            "11": "/经理/产品经理",
            "12": "/经理/项目经理"
        },
        //权限分组列表【添加权限传递key|所属权限分组】
        "groupList": {
            "1": "管理员",
            "2": "研发",
            "3": "测试",
            "4": "项目经理",
            "5": "产品经理",
            "6": "研发主管",
            "7": "产品主管",
            "8": "测试主管",
            "9": "高层管理",
            "10": "其他",
            "11": "guest",
            "12": "受限用户"
        },
        //职位分组列表【职位对应权限分组|所属职位】
        "roleGroup": {
            "admin": "1",
            "dev": "2",
            "qa": "3",
            "pm": "4",
            "po": "5",
            "td": "6",
            "pd": "7",
            "qd": "8",
            "top": "9",
            "others": "10",
            "guest": "11",
            "limited": "12"
        }
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.5添加单个用户

方法说明

请求此方法，用于新增一个新用户，新用户添加可以设定所属部门、职位、权限等信息。除了必填参数，其他参数可以先不填，日后可在后台编辑修改。
使用示例
 
public function addUser()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao = new \zentao();
    $params = array(
        'dept'      => 1,
        'account'   => 'Jack10',
        'password1' => '123456',
        'password2' => '123456',
        'realname'  => 'Jack10',
        'join'      => '2019-11-11',
        'role'      => 'dev',
        'group'     => 2,
        'email'     => 'jack2019@gmail.com',
        'commiter'  => 'http://jack2019.com',
        'gender'    => 'm'
    );    // 请求参数
    $result = $zentao->addUser($params);
    return $result;
}
请求方式
 POST
方法名称
 addUser
请求参数
参数名称
 参数类型
 是否必填
 参数描述
dept
 int 选填参数 所属部门【部门ID】
account
 string 必填参数 用户名
password1
 string 必填参数 密码
password2
 string
 必填参数
 重复密码
realname
 string 必填参数 真实姓名
join
 string 选填参数
 入职日期【格式：2019-11-19】
role string 选填参数 职位【权限标识，例如：'dev','qd'】
group int 选填参数 权限分组【分组ID】
email string 选填参数 邮箱
commiter
 string 选填参数 源代码账号
gender string 选填参数 性别【m:男|f:女】

响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": "保存成功"
}

 
{
    "status": 0,
    "msg": "error",
    "result": {
        "account": [
            "『用户名』已经有『ly0011』这条记录了。如果您确定该记录已删除，请到后台-数据-回收站还原。"
        ]
    }
}

 4.6获取产品列表

方法说明 请求此方法，可以获取所有未关闭的产品详情信息和所有产品名称。
使用示例
 
public function getProductList()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $extraFields = array('title', 'products', 'productStats');    // 自定义返回字段
    $result      = $zentao->getProductList(array(), $extraFields);
    return $result;
}
请求方式
 GET
方法名称
 getProductList
请求参数
参数名称
 参数类型
 是否必填
 参数描述
无需传参


响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
        //当前禅道项目导航位置
        "title": "全部产品",
        //所有产品列表名称
        "products": {
            "1": "禅道项目管理系统",
            "2": "产品二",
            "3": "产品三",
            "4": "产品四",
            "5": "产品五",
            "6": "产品六"
        },
        //未关闭产品列表详情
        "productStats": [
            {
                "id": "6",//产品ID
                "name": "产品六",//产品名称
                "code": "cp6",//产品代号
                "line": "0",//产品线
                "type": "branch",//产品类型【normal正常|branch多分支|platform多平台】
                "status": "normal",//产品状态
                "subStatus": "",
                "desc": "产品六产品六产品六产品六产品六产品六产品六产品六",//产品描述
                "PO": "lisi",//产品负责人
                "QD": "zhapliu",//测试负责人
                "RD": "zhapliu",//发布负责人
                "acl": "open",//访问控制【open默认|private私有|custom白名单】
                "whitelist": "",//访问白名单列表
                "createdBy": "admin",//创建者账号
                "createdDate": "2019-11-19 18:41:02",//创建者时间
                "createdVersion": "11.6.4",//禅道当前版本
                "order": "30",//排序
                "deleted": "0",//是否删除【0否1是】
                "stories": {
                    "0": "",
                    "1": "draft",
                    "2": "active",
                    "3": "closed",
                    "4": "changed",
                    "_empty_": 0,
                    "draft": 0,//草稿需求
                    "active": 0,//激活需求
                    "closed": 0,//已关闭需求
                    "changed": 0//已变更需求
                },
                "plans": 0,//计划数
                "releases": 0,//发布数
                "bugs": 0,//Bug数
                "unResolved": 0,//未解决Bug
                "assignToNull": 0//未指派Bug
            }
        ]
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.7添加单个产品可选信息

方法说明

请求此方法，可以获取添加产品时所需要一些数据，例如产品线数据列表、产品负责人数据列表等数据，添加产品时，可以为其绑定这些信息。
使用示例
 
public function getProductCreateParams()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $extraFields = array('title', 'products', 'lines', 'poUsers', 'qdUsers', 'rdUsers', 'groups');    //自定义返回字段
    $result      = $zentao->getProductCreateParams(array(), $extraFields);
    return $result;
}
请求方式
 GET
方法名称

getProductCreateParams
请求参数
参数名称
 参数类型
 是否必填
 参数描述
无需传参


响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
         //当前禅道项目导航位置
        "title": "添加产品",
        //已添加的产品列表
        "products": {
            "1": "禅道项目管理系统-PHP-SDK",
            "2": "产品二",
            "3": "产品三",
            "4": "产品四",
            "5": "产品五",
            "6": "产品六"
        },
        //产品线列表
        "lines": {
            "0": "",
            "5": "产品线一",
            "6": "产品线二",
            "7": "产品线三"
        },
        //产品负责人列表
        "poUsers": {
            "_empty_": "",
            "zhangsan": "Z:张三",
            "admin": "A:admin",
            "lisi": "L:李四",
            "niuqi": "N:牛七",
            "wangwu": "W:王五",
            "zhapliu": "Z:赵六"
        },
        //测试负责人列表
        "qdUsers": {
            "_empty_": "",
            "zhapliu": "Z:赵六",
            "admin": "A:admin",
            "lisi": "L:李四",
            "niuqi": "N:牛七",
            "wangwu": "W:王五",
            "zhangsan": "Z:张三"
        },
        //发布负责人列表
        "rdUsers": {
            "_empty_": "",
            "wangwu": "W:王五",
            "zhapliu": "Z:赵六",
            "lisi": "L:李四",
            "admin": "A:admin",
            "niuqi": "N:牛七",
            "zhangsan": "Z:张三"
        },
        //分组白名单列表
        "groups": {
            "1": "管理员",
            "2": "研发",
            "3": "测试",
            "4": "项目经理",
            "5": "产品经理",
            "6": "研发主管",
            "7": "产品主管",
            "8": "测试主管",
            "9": "高层管理",
            "10": "其他",
            "11": "guest",
            "12": "受限用户"
        }
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.8添加单个产品

方法说明

请求此方法，可以新增一个新产品，添加新产品时可以指定相关负责人，设置产品类型和访问权限。注意：假如 acl = custom ,可以额外传递参数,例如：'whitelist' => array(1, 2),添加白名单为权限分组列表中 ID。
使用示例 
public function addProduct()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao = new \zentao();
    $params = array(
        'name'         => 'product-200',
        'code'         => 'p200',
        'line'         => 0,
        'PO'           => 'lisi',
        'QD'           => 'zhangsan',
        'RD'           => 'wangwu',
        'type'         => 'normal',
        'status'       => 'normal',
        'desc'         => 'product description,product description',
        'acl'          => 'custom',
        'whitelist'    => array(1, 2)
    );    // 请求参数
    $result = $zentao->addProduct($params);
    return $result;
}
请求方式 POST
方法名称

addProduct
请求参数
参数名称 参数类型 是否必填 参数描述
name
 string 必填参数 产品名称
code
 string 必填参数 产品代号
line
 int 选填参数 产品线ID
PO
 string 选填参数 产品负责人账号
QD
 string 选填参数 测试负责人账号
RD
 string 选填参数 发布负责人账号
type
 string 选填参数 产品类型【normal正常|branch多分支|platform多平台】
desc string 选填参数 产品描述
acl
 string 选填参数 访问控制【open默认|private私有|custom白名单】
whitelist array 选填参数 白名单，权限分组列表中 ID
响应结果
 success error 
{  "status": 1,
    "msg": "success",
    "result": "保存成功"
}
 
{
    "status": 0,
    "msg": "error",
    "result": {
        "name": [
            "『产品名称』不能为空。"
        ]
    }
}

 4.9获取项目列表

方法说明 请求此方法，可以根据项目不同状态获取项目列表。
使用示例 
public function getProjectList()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $params      = array('status' => 'doing');    // 请求参数
    $extraFields = array('title', 'projects', 'projectStats', 'teamMembers', 'users');    // 自定义返回字段
    $result      = $zentao->getProjectList($params, $extraFields);
    return $result;
}
请求方式 GET
方法名称 getProjectList
请求参数
参数名称 参数类型 是否必填 参数描述
status
 string 选填参数 项目状态【all:所有|undone:未完成|wait:未开始|doing:进行中|suspended:已挂起|closed:已关闭】
响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
         //当前禅道项目导航位置
        "title": "所有项目",
        //项目名称列表
        "projects": {
            "1": "禅道系统 PHP-SDK 开发",
            "2": "淘宝项目开发",
            "3": "天猫项目开发"
        },
        //项目详情列表
        "projectStats": [
            {
                "id": "1",//项目ID
                "isCat": "0",
                "catID": "0",
                "type": "sprint",//项目类型【sprint短期项目|waterfall长期项目|ops运维项目】
                "parent": "0",
                "name": "禅道系统 PHP-SDK 开发",//项目名称
                "code": "002",//项目代号
                "begin": "2019-11-11",//起始日期
                "end": "2019-11-23",//起始日期
                "days": "10",//可用工作日
                "status": "doing",//项目状态【all所有|undone未完成|wait未开始|doing进行中|suspended已挂起|closed已关闭】
                "subStatus": "",
                "statge": "1",
                "pri": "1",
                "desc": "开发禅道项目管理系统 PHP-SDK 的开发，用于 PHPer 高效便捷的进行项目管理。",//项目描述
                "openedBy": "admin",//创建者
                "openedDate": "2019-11-11 15:24:14",//创建时间
                "openedVersion": "11.6.4",//禅道版本
                "closedBy": "",//关闭者
                "closedDate": "0000-00-00 00:00:00",//关闭时间
                "canceledBy": "",//取消者
                "canceledDate": "0000-00-00 00:00:00",//取消时间
                "PO": "zhangsan",//产品负责人
                "PM": "niuqi",//项目负责人
                "QD": "admin",//测试负责人
                "RD": "lisi",//发布负责人
                "team": "禅道开发",//团队名称
                "acl": "open",//访问控制【open默认|private私有|custom自定义白名单】
                "whitelist": "",//白名单列表
                "order": "5",//排序数
                "deleted": "0",
                "burns": [//燃尽图数据
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    "28"
                ],
                "hours": {
                    "totalEstimate": 28,//预计时间（小时）
                    "totalConsumed": 21,//消耗时间（小时）
                    "totalLeft": 28,//剩余时间（小时）
                    "progress": 42.9,//进度（百分比）
                    "totalReal": 49
                }
            } ],
        //团队成员列表信息
        "teamMembers": {
            "admin": {
                "id": "9",
                "root": "2",
                "type": "project",
                "account": "admin",
                "role": "",
                "limited": "no",
                "join": "2019-11-20",
                "days": "8",
                "hours": "7.0",
                "estimate": "0.00",
                "consumed": "0.00",
                "left": "0.00",
                "order": "0",
                "totalHours": "56.0",
                "realname": "admin"
            },
            "niuqi": {
                "id": "11",
                "root": "2",
                "type": "project",
                "account": "niuqi",
                "role": "其他",
                "limited": "no",
                "join": "2019-11-20",
                "days": "8",
                "hours": "7.0",
                "estimate": "0.00",
                "consumed": "0.00",
                "left": "0.00",
                "order": "0",
                "totalHours": "56.0",
                "realname": "牛七"
            },
            "wangwu": {
                "id": "12",
                "root": "2",
                "type": "project",
                "account": "wangwu",
                "role": "研发",
                "limited": "no",
                "join": "2019-11-20",
                "days": "8",
                "hours": "7.0",
                "estimate": "0.00",
                "consumed": "0.00",
                "left": "0.00",
                "order": "0",
                "totalHours": "56.0",
                "realname": "王五"
            },
            "zhapliu": {
                "id": "10",
                "root": "2",
                "type": "project",
                "account": "zhapliu",
                "role": "测试",
                "limited": "no",
                "join": "2019-11-20",
                "days": "8",
                "hours": "7.0",
                "estimate": "0.00",
                "consumed": "0.00",
                "left": "0.00",
                "order": "0",
                "totalHours": "56.0",
                "realname": "赵六"
            }
        },
        //用户列表信息
        "users": {
            "_empty_": "",
            "admin": "admin",
            "lisi": "李四",
            "niuqi": "牛七",
            "wangwu": "王五",
            "zhangsan": "张三",
            "zhapliu": "赵六",
            "closed": "Closed"
        }
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.10添加单个项目可选信息

方法说明

请求此方法，获取正常状态产品列表信息，用于添加项目时为其绑定产品，从而用于项目与产品需求关联。还可获取权限分组列表，用于项目绑定访问控制权限。
使用示例 
public function getProjectCreateParams()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $extraFields = array('title', 'projects', 'groups', 'allProducts');
    $result      = $zentao->getProjectCreateParams(array(), $extraFields);    // 自定义返回字段
    return $result;
}
请求方式 GET
方法名称

getProjectCreateParams
请求参数
参数名称 参数类型 是否必填 参数描述
无需传参


响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
         //当前禅道项目导航位置
        "title": "添加项目",
        //已添加的项目列表
        "projects": {
            "1": "禅道系统 PHP-SDK 开发",
            "2": "淘宝项目开发",
            "3": "天猫项目开发",
            "_empty_": ""
        },
        //权限分组列表
        "groups": {
            "1": "管理员",
            "2": "研发",
            "3": "测试",
            "4": "项目经理",
            "5": "产品经理",
            "6": "研发主管",
            "7": "产品主管",
            "8": "测试主管",
            "9": "高层管理",
            "10": "其他",
            "11": "guest",
            "12": "受限用户"
        },
        //可关联产品列表
        "allProducts": {
            "0": "",
            "1": "禅道项目管理系统-PHP-SDK",
            "2": "产品二",
            "4": "产品四",
            "5": "产品五",
            "6": "产品六",
            "9": "产品100"
        }
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.11添加单个项目

方法说明

此方法用于新增一个新产品，添加新产品时可以指定相关负责人，设置产品类型和访问权限。

  • 注意点一：假如 acl = custom ，可额外传递参数，例如：'whitelist' => array(1, 2) ，代表访问白名单中的权限分组 ID。
  • 注意点二：关联一个或者多个产品时额外传参字段，例如：'products' => array(4, 5)，代表同时关联产品 ID 等于 4 和 5 的产品。
  • 注意点三：关联一个或者多个计划时额外传参字段，例如： 'plans' => array(5, 6)，代表关联产品 ID 等于4 下的计划 ID 等于 5 的计划，关联产品 ID 等于5 下计划 ID 等于 6 的计划。
使用示例
 
public function addProject()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao = new \zentao();
    $params = array(
        'name'        => '禅道项目管理开发',
        'code'        => 'zentao',
        'begin'       => '2020-01-01',
        'end'         => '2020-06-06',
        'days'        => '100',
        'team'        => '禅道开发团队',
        'type'        => 'sprint',
        'status'      => 'wait',
        'products[0]' => 0,
        'plans[0]'    => 0,
        'desc'        => '禅道是专业的研发项目管理软件。',
        'acl'         => 'custom',
        'whitelist'   => array(1, 2),
        'products'    => array(4, 5),
        'plans'       => array(5, 6)
    );    // 请求参数
    $result = $zentao->addProject($params);
    return $result;
}
请求方式
 POST
方法名称

addProject
请求参数
参数名称
 参数类型
 是否必填
 参数描述
name
 string 必填参数
 项目名称
code
 string
 必填参数
 项目代号
begin
 string
 必填参数
 起始日期【时间格式：2019-11-20】
end
 string
 必填参数
 结束日期【时间格式：2019-11-20】
days
 int
 选填参数
 可用工作日
team
 string
 选填参数
 团队名称
type
 string
 选填参数
 项目类型【sprint短期项目|waterfall长期项目|ops运维项目】
desc
 string
 选填参数
 项目描述
acl
 string
 选填参数
 访问控制【open默认设置|private私有项目|custom白名单】
whitelist array 选填参数
 白名单中的权限分组 ID
products
 array
 选填参数
 关联产品 ID
plans
 array
 选填参数
 关联产品 ID 所属计划 ID
响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": "保存成功"
}
 
{
    "status": 0,
    "msg": "error",
    "result": {
        "name": [
            "『项目名称』已经有『禅道项目开发』这条记录了。如果您确定该记录已删除，请到后台-数据-回收站还原。"
        ],
        "code": [
            "『项目代号』已经有『zentao』这条记录了。如果您确定该记录已删除，请到后台-数据-回收站还原。"
        ]
    }
}

 4.12获取任务列表

方法说明 调用此方法可以过去某个项目下不同状态的任务列表。注意：排序方式降序排序，把 asc 修改为 desc 即可。
使用示例
 
public function getTaskList()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $params      = array('projectID' => 1, 'status' => 'all', 'orderBy' => 'pri_asc');    // 请求参数
    $extraFields = array('title', 'projects', 'project', 'products', 'tasks');    //自定义返回字段
    $result      = $zentao->getTaskList($params, $extraFields);
    return $result;
}
请求方式
 GET
方法名称

getTaskList
请求参数
参数名称
 参数类型
 是否必填
 参数描述
projectID
 int 必填参数 项目ID
status
 string
 选填参数
 任务状态【all所有|unclosed未关闭|assignedtome指派给我|myinvolved由我参与|delayed已延期|needconfirm需求变更|wait未开始|doing进行中|undone未完成|finishedbyme我完成|done已完成|closed已关闭|cancel已取消】
orderBy
 string
 选填参数
 选填参数|排序方式【name_asc名称升序|pri_asc重要度升序|estimate_asc预计时间升序|consumed_asc消耗时间升序】
响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
        //当前禅道项目导航位置
        "title": "禅道系统 PHP-SDK 开发-任务列表",
        //已添加项目名称列表
        "projects": {
            "1": "禅道系统 PHP-SDK 开发"
        },
        //当前项目详情信息【可参考获取项目列表中的描述】
        "project": {
            "id": "1",
            "isCat": "0",
            "catID": "0",
            "type": "sprint",
            "parent": "0",
            "name": "禅道系统 PHP-SDK 开发",
            "code": "002",
            "begin": "2019-11-11",
            "end": "2019-11-23",
            "days": "10",
            "status": "doing",
            "subStatus": "",
            "statge": "1",
            "pri": "1",
            "desc": "开发禅道项目管理系统 PHP-SDK 的开发，用于 PHPer 高效便捷的进行项目管理。",
            "openedBy": "admin",
            "openedDate": "2019-11-11 15:24:14",
            "openedVersion": "11.6.4",
            "closedBy": "",
            "closedDate": "0000-00-00 00:00:00",
            "canceledBy": "",
            "canceledDate": "0000-00-00 00:00:00",
            "PO": "zhangsan",
            "PM": "niuqi",
            "QD": "admin",
            "RD": "lisi",
            "team": "禅道开发",
            "acl": "open",
            "whitelist": "",
            "order": "5",
            "deleted": "0",
            "totalHours": "420.0",
            "totalEstimate": 28,
            "totalConsumed": 25,
            "totalLeft": 0
        },
        //关联的产品列表信息
        "products": {
            "1": {
                "id": "1",
                "name": "禅道项目管理系统-PHP-SDK",
                "type": "normal",
                "branch": "0",
                "plan": "0"
            }
        },
        //此项目下任务列表信息
        "tasks": {
            "1": {
                "id": "1",//任务ID
                "parent": "0",
                "project": "1",//所属项目ID
                "module": "1",//所属模块ID
                "story": "1",
                "storyVersion": "1",
                "fromBug": "0",
                "name": "确认禅道PHP-SDK需求，创建PHP-SDK文件 ",//任务名称
                "type": "design",//任务类型
                "pri": "1",
                "estimate": "4",
                "consumed": "6",
                "left": "0",
                "deadline": "2019-11-11",
                "status": "done",
                "subStatus": "",
                "color": "",
                "mailto": "",
                "desc": "创建 zentao.sdk.class 文件，做好基本的用户认证，分析需求，开始进行功能开发。",//任务描述
                "openedBy": "admin",//创建者
                "openedDate": "2019-11-11 15:29:27",//创建时间
                "assignedTo": "admin",
                "assignedDate": "2019-11-20 15:30:15",
                "estStarted": "2019-11-11",
                "realStarted": "2019-11-11",
                "finishedBy": "admin",
                "finishedDate": "2019-11-20 15:30:15",
                "finishedList": "",
                "canceledBy": "",
                "canceledDate": "0000-00-00 00:00:00",
                "closedBy": "",
                "closedDate": "0000-00-00 00:00:00",
                "closedReason": "",
                "lastEditedBy": "admin",
                "lastEditedDate": "2019-11-20 15:30:15",
                "deleted": "0",
                "storyID": "1",
                "storyTitle": "确认禅道PHP-SDK需求，创建PHP-SDK文件",
                "product": "1",
                "branch": "0",
                "latestStoryVersion": "1",
                "storyStatus": "active",
                "assignedToRealName": "admin",
                "needConfirm": false,
                "productType": "normal",
                "progress": 100
            }
        }
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.13添加单个任务可选信息

方法说明

添加单个任务时，可以先通过此方法，获取添加任务中所需要的相关信息。
使用示例
 
public function getTaskCreateParams()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $params      = array('project' => 1);    // 请求参数
    $extraFields = array('title', 'projects', 'users', 'stories', 'moduleOptionMenu', 'project');    // 自定义返回字段
    $result      = $zentao->getTaskCreateParams($params, $extraFields);
    return $result;
}
请求方式
 GET
方法名称

getTaskCreateParams
请求参数
参数名称
 参数类型
 是否必填
 参数描述
project
 int 必填参数 项目ID
响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
        //当前禅道项目导航位置
        "title": "禅道系统 PHP-SDK 开发-建任务",
        //所有项目名称列表
        "projects": {
            "1": "禅道系统 PHP-SDK 开发"
        },
        //可选用户列表【可用于指派和抄送】
        "users": {
            "_empty_": "",
            "admin": "A:admin",
            "lisi": "L:李四",
            "niuqi": "N:牛七",
            "wangwu": "W:王五",
            "zhangsan": "Z:张三",
            "zhapliu": "Z:赵六"
        },
        //该项目下的需求【可用于关联需求】
        "stories": {
            "1": "1:确认禅道PHP-SDK需求，创建PHP-SDK文件 (优先级:1,预计工时:4)",
            "2": "2:开发禅道SDK功能接口 (优先级:1,预计工时:24)",
            "_empty_": ""
        },
        //该项目所属模块列表【用于绑定所属模块】
        "moduleOptionMenu": [
            "/",
            "/设计",
            "/开发"
        ],
        //当前项目信息【描述参考 2.7 获取项目列表】
        "project": {
            "id": "1",
            "isCat": "0",
            "catID": "0",
            "type": "sprint",
            "parent": "0",
            "name": "禅道系统 PHP-SDK 开发",
            "code": "002",
            "begin": "2019-11-11",
            "end": "2019-11-23",
            "days": "10",
            "status": "doing",
            "subStatus": "",
            "statge": "1",
            "pri": "1",
            "desc": "开发禅道项目管理系统 PHP-SDK 的开发，用于 PHPer 高效便捷的进行项目管理。",
            "openedBy": "admin",
            "openedDate": "2019-11-11 15:24:14",
            "openedVersion": "11.6.4",
            "closedBy": "",
            "closedDate": "0000-00-00 00:00:00",
            "canceledBy": "",
            "canceledDate": "0000-00-00 00:00:00",
            "PO": "zhangsan",
            "PM": "niuqi",
            "QD": "admin",
            "RD": "lisi",
            "team": "禅道开发",
            "acl": "open",
            "whitelist": "",
            "order": "5",
            "deleted": "0",
            "totalHours": "420.0",
            "totalEstimate": 28,
            "totalConsumed": 25,
            "totalLeft": 0
        }
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.14添加单个任务

方法说明

请求此方法，用于新增一个任务，新增任务的同时可以绑定所属项目、指派给某用户、设定优先级等相关信息。
使用示例
 
public function addTask()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao = new \zentao();
    $params = array(
        'project'          => 1,
        'type'             => 'ui',
        'module'           => 0,
        'assignedTo[]'     => 'lisi',
        'testAssignedTo[]' => 'lisi',
        'color'            => '',
        'name'             => '测试添加任务2',
        'pri'              => 2,
        'estimate'         => 1,
        'desc'             => '测试添加任务描述测试添加任务描述',
        'estStarted'       => '2019-11-11',
        'deadline'         => '2019-11-12',
        'mailto[1]'        => 'lisi'
    );    // 请求参数
    $result = $zentao->addTask($params);
    return $result;
}
请求方式
 POST
方法名称

addTask
请求参数
参数名称
 参数类型
 是否必填
 参数描述
project
 int 必填参数 所属项目ID
type
 string
 必填参数 任务类型【design设计|devel开发|test测试|study研究|discuss讨论|ui界面|affair事务|misc其他】
module
 int 选填参数
 所属模块ID
color
 string
 选填参数
 任务颜色【示例：#ff4e3e】
name
 string
 必填参数 任务名称
pri
 int 选填参数
 优先级【分为 1、2、3、4级】
estimate
 int 选填参数
 预计时间【小时】
desc
 string
 选填参数
 任务描述
estStarted
 string
 选填参数
 日程规划开始【格式：2019-11-20】
deadline
 string
 选填参数
 日程规划结束【格式：2019-11-28】
assignedTo
 array
 选填参数
 指派用户，示例：'assignedTo' => array('zhangsan')
mailto
 array 选填参数
 抄送用户，示例：'mailto' => array('lisi', 'niuqi', 'zhangsan'), 代表同时抄送给 3 个用户。
响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": "保存成功"
}
 
{
    "status": 0,
    "msg": "error",
    "result": {
        "name": [
            "『任务名称』不能为空。"
        ]
    }
}



杨苗
高级客户经理
13165050229
2692096539
统一服务热线 4006-8899-23
我要提问提问有任何问题，您都可以在这里提问。 问题反馈反馈点击这里，让我们聆听您的建议与反馈。