# 工作区与成员

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

## 前提条件

- 已按[开始使用 Product API](getting-started.md)准备 Product API Base URL 和个人访问令牌。
- 已从 `GET /workspaces` 响应中取得目标工作区 ID。
- 当前身份具有查看目标工作区的权限；邀请、修改、停用或移除成员还需要相应的成员管理权限。

在终端中设置以下变量：

```bash
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` | 从工作区移除成员 | 是 |

## 检查当前工作区身份

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

```bash
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"
```

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

```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 请求体传递分页和筛选条件。下面的请求读取第一页成员：

```bash
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[] | 使用筛选时 | 当前筛选字段的值。 |

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

```json
{
  "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](getting-started.md)重新配置凭据，不混入 Bearer Token 或 Cookie。 |
| 返回 `403` | `X-Workspace-ID`、成员状态、有效角色和能力结果 | 重新调用 `/user/info`，确认当前工作区和有效角色，再由有权限的成员执行操作。 |
| 找不到成员 | 成员 ID、筛选条件和分页位置 | 清除筛选并继续翻页；不要用显示名称代替成员 ID。 |
| 角色更新冲突或失败 | 最新角色列表、默认角色和权限 Schema 版本 | 重新读取当前身份和成员详情，使用最新角色 ID 与版本信息提交。 |
| 邀请后没有立即成为可用成员 | 成员列表中的当前状态 | 等待被邀请账号完成接受流程，再重新读取成员状态。 |

## 下一步

- [创建和部署工作流](workflows-workitems-lineage/create-deploy-workflows.md)
- [运行、查询和取消工作流](workflows-workitems-lineage/run-query-cancel.md)
- [管理数据、文件与连接器](data-files-connectors/index.md)