工作区与成员

Product API 使用工作区划分产品资源和权限范围。完成本页操作后，你可以确认当前身份在目标工作区中的角色和能力，列出工作区成员，并找到成员管理所需的接口与标识符。

前提条件

• 已按开始使用 Product API准备 Product API Base URL 和个人访问令牌。

• 已从 GET /workspaces 响应中取得目标工作区 ID。

• 当前身份具有查看目标工作区的权限；邀请、修改、停用或移除成员还需要相应的成员管理权限。

在终端中设置以下变量：

export PRODUCT_API_BASE_URL='<Product API Base URL ending in /newmoi>'
export PRODUCT_API_KEY='<your-personal-access-token>'
export WORKSPACE_ID='<workspace-id-from-GET-workspaces>'

除工作区发现和创建等少数接口外，工作区资源请求同时使用 X-API-Key 和 X-Workspace-ID。工作区 ID 必须来自当前账号可见的工作区结果，不能使用名称代替。

相关接口

以下路径相对于 Product API Base URL：

方法与路径	用途	是否需要 X-Workspace-ID
GET /workspaces	列出当前账号可见的工作区	否
POST /user/info	查询当前身份在目标工作区中的角色和能力	是
POST /user/list	分页列出目标工作区的成员	是
POST /user/create	邀请账号加入目标工作区	是
POST /user/detail_info	查询指定成员详情	是
POST /user/update_info	更新成员资料和标签	是
POST /user/update_role_list	更新成员角色和默认角色	是
POST /user/update_status	启用或停用成员	是
POST /user/delete	从工作区移除成员	是

检查当前工作区身份

在执行成员管理或其他受权限控制的操作前，先查询当前身份。此请求不需要请求体：

curl -X POST "$PRODUCT_API_BASE_URL/user/info" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Accept: application/json"

成功响应会返回当前成员、有效角色和能力快照。下面只展示后续调用最常用的字段：

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "user": "<MEMBER_NAME>",
    "role": "<ROLE_NAME>",
    "is_admin": false,
    "user_info": {
      "id": "<MEMBER_ID>",
      "name": "<MEMBER_NAME>",
      "status": "enabled",
      "reserved": false
    },
    "iam_context": {
      "effective_role_id": "<ROLE_ID>",
      "role_context_status": "<ROLE_CONTEXT_STATUS>",
      "schema_version": "<SCHEMA_VERSION>",
      "capability_version": "<CAPABILITY_VERSION>"
    },
    "iam_snapshot_version": "<SNAPSHOT_VERSION>"
  }
}

字段	类型	返回条件	说明
data.user_info.id	string	请求成功时返回	当前成员 ID。不要把它与工作区 ID 或角色 ID 混用。
data.user_info.status	string	请求成功时返回	当前成员状态。成员被停用时，后续操作会受到限制。
data.role	string	请求成功时返回	当前有效角色的显示名称。权限判断仍以服务端返回的能力结果为准。
data.is_admin	boolean	请求成功时返回	当前有效身份是否处于工作区系统管理员角色。不要只根据该字段推断某个具体操作一定允许。
data.iam_context.effective_role_id	string	角色上下文可用时返回	本次请求实际生效的角色 ID。
data.iam_context.role_context_status	string	请求成功时返回	角色上下文状态。只有当前返回状态可用于判断本次请求的角色上下文。
data.iam_context.schema_version	string	请求成功时返回	当前权限 Schema 版本。需要版本控制的权限变更应使用最新响应。
data.iam_snapshot_version	string	请求成功时返回	当前权限快照版本，可用于记录和排查权限变化。

如果页面或应用允许工作区成员选择当前角色，应在切换后重新查询 /user/info，确认 effective_role_id 和能力结果已经更新。

列出工作区成员

POST /user/list 使用 JSON 请求体传递分页和筛选条件。下面的请求读取第一页成员：

curl -X POST "$PRODUCT_API_BASE_URL/user/list" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 20
  }'

