NAV
json

斑马服务器(server)

地址

  1. 正式环境:https://zpert.com
  2. 外网可访问的测试环境:https://b.zpert.com,此环境已和数字项目集成管理平台打通,如需从数字项目集成管理平台同步数据到斑马,请使用此环境
  3. 内网测试环境:https://dev.zpert.com

斑马进度资源授权(authorization-resource)

单点登录(sso)

斑马进度提供第三方应用基于广联达用户中心单点登录斑马进度的机制,第三方应用可直访问斑马进度网站页面地址,对于最终能否正确访问到预期页面,斑马进度还会判断登录用户在斑马中是否有访问资源的权限。如权限正确则会展现预期页面,如权限不正确则会有对应错误提示。

单点登录访问斑马进度页面

第三方应用授权(app-auth)

首先,在斑马进度网站创建第三方应用获取应用的client_idclient_secret;使用access token访问/open资源下的页面;使用接口参数签名的方式访问斑马进度API。如果仅仅过网关访问斑马进度API,则可忽略本章文档。 详细信息如下:

创建第三方应用

  1. 在斑马进度的网站中添加第三方应用(企业--设置--第三方应用),点击新建应用按钮,输入应用名称完成第三方应用创建。完成应用创建后就可以拿到client_idclient_secret,选中应用授权中组织的根节点添加管理员权限。
  2. 新建第三方应用示例图
  3. 添加管理员示例图
  4. 第三方应用可创建多了,可只用其中的一个或多个。

获取access token

获取access token

使用access token访问斑马进度页面

签名算法

签名算法(signature)

签名算法(signature)

获取access_token接口签名

生成获取access_token接口专用签名方式

签名参数列表

签名参数 是否必须 描述
grant_type 值固定为:client_credentials
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串
client_secret 应用的 client_secret

获取client_id&client_secret

签名算法

  1. grant_type, client_id, timestamp, nonce按名称升序排列
  2. 将每个参数与参数对应的值组成的字符串(例如 'grant_type=xxxxx'), 用'&'连接成一个字符串str
  3. 在str的前后加入client_secret,组成一个新的字符串
  4. 对新字符串做32位md5处理, 取32位小写的结果作为 signature

Ruby实现

  #源码
  require "rest-client"
  require "json"
  require "pry"
  require "uuid"

  client_id = '3245d490f4160138fc74245e60d8aead'
  client_secret = '46fba050f4160138fc74245e60d8aead'

  uuid = UUID.new
  uuid_str = uuid.generate
  timestamp = Time.now.to_i
  params = {
    grant_type: "client_credentials",
    client_id: client_id,
    timestamp: timestamp,
    nonce: uuid_str
  }

  puts params

  str = params.keys.sort.map{|k| "#{k}=#{params[k]}"}.join('&')
  str = "#{client_secret}#{str}#{client_secret}"
  puts str
  signature = Digest::MD5.hexdigest(str)
  puts signature

  # 示例
  签名参数:
  grant_type = "client_credentials"
  client_id = "3245d490f4160138fc74245e60d8aead"
  client_secret = "46fba050f4160138fc74245e60d8aead"
  timestamp = "1603099304"
  nonce = "6dc78060-f41a-0138-fc77-245e60d8aead"

  待签字符串:
  46fba050f4160138fc74245e60d8aeadclient_id=3245d490f4160138fc74245e60d8aead&grant_type=client_credentials&nonce=6dc78060-f41a-0138-fc77-245e60d8aead&timestamp=160309930446fba050f4160138fc74245e60d8aead

  签名结果:
  dd39886dc8b83dac1b5331f818877180

其他接口签名(other)

除获取access_token接口之外的其他接口生成签名的算法

签名参数列表

签名参数 是否必须 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串
client_secret 应用的 client_secret

获取client_id&client_secret

签名算法

  1. client_id, timestamp, nonce按名称升序排列
  2. 将每个参数与参数对应的值组成的字符串(例如 'client_id=xxxxx'), 用'&'连接成一个字符串str
  3. 在str的前后加入client_secret,组成一个新的字符串
  4. 对新字符串做32位md5处理, 取32位小写的结果作为 signature

