统一账户集成

观远数据提供一套简便的验证机制，来供私有化部署用户做外部系统账户对接。

1. 获取账号同步令牌（Token）

账号同步令牌（Token）是调用统一账户集成相关API时的唯一身份凭证。系统管理员可从管理员设置页面获得该令牌。安全起见，进行账户集成开发时，需妥善保管该令牌。

2. 统一账户集成接口

观远数据提供一整套用户、用户组管理接口供企业IT部门来实现统一账户管理的集成。提供的接口包括：

2.1 批量创建用户

请求方式： POST

请求地址：/public-api/users/add

参数说明：

POST Body Sample:

{
 "token":"sdjfghfodjgjshgfiw23ehrt43",
 "users": [
  {
   "name": "nameA",
   "loginId": "Id1",   // 必填 用户界面登录以及通过api管理用户属性的id
   "password": "", //SSO登录可不提供该字段信息，密码必须BASE64加密
   "role": "admin",  //用户角色，目前可支持admin，editor，readonly三类
   "email": "sample1@qq.email.com",
   "mobile": "13200000000",
   "userGroupIds": ["gId1", "gId2"...],   //External group ID
   "userDefinedProperties": {
      "key1": "value1",
      "key2": "vaule2"
    }   //观远平台内已经添加的用户属性字段
  },
  {
   "name": "nameB",
   "loginId": "Id2",  // 必填 用户界面登录以及通过api管理用户属性的id
   "password": "",
   "role": "editor",
   "email": "sample2@qq.email.com",
   "mobile": "13200000001",
   "userGroupIds": ["gId3", "gId4"...],
   "userDefinedProperties": {
      "key1": "value1",
      "key2": "vaule2"
    }   //观远平台内已经添加的用户属性字段
  }
  ...
 ]
}

2.2 删除用户

请求方式： POST

请求地址：/public-api/users/delete

参数说明：

POST Body Sample:

{
 "token":"sdjfghfodjgjshgfiw23ehrt43",
 "users": ["loginId1","loginId2",...]
}

这里需要注意的是，若要删除的用户还有资源未转移，则该用户不能被删除，需要在response中告知用户哪些用户没有被成功删除。

Response:

{
    "response": "uId1, uId2 deleted successfully. uId3 can not be deleted due to some resource rely on."
}

2.3 批量修改用户属性

请求方式： POST

请求地址：/public-api/users/modify

参数说明：

POST Body Sample:

{
   "token":"sdjfghfodjgjshgfiw23ehrt43",
   "users": [
   {
    "name": "nameA",
    "loginId": "Id1",   // 必填 用户界面登录以及通过api管理用户属性的id
    "password": "", //SSO登录可不提供该字段信息，密码必须BASE64加密
    "role": "admin",  //用户角色，目前可支持admin，editor，readonly三类
    "email": "sample1@qq.email.com",
    "mobile": "13200000000",
    "userDefinedProperties": {
      "key1": "value1",
      "key2": "vaule2"
     }   //观远平台内已经添加的用户属性字段
   },
   {
    "name": "nameB",
    "loginId": "Id2",  // 必填 用户界面登录以及通过api管理用户属性的id
    "password": "", 
    "role": "editor",
    "email": "sample2@qq.email.com",
    "mobile": "13200000001",
    "userDefinedProperties": {
      "key1": "value1",
      "key2": "vaule2"
     }   //观远平台内已经添加的用户属性字段
   }
  ...
 ]
}

Response:

{
    "response": "Property changed!"
}

2.4 批量查询用户是否存在

请求方式： POST

请求地址：/public-api/user/get

参数说明：

POST Body Sample:

{
   "token":"sdjfghfodjgjshgfiw23ehrt43",
   "users": ["loginId1", "loginId2", ...]  
}

Response:

{
  "userExist": ["loginId1", ...],
  "userNotExist": ["loginId2", ...]
}

2.5 批量创建用户组

请求方式： POST

请求地址：/public-api/user-groups/add

参数说明：

POST Body Sample:

{
    "token":"sdjfghfodjgjshgfiw23ehrt43",
    "userGroups": [
        {
            "name": "groupA",
            "externalGroupId": "gId1",
            "externalParentGroupId":"parent_gId1"
        },
        {
            "name": "groupA",
            "externalGroupId": "gId1",
            "externalparentGroupId":"parent_gId1"
        }
    ]
}

若请求中有用户组的externalParentGroupId在当前用户组以及请求userGroups中都不存在，或者用户组父子关系逻辑成环，都将导致本次用户组创建失败（全部都不创建）。

2.6 批量修改用户组

请求方式： POST

请求地址：/public-api/user-groups/modify

参数说明：

POST Body Sample:

{
    "token":"sdjfghfodjgjshgfiw23ehrt43",
    "userGroups": [
        {
            "name": "groupA",
            "externalGroupId": "gId1",
            "externalParentGroupId":"parent_gId1"
        },
        {
            "name": "groupA",
            "externalGroupId": "gId1",
            "externalparentGroupId":"parent_gId1"
        }
    ]
}

2.7 将用户添加至用户组

请求方式： POST

请求地址：/public-api/user/assoc-groups

参数说明：

POST Body Sample:

{
    "token":"sdjfghfodjgjshgfiw23ehrt43",
    "loginId": "Id1",   // 必填 用户界面登录以及通过api管理用户属性的id
    "ugIds": ["ugId1", "ugId2"...]
}

2.8 将用户从用户组删除

请求方式： POST

请求地址：/public-api/user/remove-from-groups

参数说明：

POST Body Sample:

{
    "token":"sdjfghfodjgjshgfiw23ehrt43",
    "loginId": "uId1",
    "ugIds": ["ugId1", "ugId2"...]
}

3. 账户集成最佳实践

以上提供了账户集成的需要的所有接口。作为合理的账户集成方案，我们建议您按照以下最佳实践方式进行账户集成，尽可能减少接口调用失败的情况发生。

步骤一 获取同步令牌

在观远平台内登录管理员账户，打开统一账户集成功能，获得同步令牌(token)。

步骤二 创建用户组

一般情况下，我们创建的用户总是要挂到相应的用户组下面去的。如果在调用用户创建接口时，想要直接配置好相关的用户组，则需要事先创建用户组。

我们建议您调用一次批量创建用户组接口，一次性创建好所有用户组；或者依照用户组的层次关系，从上往下依次创建用户组。这样就可以尽可能降低用户组创建失败的几率。

步骤三 添加扩展用户属性

观远暂未提供添加扩展用户属性字段的公共接口，如果您有需要，可以在登陆到Web环境内，在管理员设置界面添加您需要的扩展用户属性。

步骤四 添加用户

由于前两步已经创建好了用户组和扩展用户属性，这一步添加用户时，可以直接在调用批量用户创建接口时将用户组与用户属性一并配置进去。

步骤五 账户体系同步

我们建议您将观远账户体系同步集成进您的统一账户管理平台中，确保外部系统每一次账户修改都能及时同步至观远平台。