变更日志 API 文档 / 枚举/常量参考

2019-11-14 Update-1
  • 认证信息（CoreStoneAuthInfo）中account和team字段增加tags信息
2019-10-10 Update-1

  • 增加「权限」、「权限规则」、「团队角色」、「内建权限」、「内建团队角色」系列接口（详情见API文档）

  • 调整「列出团队下属登录账号」接口，返回值元素增加团队角色teamRoles和权限permissions字段（详情见API文档）

  • 调整「向团队添加登录账号」「修改团队中登录账号」接口，增加设置团队角色teamRoles和设置权限permissions选项

  • 调整请求转发后的CoreStoneAuthInfo，团队角色teamRoles和权限permissions字段

  • 文档「请求转发」和「账户体系」章节同步更新权限内容

快速了解：仅限本期更新所涉及的权限

  • 「列出团队下属登录账号」接口增加返回字段：

    1. 团队角色teamRoles，JSON数组，内含IDid，名称name字段

  • 「向团队添加登录账号」、「修改团队中登录账号」接口增加参数：

    1. 团队角色teamRoles，JSON数组，需要指定IDid，操作operation字段（添加add，移除remove）

  • 新增「列出团队角色」接口，可以返回本团队可用的所有角色

  • 新增「列出权限」接口，可以返回本系统可用的所有权限

  • 认证令牌创建后的返回值（客户端相关），转发后的认证信息对象（业务系统相关）新增团队角色teamRoles，权限permissions字段：

    1. 团队角色teamRoles，JSON数组，内含IDid字段（名称可能存在修改可能，请从「列出团队角色」接口获取）
    2. 权限permissions，JSON数组，内含IDid字段（名称可能存在修改可能，请从「列出权限」接口获取）

其中，权限ID为具有语义的字符串，如：buildIn.admin.RO，前端可以直接作为常量使用

目前可直接使用的内建角色和权限

  • 管理员（ID：tmro-buildIn-admin）

    • 内建管理员只读权限（ID：buildIn.admin.RO）
    • 内建管理员读写权限（ID：buildIn.admin.RW）

  • 普通成员（ID：tmro-buildIn-generalMember）

    • 内建普通成员只读权限（ID：buildIn.generalMember.RO）
    • 内建普通成员读写权限（ID：buildIn.generalMember.RW）

注：具体配置可以更改，详情见后台配置

2019-07-01 Update-1

  • 调整「添加登录账号」接口，返回值增加joinedTeams和defaultTeam字段，分别表示当前添加的登录账号所属的团队和默认登录团队。

  • 调整「修改团队」接口，当设置isCanceled=true时，增加回退结果fallbackResult字段（详情见下文）

  • 调整「从团队中删除登录账号」，增加回退结果fallbackResult字段（详情见下文）

回退结果fallbackResult字段

对于需要实现「自动添加默认规则」的业务场景，只需要针对data.fallbackResult.orphanTeams处理即可。

{
  "data": {
    "fallbackResult": {
      // 孤儿团队：在团队-登录账户关系改变后，针对无所属团队的登录账号，自动创建的团队信息
      // （`type`一定为`singleAccount`）
      "orphanTeams": [
        {
          "id"       : "team-XXXXXXXXXXXXX",
          "accountId": "acnt-YYYYYYYYYYYYY",
          "name"     : "team-XXXXXXXXXXXXX",
          "type"     : "singleAccount"
        }
      ],
      // 回退关系信息：在团队-登录账户关系改变后，自动修改的登录账号创建的团队-登录账号关联信息
      // （`isDefault`一定为`true`，包含转移至孤儿团队和有所属团队的所有自动修改的关联）
      "fallbackRelInfo": [
        {
          "teamId"   : "team-XXXXXXXXXXXXX",
          "accountId": "acnt-YYYYYYYYYYYYY",
          "isDefault": true,
        }
      ]
    }
  },
  ... // 其他返回字段
}
2019-06-05 Update-1

细化报错信息中EBizCondition，详情见 常量表 EBizCondition章节。

2019-05-17 Update-1

  • 新增「认证令牌操作记录」页面，详细记录认证令牌的创建/销毁信息

  • 调整认证令牌的创建/作废逻辑

为了避免各个业务系统之间将其他业务系统中生成的认证令牌误删，「作废认证令牌」接口会根据调用方（所使用AccessKey ID）进一步隔离认证令牌。

每个AccessKey ID 只能作废由本AK所创建的认证令牌。

例外：团队解散/禁用、登录账号禁用、团队删除登录账号所导致的连带作废认证令牌依然为全局范围

2019-04-28 Update-1
  • 调整登录账号-团队关联信息相关接口，增加团队内备注inTeamNote，涉及接口如下：
    1. 「添加团队」
    2. 「向团队添加登录账号」
    3. 「修改团队中登录账号」
    4. 「添加登录账号」
2019-04-26 Update-1

  • 调整「登录账号列表」、「登录账号详情」接口，增加是否已设置密码isPasswordSet字段，用于标示登录账号是否已设置密码。

    注意：对于LDAP用户（命名空间为ldap.开头），此字段永远为true。

2019-04-22 Update-1

  • 调整认证系列接口，调整signInTeamId参数：

    1. 「验证登录账号」
    2. 「直接创建认证令牌」
    3. 「作废认证令牌（对应客户端登出操作）」
    4. 「解析认证令牌（方便测试/DEBUG使用）」

    详情请见API接口文档