Ruby实现

  # 源码
  require "rest-client"
  require "json"
  require "pry"
  require "uuid"

  client_id = '3245d490f4160138fc74245e60d8aead'
  client_secret = '46fba050f4160138fc74245e60d8aead'

  uuid = UUID.new
  uuid_str = uuid.generate
  timestamp = Time.now.to_i
  params = {
    client_id: client_id,
    timestamp: timestamp,
    nonce: uuid_str
  }

  str = params.keys.sort.map{|k| "#{k}=#{params[k]}"}.join('&')
  str = "#{client_secret}#{str}#{client_secret}"
  puts str
  signature = Digest::MD5.hexdigest(str)
  puts signature

  # 示例
  client_id = "3245d490f4160138fc74245e60d8aead"
  client_secret = "46fba050f4160138fc74245e60d8aead"
  timestamp = "1603097721"
  nonce = "be2ed1d0-f416-0138-fc76-245e60d8aead"

  待签字符串:

  46fba050f4160138fc74245e60d8aeadclient_id=3245d490f4160138fc74245e60d8aead&nonce=be2ed1d0-f416-0138-fc76-245e60d8aead&timestamp=160309772146fba050f4160138fc74245e60d8aead

  签名结果:
  f49b8ac3d9651fc2dd8cdd09dea3f75f

Access token

获取access token

access token用于访问斑马内嵌页面等资源。

HTTP Request

POST /api/v2/oauth/token

Query参数

参数名称 是否必选 描述
grant_type 值固定为:client_credentials
client_id 应用的 uid
p_id 斑马计划的id要
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

  {
    "code":0,
    "access_token":"f6c87fb84bc872f92f519a41204180d15658bcdee014e3387a1ad9abfbd70d43",
    "token_type":"Bearer",
    "expires_in":7200,
    "created_at":1543372633
  }

失败返回结果:

  // 请求不在60秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

  // 其他一些错误,例如grant_type错误等
  {"code":6,"message":"服务器不支持此类型的授权方式"}

API V2

企业(Company)接口

获取企业信息

HTTP Request

GET /api/v2/companies/info