字段	类型	必需	说明
page	integer	否	要读取的页码。示例值为 1，不表示所有部署的固定默认值。
page_size	integer	否	本页请求的成员数量。取值限制以当前接口返回的校验信息为准。
filters	array	否	筛选条件列表。每项包含 name 和 values；当前接口支持按名称、名称或描述、状态等字段筛选。
filters[].name	string	使用筛选时	筛选字段，例如 name、name_description 或 status。
filters[].values	string[]	使用筛选时	当前筛选字段的值。

成功响应包含成员总数和当前页成员：

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "total": 1,
    "user_list": [
      {
        "id": "<MEMBER_ID>",
        "iam_user_id": "<IAM_USER_ID>",
        "name": "<MEMBER_NAME>",
        "description": "",
        "status": "enabled",
        "created_at": "<CREATED_AT>",
        "updated_at": "<UPDATED_AT>",
        "reserved": false,
        "role_list": [
          {
            "id": 1,
            "name": "<ROLE_NAME>",
            "status": "<ROLE_STATUS>"
          }
        ],
        "tag_list": []
      }
    ]
  }
}

字段	类型	返回条件	说明
data.total	integer	请求成功时返回	符合当前筛选条件的成员总数。不能只根据当前页数组长度判断是否还有下一页。
data.user_list	array	请求成功时返回	当前页的成员列表。
data.user_list[].id	string	每个成员返回	Product API 成员 ID。查询、修改、停用或删除成员时使用该值。
data.user_list[].status	string	每个成员返回	成员当前状态，包括已启用、已停用或待接受邀请等当前接口返回的状态。
data.user_list[].role_list	array	每个成员返回	成员当前绑定的角色。角色变更时使用服务端返回的角色 ID。
data.user_list[].tag_list	array	每个成员返回	成员标签。没有标签时返回空数组。

遍历全部成员时，根据 total、page 和 page_size 继续请求后续页面。不要假定第一项是最新成员，也不要根据名称推断成员唯一性。

管理成员

成员写操作都需要目标成员 ID。先通过 /user/list 或 /user/detail_info 读取最新状态，再提交变更。

任务	接口	关键输入	完成后检查
邀请成员	POST /user/create	name、邮箱或手机二选一、role_id_list、default_role_id	保存返回的成员 ID，并通过成员列表确认邀请或成员状态。
查看成员详情	POST /user/detail_info	id	检查状态、角色和标签是否为最新值。
更新成员资料	POST /user/update_info	id、name、description、tag_list	重新读取详情，不根据 HTTP 成功自行推断字段已经按预期保存。
更新角色	POST /user/update_role_list	id、role_id_list、default_role_id	确认默认角色属于已分配角色列表，再重新读取成员和权限。
启用或停用成员	POST /user/update_status	id、action	重新读取成员状态；action 使用当前接口支持的 enable 或 disable。
移除成员	POST /user/delete	id	重新查询成员列表，确认成员已不在当前工作区。

停用或移除成员前，先交接其工作流、自动化任务、凭据和运维责任。成员关系发生变化后，已有任务和外部系统中的数据不会因此自动撤销或回滚。

常见问题

现象	先检查	下一步
返回 401	个人访问令牌和 X-API-Key	按开始使用 Product API重新配置凭据，不混入 Bearer Token 或 Cookie。
返回 403	X-Workspace-ID、成员状态、有效角色和能力结果	重新调用 /user/info，确认当前工作区和有效角色，再由有权限的成员执行操作。
找不到成员	成员 ID、筛选条件和分页位置	清除筛选并继续翻页；不要用显示名称代替成员 ID。
角色更新冲突或失败	最新角色列表、默认角色和权限 Schema 版本	重新读取当前身份和成员详情，使用最新角色 ID 与版本信息提交。
邀请后没有立即成为可用成员	成员列表中的当前状态	等待被邀请账号完成接受流程，再重新读取成员状态。

下一步

• 创建和部署工作流

• 运行、查询和取消工作流

• 管理数据、文件与连接器

最后更新于 2026 年 8 月 14 日