2019-03-25 Update-1
  • 新增「List tag Key-Value pairs」接口，支持对标签tag进行搜索（支持JSON数组是否包含元素方式）
2019-03-08 Update-1
  • 新增「支持挑选返回字段」功能，如：?fieldPicking=seq,id,name，详情请参考具体接口文档
2019-03-07 Update-1
  • 优化「监控」系列页面
  • 新增「系统状态」页面
2019-03-04 Update-1
  • 调整「列出团队下属登录账号」接口，增加joinTime作为加入团队时间，方便客户端排序
2019-03-02 Update-1
  • 优化业务系统转发规则配置页面，增加更多提示内容，让配置人员更容易理解
  • 调整「列出团队下属登录账号」接口，默认排序为按照name字段GBK编码升序（即一级汉字拼音升序）
  • 增加登录账号「昵称nickname」字段
2019-02-28 Update-1
  • 原「查询团队下属LDAP用户」接口URL地址从/api/v1/teams/:uniqueMarker/ldap-users/do/search改为/api/v1/teams/ldap-users/do/search?uniqueMarker=xxx。（旧接口暂时保留，业务系统请尽快切换）
  • 优化「团队列表」、「新建团队」、「修改团队」页面
  • 新增「团队配置」页面
2019-02-26 Update-1
  • 修复拼写错误：telphone改为telephone
  • 优化「添加登录账号」和「修改登录账号」接口，namespace字段必须满足^\w([.\w-]*\w)?$（即必须为大小写英文数字或.、_、-，且开头结尾不得为.或-）
2019-02-24 Update-1
  • 数据库切换为utf8mb4，支持emoji😄
  • Celery任务ID统一为task-<UUID>
2019-02-22 Update-2
  • 修复「请求发往不接受命名空间的业务系统时，依然会带上用户信息」的BUG
2019-02-22 Update-1
  • 钉钉机器人发生未捕捉的异常不再发往「CC基础系统互助友爱群」，改为发往专门的「CC基础系统异常搜集群」
  • Webhook同时支持发送Kafka消息，数据结构与原版Webhook基本相同（基础系统产生的消息，所属topic均为basis，且不包含isEcho字段）
  • 调整「新增/修改团队」，名称name字段不再要求唯一；增加备注note字段
2019-02-19 Update-1
  • 调整「验证登录账号」、「直接创建认证令牌」，命名空间（namespace）字段是否必须改为视情况而定
  • 调整「添加登录账号」接口，命名空间（namespace）不得为ldap或以ldap.开头

有关登录账号的命名空间

由于之前的设计，所有LDAP用户生成的登录账号都属于同一个命名空间ldap， 而与此同时，CoreStone本身是支持多个LDAP账号源的（即可以为不同的团队分别配置LDAP登录源）。

默认情况下，通过LDAP用户生成的登录账号的用户名、手机、邮箱都为null。 那么，当存在多个LDAP账号源时，同时业务系统又为登录账号设置了用户名、手机、邮箱， 那么非常容易发生冲突。

为了解决上述问题，所有LDAP用户生成的登录账号所属的命名空间改为「分别属于ldap.<Unique Marker>」，如： 通过jiagouyun/zhang3登录的LDAP用户，生成的命名空间为ldap.jiagouyun，以此解决冲突问题。

对于业务系统来说，调用「验证登录账号」、「直接创建认证令牌」可以不做任何改动。

但对于通过LDAP登录/验证的，命名空间namespace字段不再需要填写。

2019-02-18 Update-2
  • 修复「转发时，无匹配后端系统时系统崩溃」的BUG
2019-02-18 Update-1
  • 修复在「直接创建认证令牌」接口参数中，「错误把expire当作名词使用」的BUG
  • 完善「验证登录账号」接口描述

目前在「直接创建认证令牌」接口参数中，expire和expires参数同时存在，效果相同。但请尽早将此参数从expire改为expires。

2019-02-16 Update-3
  • 调整了「发送Socket.io 消息」接口返回值，增加succeededTo和failedTo字段，表示发送成功/失败的Room
2019-02-16 Update-2
  • 修复「仅修改实体tags时，SQL语句生成错误」的BUG
2019-02-16 Update-1
  • 修复「SDK上传文件的文件名为中文时，未进行编码」的BUG
  • 修复「修改实体tags扩展字段后，通过Webhook通知时，未将修改的tags包含在内」的BUG
  • 修复「从团队中移除登录账号时，未将此登录账号的认知令牌作废」的BUG
  • 调整「验证登录账号」接口，在验证LDAP用户后，系统会自动添加/更新此LDAP用户至本系统内
2019-02-13 Update-2
  • 当服务器发生未捕捉的异常时，会通过钉钉机器人将错误信息抛出
2019-02-13 Update-1
  • CoreStone 在转发请求时，会在HTTP 请求头X-Trace-Id中添加跟踪ID，业务系统直接使用此跟踪ID即可
  • CoreStone 在回发响应时，会在HTTP 响应头X-Trace-Id中添加跟踪ID，业务系统响应中是否包含此ID都可以
  • 更新API文档「部署」章节
  • 更新API文档「请求转发」章节，增加有关「跟踪ID」的说明
  • 更新SDK，支持添加自定义请求头