Query参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code":0,
  "data":
    {
      "company":
        {
          "id": 3,        // 企业id
          "name": "xxxx"  // 企业名称
        }
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

计划(Project)接口

获取企业下所有计划

HTTP Request

GET /api/v2/company_projects

Query参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code":0,
  "data":
    {
      "company_projects":
        [
          {
            "id":61, // 计划id
            "name":"6666", // 计划名称
            "company_catalog": // 计划归属的目录或项目
              {
                "id":215, // 目录或项目的id
                "name":"项目b", // 目录或项目的名称
                "folder":false // true代表是目录, false代表是项目
                "cloudt_project_id": "336969852666368" //数字项目集成管理平台项目id
              }
          }
        ]
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

获取计划详情

HTTP Request

GET /api/v2/company_projects/:id

Path 参数

参数名称 是否必选 描述
id 斑马计划id

Query 参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
mt_size 里程碑数量,不需要参加 signature 的计算,当 mt_size = -1 时,会返回所有进行中的里程碑数据,当 mt_size = 0 或者不存在时,不返回里程碑数据,当 mt_size > 0 时,返回小于等于指定数量的里程碑数据
signature 签名

成功返回结果:

{
  "code":0,
  "data":
    {
      "id":73, // 计划id
      "user_name":"xx", // 负责人名称
      "name":"住一黑庄户", // 计划名称
      "uploaded_at":1500974424, // 计划建立时间
      "last_uploaded_at":1533629696, // 计划上次更新时间
      "ask_start_time":1486915200, // 计划要求开始时间
      "ask_stop_time":1534348800, // 计划要求结束时间
      "ask_duration":549, // 计划要求工期天数
      "real_start_time":1533484800, // 计划实际开始时间, 可能不存在
      "real_stop_time":null, // 计划实际结束时间, 可能不存在
      "real_duration":null, //计划实际工期, 可能不存在
      "plan_start_time":1486915200, // 计划预计开始时间
      "plan_stop_time":1534348800, // 计划预计结束时间
      "plan_duration": 12.0, // 计划工期
      "estimate_start_time":1486915200, // 计划估计开始时间
      "estimate_stop_time":1534348800, // 计划估计结束时间
      "forward_line_unix": 1534348800, // 最新的里程碑时间
      "offset": 12.0, // 计划预测偏差天数,小于零超期,大于零提前,等于零按时完成
      "milestones":[ // 里程碑数据
        {
          "id": 1,  // 里程碑id
          "name": "xxx",  // 里程碑名称
          "rank": 1,      // 里程碑等级
          "ask_stop_time": 1499235885, // 要求结束时间
          "plan_start_time": 1499235885, // 预计开始
          "plan_stop_time": 1499235885, // 预计结束
          "estimate_start_time": 1499235885, // 估计开始
          "estimate_stop_time": 1499235885, // 估计结束
          "real_start_time": 1499235885, // 实际开始
          "real_stop_time": 1499235885 // 实际结束
          "offset": 12.0 // 计划预测偏差天数,小于零超期,大于零提前,等于零按时完成
        }
      ]
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

项目(Catalog)接口

获取企业组织结构

HTTP Request

GET /api/v2/company_catalogs

Query 参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code":0,
  "data":
    {
      "company_catalog":
        {
          "id": 3,            // 目录id
          "parent_id": null,  // 目录的父id,根节点的父id为空
          "name": "xx集团",    // 目录名称
          "status": "",       // 项目状态
          "default_company_project_id": null, // 项目的主控计划id
          "desc": null,       // 描述
          "folder": true,     // 是否是目录,目录:true,项目:false
          "tags": "",         // 标签
          "catalog_no": "E1BFBF2998A7561F07F6F28E", // 编号
          "establish_time": null,// 立项时间,unix时间戳
          "children": [
            {
              "id": 3519,
              "parent_id": 3,
              "name": "模板库",
              "status": "未开始",
              "default_company_project_id": null,
              "desc": null,
              "folder": false,
              "tags": "",
              "catalog_no": "__TEMPLATE_ITEM__",
              "establish_time": 1554816484
            },
            {
              "id": 3387,
              "parent_id": 3,
              "name": "已完成项目",
              "status": "",
              "default_company_project_id": null,
              "desc": null,
              "folder": true,
              "tags": "",
              "catalog_no": "__DONE_FOLDER__",
              "establish_time": null,
              "children": []
            }
          ]
        }
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

获取项目列表

HTTP Request

GET /api/v2/company_catalogs/company_items

Query 参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名
catalog_name 组织名称
catalog_code 项目编码
min_duration_offset 最小偏差天数
max_duration_offset 最大偏差天数

成功返回结果:

{
  "code":0,
  "data":
    {
      "company_catalogs":
        [
          {
            "id": 124,              // 项目id
            "cloudt_project_id": "336969852666368", //数字项目集成管理平台项目id
            "parent_id": 86,        // 父目录id
            "name": "轨道北京地铁7号线东延工程土建施工02合同段",
            "status": "进行中",      // 状态
            "default_company_project_id": null, // 主控计划id,当不存在时,默认取了项目下第一个计划
            "desc": "",
            "folder": false,
            "tags": "地铁",
            "catalog_no": "D29C406EA630378F6D00DFE3",
            "establish_time": 1514525385, // 立项时间,unix时间戳
            "manage_status": 1,  // 0 未及时上传,1 暂未上传,2 前锋线未及时更新 上周一之前,3 前锋线已及时更新 上周一之后
            "emphasis": false,  // 是否重点项目
            "plan_info": {                // 主控计划信息
              "root": {                   // 整个计划的信息
                "name": "项目结束",        // root的name都是'项目结束'
                "ask": 1569686400,        // 要求完成时间,unix时间戳
                "estimate": null,         // 预测完成时间,unix时间戳
                "status": null            // 自然日数,小于零时是超期,大于零时是提前,等于零是按时完成
              },
              "milestone0": null,         // 近期里程碑1
              "milestone1": null,         // 近期里程碑2
              "milestone2": null          // 近期里程碑3
            }
          }
        ],
        "statistics_catalogs": [1, 2, 3] // 统计项目id数组
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

获取项目信息

HTTP Request

GET /api/v2/company_catalogs/:id/company_item

Query 参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code":0,
  "data":
    {
      "company_projects":     // 项目下的计划
        [
            {
              "id": 3801,     // 计划id
              "name": "黑庄户住一项目部1#3#5#8#23#32#2018年12月份进度计划",  // 计划名称
              "plan_info":
                {
                  "forward_line_unix": 315504000  // 前锋线时间,unix时间戳
                }
            },
        ]
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

API V3

V3接口返回的时间皆为UTC时间

获取计划标准(standard)格式

HTTP Request

GET /api/v3/company_projects/:id/standard_data

Query 参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code": 0,
  "data": {
    ......
    "tasks": [                 // 计划工作项数组
      {
        "id": 0,
        "name": "test1",
        "rank": 1,
        "type": 0,
        "layer": 0,
        "level": 0,
        "depends": "",
        "end_dot": 7,
        "duration": 8092800,
        "begin_dot": 0,
        "draw_type": 2,
        "is_parent": true,
        "department": {},
        "is_keywork": true,
        "attachments": [],
        "depend_type": "FS",
        "forign_name": "The Pert Chart of Zebra Project",
        "source_count": {
          "plan": 1.0,
          "unit": "",
          "price": 0.0,
          "real_price": 0.0,
          "current_plan": 0.0,
          "contract_price": 0.0
        },
        "ask_stop_time": 1585872000,
        "auto_duration": true,
        "schedule_type": 0,
        "ask_start_time": 1585785600,
        "plan_stop_time": 1593878400,
        "work_style_idx": 1,
        "plan_start_time": 1585785600,
        "estimate_stop_time": 1593878400,
        "estimate_start_time": 1585785600,
        "is_typical_deviation": true
      }
    ],
    "groups": [],
    "legend": {
      "sDate": "2020-04-02",
      "width": 320,
      "height": 160,
      "visible": true,
      "position": 0,
      "script10": "\n  备注:",
      "script21": "项目负责人",
      "script22": "",
      "script31": "绘图人",
      "script32": "",
      "script41": "审核人",
      "script42": "",
      "script51": "校对人",
      "script52": "",
      "script61": "起始时间",
      "script62": "",
      "script71": "结束时间",
      "script72": "",
      "script81": "文件名",
      "script82": "",
      "script91": "总工期",
      "script92": "",
      "developer": "斑马·梦龙网络计划制作",
      "script11_1": "总工期(工日)",
      "show_symbol_list": [
        1
      ],
      "show_symbol_mode": 0,
      "is_show_script_10": true,
      "is_show_script_11": true,
      "is_show_catalog_name": true
    },
    "next_id": 15,
    "version": 2,
    "calendars": [
      {
        "id": 0,
        "name": "自然日",
        "work_periods": [
          [
            0,
            86400
          ]
        ]
      },
      {
        "id": 6,
        "name": "标准",
        "work_periods": [
          [
            0,
            86400
          ]
        ]
      }
    ],
    "count_time": 1585756800,
    "plan_state": 1,
    "progresses": [
      {
        "time": 1585785600,
        "notes": "",
        "is_display": true
      }
    ],
    "store_type": "zpert",
    "default_calendar_id": 6
    ......
  }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

获取计划计算(calculation)数据

HTTP Request

GET /api/v3/company_projects/:id/calculation_data

Query 参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code": 0,
  "data": {
    "tasks":
      [
        {
          "id": 0,                                //工作id
          "plan_duration_days": 41.0,             //计划工期天数(浮点)
          //计划变动分析计算结果(原工期差异 = 原计划工期天数 - 计划工期天数)
          "last_plan_start_diff_days": 0.0,       //原计划开始偏差天数(浮点)
          "last_plan_stop_diff_days": 0.0,        //原计划结束偏差天数(浮点)
          "last_plan_duration_days": 0.0,         //原计划工期天数(浮点)
          "change_details": "",                   //执行情况(计划变动)(字符串)
          "change_resolution": ""                 //解决措施(计划变动)(字符串)
          //进度对比分析计算结果(实际工期/剩余差异 = 实际工期/预计剩余天数 - 计划工期天数)
          "real_duration_days": 41.0,             //实际工期天数(浮点)
          "real_start_diff_days": 1.0,            //实际开始偏差天数(浮点)(由状态判断是否可能滞后)
          "real_stop_diff_days": 1.0,             //实际结束偏差天数(浮点)
          "plan_left_days": 40.0,                 //计划剩余天数(浮点)
          "predict_left_days" :  0.0              //预计剩余天数(浮点)
          "progress_details": "",                 //执行情况(进度对比)(字符串)
          "progress_resolution": "",              //解决措施(进度对比)(字符串)
        }
      ]
  }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

获取计划里程碑(milestone)数据

HTTP Request

GET /api/v3/company_projects/:id/milestones

Query 参数

参数名称 是否必选 描述
client_id 应用的 uid
timestamp 当前时间的 unix 值, 600 秒之内发送的请求视为有效的
nonce 随机生成的字符串,例如 uuid
signature 签名

成功返回结果:

{
  "code": 0,
  "data": {
    "tasks": [
        {
          "id": 0,                           //工作id
          "name": "0708",                    //工作名称
          "rank": 1,                         //里程碑等级
          "plan_delay_days": -33.0,          //提前或滞后天数(要求-计划)
          "estimate_delay_days": -33.0,      //提前或滞后天数(要求-预测)
          "plan_stop_time": 1589130000,      //计划完成时间
          "estimate_stop_time": 1589130000,  //预测完成时间
          "real_stop_time": 0,               //实际完成时间
          "ask_stop_time": 1586304000,       //要求完成时间
          "plan_duration_days": 34.0         //计划工期天数(浮点)(只有总任务存)
        }
      ]
    }
}

失败返回结果:

  // 请求不在600秒有效期之内
  {"code":1, "message":"请求过时"}

  // nonce重复
  {"code":2, "message":"执行过的请求"}

  // 包含非法字段,例如client_secret
  {"code":3, "message":"包含非法字段"}

  // 生成的signature错误
  {"code":4, "message":"signature错误"}

  // client_id错误
  {"code":5, "message":"由于未知、不支持或没有客户端,认证失败"}

内嵌斑马进度页面(embed-page)

单点登录的方式(sso)

计划详情页面

数字项目集成管理平台上注册产品

测试环境地址:https://xmgl-test.glodon.com/zpet/gateway

正式环境地址:https://xmgl.glodon.com/zpet/gateway

Http Method:GET

请求参数:

参数名称 是否必须 说明
access_path 值固定为:SNAP_COMPANY_PROJECT
cloudt_tenant_id 数字项目集成管理平台租户id
zpet_project_id 斑马计划id
hack_style 自定义样式(css)文件地址

示例:

测试环境地址:https://xmgl-test.glodon.com/zpet/gateway?access_path=SNAP_COMPANY_PROJECT&cloudt_tenant_id=123&zpet_project_id=789&hack_style=https://demo.com/a.css

正式环境地址:https://xmgl.glodon.com/zpet/gateway?access_path=SNAP_COMPANY_PROJECT&cloudt_tenant_id=123&zpet_project_id=789&hack_style=https://demo.com/a.css

单独产品

测试环境地址:https://b.zpert.com/company_projects/:id/snap

正式环境地址:https://zpert.com/company_projects/:id/snap

Http Method:GET

请求参数:

参数名称 是否必须 说明
com_id 斑马企业id
id 斑马计划id
hack_style 自定义样式(css)文件地址

示例:

测试环境地址:https://b.zpert.com/company_projects/12/snap?com_id=1&hack_style=https://demo.com/a.css

正式环境地址:https://zpert.com/company_projects/12/snap?com_id=1&hack_style=https://demo.com/a.css

项目详情页面

数字项目集成管理平台上注册产品

测试环境地址:https://xmgl-test.glodon.com/zpet/gateway

正式环境地址:https://xmgl.glodon.com/zpet/gateway

Http Method:GET

请求参数:

参数名称 是否必须 说明
access_path 值固定为:COMPANY_ITEM_COMPANY_CATALOG
cloudt_tenant_id 数字项目集成管理平台租户id
cloudt_item_id 数字项目集成管理平台项目id
hack_style 自定义样式(css)文件地址

示例:

测试环境地址:https://xmgl-test.glodon.com/zpet/gateway?access_path=COMPANY_ITEM_COMPANY_CATALOG&cloudt_tenant_id=123&cloudt_item_id=456&hack_style=https://demo.com/a.css

正式环境地址:https://xmgl.glodon.com/zpet/gateway?access_path=COMPANY_ITEM_COMPANY_CATALOG&cloudt_tenant_id=123&cloudt_item_id=456&hack_style=https://demo.com/a.css

单独产品

测试环境地址:https://b.zpert.com/company_catalogs/:id/company_item

正式环境地址:https://zpert.com/company_catalogs/:id/company_item

Http Method:GET

请求参数:

参数名称 是否必须 说明
com_id 斑马企业id
id 斑马项目id
hack_style 自定义样式(css)文件地址

示例:

测试环境地址:https://b.zpert.com/company_catalogs/12/company_item?com_id=1&hack_style=https://demo.com/a.css

正式环境地址:https://zpert.com/company_catalogs/12/company_item?com_id=1&hack_style=https://demo.com/a.css

备注

  1. 第三方应用没有使用广联云作为用户中心,则不能使用此方案。
  2. 斑马提供统一的页面样式,如果第三方应用需要个性化显示斑马提供的内嵌页面,斑马提供通过参数hack_style满足第三方应用自定义页面样式的需求,hack_style的值是第三方应用提供的个性化样式(css)文件地址。

使用access token

计划详情页面

测试环境地址:https://b.zpert.com/frontend/open/company_projects/:id

正式环境地址:https://zpert.com/frontend/open/company_projects/:id

请求参数:

参数名称 是否必须 说明
id 斑马计划id
access_token 斑马资源访问票据
hack_style 自定义样式(css)文件地址

示例:

测试环境地址:https://b.zpert.com/frontend/open/company_projects/12?access_token=xxxxxx&hack_style=https://demo.com/a.css

正式环境地址:https://zpert.com/frontend/open/company_projects/12?access_token=xxxxxx&hack_style=https://demo.com/a.css

斑马计划内容字段说明(zpet)

calendar

json字段 json类型 变量类型 默认值 意义 范围 导出 导入
id int int 0 唯一标识 int
name string CString “” 名称
work_periods 数组 std::set> 工作起止时间对数组(单位:分钟,0=0点,60=1点,24小时制) 不允许有覆盖的时间
vacation_rules 数组 std::vector<Rule> 休息日数组
Rule
name string CString “”
type enum Type BY_DATE 休息日类型 enum Type {
BY_DATE,//按日期
PER_WEEK,//按周
PER_MONTH,//按月
PER_YEAR,//按年
};
start int64_t int64_t 系统当前时间 时间段的开始时间 上述type为"0"时,值为选定时间CTime
上述type为"1"时,表示周几,0=周日,1=周一...6=周六,可循环(即开始为周六,结束为周一)
上述type为"2"时,表示每月的哪天,1=1日,2=2日,可循环
上述type为"3"时,表示每年的哪天,值为何月*100+何日,可循环
stop int64_t int64_t 系统当前时间+1天 时间段的结束时间 同start
is_vacation bool bool True 是否休息 bool
is_valid bool bool True 是否生效 bool

feedback

json字段 json类型 变量类型 默认值 意义 范围 导出 导入
data_source int HistoryDataSource kFromLocal 数据来源 enum HistoryDataSource {
kFromCloud, 来源于云端服务器
kFromLocal, 来源于本地客户端
kFromNone, 空类型,用于默认的过滤选项
};
status int WorkProgressStatus kUnstarted 工作状态 enum WorkProgressStatus {
kUnstarted,未开始
kOngoing,进行中
kFinished,已完成
};
real_start_time int64_t Ctime kNonTime=0 实际开始时间 int64_t 进行中和已完成的工作必须有 进行中和已完成的工作必须有
real_stop_time int64_t Ctime kNonTime 实际结束时间 int64_t 已完成的工作必须有 已完成的工作必须有
predict_stop_time int64_t Ctime kNonTime 预计结束时间 int64_t 进行中的工作必须有 进行中的工作必须有
completion_ratio double double 0.0 完成占比
feedback_time int64_t Ctime kNonTime 反馈时间 int64_t
details string CString “” 偏差原因
resolution string CString “” 解决措施

object

json字段 json类型 变量类型 默认值 意义 范围 导出 导入
version int int 2 版本 2
zpert_product string CString 产品名称
zpert_version string CString 版本号全部
store_type string CString "zpert" 保存类型 "zpert"
task_id_seq int int 0 工作ID的最大值+1 int
count_time int64_t Ctime kNonTime = 0 统计时间:前锋线基准时间 int64_t
frozen_time int64_t Ctime kNonTime 冻结时间:拉直前锋线的时间 int64_t
plan_state int planState ps_change 工程当前状态 enum planState {
ps_change,(计划编辑调整状态)
ps_count,(统计状态)
};
guid 数组 Guid 系统自动生成 GUID
calendars 数组 std::vector 标准日历和24小时日历 日历数组 见表calendar
default_calendar_id int int 0 默认日历id
tasks 数组 std::vector 有一个跟工作 工作数组 见表work
links 数组 std::vector 关系数组 见表work
dots_size unsigned int size_t 2 节点数量 大于等于2的int
progresses 数组 std::vector 前锋线数组 见表progress
schema value 自定义字段 见表schema

progress

json字段 json类型 变量类型 默认值 意义 范围 导出 导入
time int64_t Ctime kNonTime=0 前锋线时间 int64_t
is_display bool bool False 是否显示 bool
notes string Cstring "L" 前锋线说明

schema

json字段 json类型 变量类型 默认值 意义 取值范围
next_id int int 0 不重复id序号
fields 数组 数组 自定义字段

fields

json字段 json类型 变量类型 默认值 意义 取值范围
id int int 0 id
name string string 名称
type int 枚举 类型 0 (文本),1 (数值),2 (开始时间),3 (枚举),4 (完成时间)
is_visible bool bool true 表格中是否显示
width int int 100 表格中显示列宽度

work

json字段 json类型 变量类型 默认值 意义 取值范围 导出 导入
auto_duration bool bool False 自动计算工期 bool
ask_start_time int64_t CTime kNonTime 要求开始 int64_t
ask_stop_time int64_t CTime kNonTime 要求完成 int64_t
attachments 数组 数组 工作附件(地址链接)
begin_dot int Dot* 开始节点序号 int
calendar_id int Calendar* 0 该工作使用的日历id int 否(Calendar*=NULL时不存在) 否(系统默认日历)
collapsed bool bool False 是否折叠 bool
custom_values 数组 数组 自定义字段值(字段内容参见schema)
duration int CTimeSpan 0 工期 int
duration_unit int DurationUnit 系统时间单位 时间单位 0 (天),
1 (小时),
2 (分钟)
depends string CString 横道图中前置关系 是(关系除外)
down_note_idx int Note* -1 工作线下方内容批注序号 int
detail_note_idx int Note* -1 工作备注批注序号 int
department value 部门及部门负责人
draw_type unsigned int DrawType dt_line 显示类型 0 (线形),
1 (保留值),
2 (分区)
estimate_start_time int64_t CTime kNonTime 预计开始时间 int64_t 是(关系除外)
estimate_stop_time int64_t CTime kNonTime 预计完成时间 int64_t 是(关系除外)
end_dot int Dot* 结束节点序号 int
frozen_status int WorkStatus unstarted 冻结状态 0 (未开始),
1 (已完成),
2 (进行中)
feedbacks 数组 std::set< WorkFeedback> 见表feedback 历史反馈时间
forign_name string CString “” 外文名
height int int 1 占多少层(包含子工作的层)
id int int kNonWorkId(=-1) 工作ID 不重复的int
is_keywork bool bool 是否是关键路径 bool
is_typical_deviation bool bool 是否采用典型偏差计算工作完成占比 bool
is_parent bool bool 是否是父工作 bool
layer int int kNonLayer(=-10000) 工作所在层(layer*图幅每层高度=该工作的y值,零点在左上角) int
level int int 1 父子层级(子比父多1)
last_plan_start_time int64_t CTime kNonTime 上次计划开始时间 int64_t
last_plan_stop_time int64_t CTime kNonTime 上次计划完成时间 int64_t
leader string CString “” 负责人
leader_id int int -1 负责人ID int
name string CString “” 中文名 否(默认为"工作"或"里程碑"或默认值)
notes string CString “” 备注
plan_start_time int64_t CTime kNonTime(=0) 计划开始时间 int64_t 是(关系除外)
plan_stop_time int64_t CTime kNonTime 计划完成时间 int64_t 是(关系除外)
rand int int 多级里程碑的级数 1,2,3,4,5
real_start_time int64_t CTime kNonTime 实际开始时间 int64_t
real_stop_time int64_t CTime kNonTime 实际完成时间 int64_t
source_count 数组 CResQuantity* 关系为NULL,工作和里程碑的资源包含初始化工程量 资源 否(非标准,之后会有变动)
schedule_type unsigned int ScheduleType st_none 排网方式 0 (越早越好),
1 (越晚越好),
2 (系统默认排网方式)
type int CellType 类型 0 (工作),
1 (关系),
3 (里程碑)
否(默认为job)
up_note_idx int Note* -1 工作线上方内容批注序号 int
work_code string CString “” 编码
work_site string CString “” 工作部位
work_style_idx int int -1 工作风格数组索引

计划更新通知消息(mq)

斑马客户端上传计划(新建、更新)、删除计划斑马服务端向消息队列中发送通知消息;消息队列由项目管理平台部提供,消息队列相关内容请联系:刘延成或王耀廷

消息队列(config)

测试环境Topic:VPC_TEST_GLODON_ZPET_PROJECT_SYNC

正式环境Topic:VPC_PRODUCT_GLODON_ZPET_PROJECT_SYNC

消息体格式(body)

{
  tenant_id: '123qwesdrf', 
  cloudt_project_id: 'qqazwsxedc',
  zpert_company_id: '12',
  zpert_item_id: '12',
  zpert_plan_id: '12',
  user: {
    id: '12',
    phone: '18112345678',
    email: 'test@glodon.com',
    global_id: 'qwertyhgbn'
  },
  type: 'CREATE',
  updated_at: '2020-08-19 12:12:00'
}
  1. tenant_id: 数字项目集成管理平台租户ID
  2. cloudt_project_id: 数字项目集成管理平台项目ID
  3. zpert_company_id: 斑马进度企业ID,对应数字项目集成管理平台租户ID
  4. zpert_item_id: 斑马进度项目ID,对应数字项目集成管理平台项目ID
  5. zpert_plan_id: 斑马进度计划ID
  6. user:计划上传人信息,id为斑马进度用户ID,phone为用户手机号,email为用户邮箱,global_id为广联达用户中心的global_id
  7. type: 操作类型,取值:CREATE、UPDATE、DELETE,分别表示计划创建、更新和删除操作
  8. updated_at: 操作时间