provision/user

使用此资源来完成简单查询和用户供应以及取消供应请求。 用户必须是帐户管理员。

注意： API文档已迁移至 IBM API Hub 外部链接将在新窗口或新标签页中打开。 在 API Hub 中查找 API Blueworks Live 的最新更新和文档。

方法概要

HTTP 方法 路径 描述
GET /scr/api/provision/user/ 检索有关特定用户帐户的详细信息，并将帐户中的所有用户作为 JSON 数组列出。
PUT /scr/api/provision/user/ 在组中添加用户或更新用户成员资格。
DELETE /scr/api/provision/user/ 单独归档每个用户、从所有组中除去用户，或从一个或多个指定组中除去用户。

GET /scr/api/provision/user/

描述

使用此方法来检索有关特定用户帐户的详细信息，并在 JSON 数组中列出所有帐户用户。

用户供应服务提供以下形式的查询方法：
  • 基本 URI 的行为方式与集合 URI 类似，并且将以 JSON 数组的形式检索帐户中的用户列表。
  • 包含用户电子邮件地址的基本 URI 的行为方式与元素 URI 类似，并且将检索有关电子邮件地址指定的帐户的特定详细信息。
资源信息
需求 描述
响应格式 JSON
需要认证 是。 用户必须是帐户管理员。
支持 OAuth 2 客户机凭证 是，使用包含用户管理类别的用户服务标识
限制速度 尚未
参数
名称 位置 描述 必需 Type
version 页眉 请求的 API 版本为 1.0。 是 字符串
响应
示例输入
列出帐户中的所有用户：/scr/api/provision/user/
  • 使用 OAuth 2 客户机凭证：
    curl -i -H "Authorization: Bearer access_token" 
    -H "Version:1.0" "https://your_server_url/scr/api/provision/user"
获取特定用户的详细信息：/scr/api/provision/user/email_address
重要信息: email_address 参数必须正确编码。
  • 使用 OAuth 2 客户机凭证：
    curl -i -H "Authorization: Bearer access_token" 
    -H "Version:1.0" "https://your_server_url/scr/api/provision/user/user_id%40us.ibm.com"
示例输出
列出帐户中的所有用户：
HTTP/1.1 200 OK
{
  "users":["admin@us.ibm.com",
  "user_id@us.ibm.com","test@us.ibm.com"]
}
获取特定用户的详细信息：
HTTP/1.1 200 OK 
Content-Length: 108 
{
  "fullname": "John Smith",
  "username": "john.smith4@acme.com",
  "license": "VIEWER",
  "businessunit": { 
      "name": "Shipping",
      "id": "150007"
  },
  "admin": false,
  "active": true,
}
响应属性
username
供应的用户的电子邮件地址。
fullname
供应的用户的全名。 缺省值为空字符串。
license
供应的用户的许可证级别。 缺省值为 EDITOR
admin
如果用户是管理员，那么值为 true。 否则，此值为 false。
active
如果用户处于活动状态，那么值为 true。 否则，此值为 false。
businessunit
用户工作的部门、分支、工作组或功能区域。
usergroups
用户所属的组的列表。 仅当用户至少属于一个组时，才返回该属性。
usergroups.groupname
用户所属的组的名称。
响应消息
HTTP 代码 原因
200，带有 JSON 有效内容

该请求已成功完成。
400，带有 JSON 有效内容

处理请求时出错。 必需参数缺失或者包含无效值。
401

用户无权发出请求。
403
禁止访问。 可能会因以下原因之一显示此消息：
  • 指定的凭证无效。
  • 此用户不是此流程的编辑者。
  • 管理员未启用 API。 必须在帐户信息选项卡上启用 API。
  • 管理员没有接受服务的条款和条件。
404 找不到指定的 GET 用户。

PUT /scr/api/provision/user/

描述
使用此方法来添加用户以及更新组中的用户成员资格。
  • 基本 URI 的行为方式与 add 方法类似。 使用 add 方法，在添加先前归档的用户时，将重新激活此用户的帐户。
  • 包含用户名的基本 URI 的行为方式与 update 方法类似。 Update 方法用于更新一个或多个组中的用户成员资格。 如果用户名不存在，那么将使用下列缺省属性创建用户。
资源信息
需求 描述
响应格式 JSON
需要认证 是。 用户必须是帐户管理员。
支持 OAuth 2 客户机凭证 是，使用包含用户管理类别的用户服务标识
限制速度 尚未
参数
名称 位置 描述 必需 Type
content-type 页眉 该值必须为 application/json。 是 字符串
version 页眉 请求的 API 版本为 1.0。 是 字符串
JSON Request admin JSON 正文 参数值 true 或 false 指示供应的用户是否必须是管理员。 缺省设置为 false。 是 布尔值
JSON Request fullname JSON 正文 要供应的用户的全名。 如果未提供任何全名，那么将使用空白全名。 是 字符串
JSON Request license JSON 正文 用户的许可证级别。 可能的值为：VIEWER、COMMUNITY、CONTRIBUTOR 或 EDITOR。 如果未提供许可证，那么将许可证设置为缺省值 EDITOR 级别。 是 字符串
JSON Request username JSON 正文 要供应的用户的电子邮件地址。 是，在添加新用户时。 字符串
JSON Request usergroups JSON 正文 组名的 JSON 数组。 将用户添加到 usergroups 列表。 如果列表为空，那么不会将用户添加到组中。 是，用于更新。 字符串的 JSON 数组
businessunitid JSON 正文 现有业务单元的标识。 业务单元必须已存在。 否 字符串
businessunitname JSON 正文 业务单元的名称。 如果具有该名称的业务单元已经存在，那么使用该业务单元。 否则，将新建业务单元。

您可以指定 businessunitid 或 businessunitname。 如果指定两者，那么 businessunitid 优先。

 否 字符串
响应
示例输入

供应特定用户：/scr/api/provision/user/

仅使用 JSON 主体中必需的 username 参数配置用户：
  • 使用 OAuth 2 客户机凭证：
    curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" 
    -X PUT --data "{\"username\":\"user1@us.ibm.com\"}" "https://your_server_url/scr/api/provision/user/"

为用户提供 JSON 主体中的所有参数：

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" 
    -X PUT --data "{\"username\":\"john.smith@us.ibm.com\",\"fullname\":\"John Smith\",\"license\":\"EDITOR\",\"admin\":true,
    \"usergroups\":[{\"groupname\":\"group1\"},{\"groupname\":\"group2\"}]}" "https://your_server_url/scr/api/provision/user/"

将现有用户添加到组：/scr/api/provision/user/email_address

重要信息: email_address 参数必须正确编码。

将用户添加到组：

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" -X PUT 
    --data "{\"usergroups\":[{\"groupname\":\"group1\"},{\"groupname\":\"group2\"}]}" "https://your_server_url/scr/api/provision/user/user1%40us.ibm.com"

将用户添加到无效组：

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" -X PUT 
    --data "{\"usergroups\":[{\"groupname\":\"invalid\"}]}" "https://your_server_url/scr/api/provision/user/user1%40us.ibm.com"

使用业务单元标识添加新用户，并将该用户与现有业务单元关联：

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" -X PUT
    --data "{\"username\":\"john.smith4@acme.com\",\"fullname\":\"John Smith\",\"license\":\"VIEWER\",\"admin\":false, \"businessunitid\":\"150007\"}" 
    "https://your_server_url/scr/api/provision/user/user1%40us.ibm.com"

使用业务单元名称添加新用户，并将该用户与业务单元关联：

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" -X PUT 
    --data "{\"username\":\"john.smith4@acme.com\",\"fullname\":\"John Smith\",\"license\":\"VIEWER\",\"admin\":false, \"businessunitname\":\"Shipping\"}"
    "https://your_server_url/scr/api/provision/user/user1%40us.ibm.com"
添加多个用户

样本 MS-DOS 脚本用于通过 CSV 文件中的值多次执行 PUT 请求。 该脚本将标记映射到 CSV 文件中的各列。 也可以使用以 Perl、Python 或其他语言编写的更健壮的脚本。

            for /f "tokens=1,2,3,4,5,6* delims=," %%a in (usersdetail.csv) do curl -i -H "Authorization: Bearer access_token" 
            -H "Version:1.0" -H "Content-Type:application/json" -X PUT --data 
            "{\"username\":\"%%a\", \"fullname\":\"%%b\",\"license\":\"%%c\",\"admin\":%%d,\"usergroups\":[{\"groupname\":\"%%e\"},{\"groupname\":\"%%f\"}]}" 
            "http://localhost:8080/scr/api/provision/user/"
然后，usersdetail.csv 将与具有以下样本内容的批处理脚本位于同一目录中。
           abc@ibm.com,john smith,editor,true, groupA, groupB
           bac@ibm.com,smith john,community,false,group1, groupB
注意： 令牌需手动映射至 CSV 文件中的列；因此，所有已配置用户最好属于相同数量的组。
示例输出

仅使用 JSON 主体中必需的 username 参数配置用户：

HTTP/1.1 200 OK 
Content-Length: 107
{"username":"user1@us.ibm.com","fullname":"","license":"EDITOR","admin":false,"active":true}

为用户提供 JSON 主体中的所有参数：

HTTP/1.1 200 OK 
Content-Length: 155
{"username":"john.smith@us.ibm.com","fullname":"John Smith","license":"EDITOR","admin":true,"active":true, 
"usergroups":[{"groupname":"group1"},{"groupname":"group2"}]}

添加重复用户：

HTTP/1.1 400 Bad Request  
Content-Length: 71
{"message":"The provided username is already a member of this account"}

将用户添加到组：

HTTP/1.1 200 
OK Content-Length: 107
{"username":"user1@us.ibm.com","fullname":"User One","license":"EDITOR","admin":true,"active":true, "usergroups":[{"groupname":"group1"},{"groupname":"group2"}]}

将用户添加到无效组：

HTTP/1.1 400 Bad Request 
Content-Length: 79
{"message":"One of the provided groupname is either archived or is not valid."}
响应属性
username
供应的用户的电子邮件地址。
fullname
供应的用户的全名。 缺省值为空字符串。
license
供应的用户的许可证级别。 缺省值为 EDITOR。
admin
如果用户是管理员，那么值为 true。 否则，此值为 false。
活动
如果用户处于活动状态，那么值为 true。 否则，此值为 false。
usergroups
用户所属的组的列表。 仅当用户至少属于一个组时，才返回该属性。
usergroups.groupname
用户所属的组的名称。
响应消息
HTTP 代码 原因
200，带有 JSON 有效内容

该请求已成功完成。
400 处理请求时发生错误。 检查 JSON 消息元素以获取详细信息。 可能会因以下原因之一显示此消息：
  • 指定的用户已存在。
  • 存在格式或许可问题。
.
401

用户无权发出请求。
403
禁止访问。 可能会因以下原因之一显示此消息：
  • 指定的凭证无效。
  • 此用户不是此流程的编辑者。
  • 管理员未启用 API。 必须在帐户信息选项卡上启用 API。
  • 管理员没有接受服务的条款和条件。
404 找不到指定用户。

删除 /scr/api/provision/user/

描述
使用此方法单独归档每个用户、从所有组中除去用户，或从一个或多个指定组中除去用户。 用户归档服务提供单项形式的 DELETE 方法，因此不支持集合。 可重复调用此方法以删除多个用户。
资源信息
需求 描述
响应格式 JSON
需要认证 是。 用户必须是帐户管理员。
支持 OAuth 2 客户机凭证 是，使用包含用户管理类别的用户服务标识
限制速度 尚未
参数
名称 位置 描述 必需 Type
version 页眉 请求的 API 版本为 1.0。 是 字符串
groups/group-id 路径 要从中除去用户的组的标识。 使用逗号分隔多个组。 要从所有组中除去用户，请使用 /groups。 否 字符串
响应
示例输入
重要信息: email_address 参数必须正确编码。

删除帐户中的特定用户：/scr/api/provision/user/email_address

  • 使用 OAuth 2 客户机凭证：
    curl -i -H "Authorization: Bearer access_token" -H "Version:1.0"
     -X DELETE "https://your_server_url/scr/api/provision/user/user1%40domain.com"

从所有组中除去用户：/scr/api/provision/user/email_address/groups

  • 使用 OAuth 2 客户机凭证：
    curl -i -H "Authorization: Bearer access_token" -H "Version:1.0"
    -X DELETE "https://your_server_url/scr/api/provision/user/user1%40domain.com/groups"

根据组标识从指定组中除去用户。 如果有多个组，请使用逗号分隔组标识。 /scr/api/provision/user/email_address/groups/group_ID

  • 使用 OAuth 2 客户机凭证：
    curl -i -H "Authorization: Bearer access_token" -H "Version:1.0"
    -X DELETE "https://your_server_url/scr/api/provision/user/user1%40domain.com/groups/1310f8,180001"
示例输出

删除用户：

HTTP/1.1 200 OK  
Content-Length: 21
{"message":"Success"}

删除不存在的用户：

HTTP/1.1 404 Not Found
Content-Length: 0

从指定组中除去用户：

HTTP/1.1 200 OK  
Content-Length: 21
{"message":"Success"}
响应属性
无
响应消息
HTTP 代码 原因
200，带有 JSON 有效内容

该请求已成功完成。
400 处理请求时发生错误。 检查 JSON 消息元素以获取详细信息。 可能会因以下原因之一显示此消息：
  • 组标识无效或找不到该组。
  • 用户不属于该组。
  • 用户具有该组的“管理”和“编辑”许可权，无法将其除去。
401

用户无权发出请求。
403
禁止访问。 可能会因以下原因之一显示此消息：
  • 指定的凭证无效。
  • 此用户不是此流程的编辑者。
  • 管理员未启用 API。 必须在帐户信息选项卡上启用 API。
  • 管理员没有接受服务的条款和条件。
404 找不到请求的用户。