跳到主要内容

列出 Cloud 角色主体 (V2)

Lists users, groups, and API keys directly bound to a Cloud ACL role.

GET/v2/roles/{roleId}/principals
连接端点

该 API 的 Base URL 格式如下：

https://api.cloud.zilliz.com

📘说明

控制面接口速率限制为单用户单接口每秒最多 20 个请求。

shell
export BASE_URL="https://api.cloud.zilliz.com"
参数
Authorizationstringheader必填项

认证令牌，应为具备适当权限的 API Key。

示例值：Bearer {{TOKEN}}
roleIdstringpath必填项

角色 ID。

示例值：r-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
projectIdstringquery

预定义项目角色的项目边界。

示例值：proj-xxxxxxxx
currentPageintegerquery

返回的页码，第一页为 1。

示例值：1
pageSizeintegerquery

每页返回的条目数。

示例值：10
bash
export TOKEN="YOUR_API_KEY"
export roleId="r-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

curl --request GET \
--url "${BASE_URL}/v2/roles/${roleId}/principals" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json"
响应200 OK - application/json

Returns a successful result or an error message.

成功响应。

codeinteger必填项

响应码。

示例值：0
dataobject必填项
countinteger必填项

匹配条目的总数。

currentPageinteger必填项

当前页码。

取值范围：≥ 1
pageSizeinteger必填项

请求的每页条目数。

取值范围：≥ 1
principalsarray必填项

当前页面返回的主体。

[]principalsobject必填项
principalTypestring必填项

主体类型。

principalIdstring必填项

主体标识符。user 类型为用户 ID（如 usr-xxxxxxxxxxxxxxxxxxxxxx）；apikey 类型为 API Key ID（64 位十六进制字符串）；group 类型为群组 ID。

principalNamestring必填项

主体显示名称。

assignedBystring必填项

授予者的用户显示名称；非用户授予者返回类似 system 的原始值。

assignedAtstring<date-time>必填项

授予时间，采用 UTC ISO 8601 格式。

失败响应。

codeinteger必填项

响应码。

messagestring必填项

错误消息。

Successjson
{
    "code": 0,
    "data": {
        "count": 3,
        "currentPage": 1,
        "pageSize": 10,
        "principals": [
            {
                "principalType": "user",
                "email": "alice@example.com",
                "principalName": "Alice Wang",
                "assignedBy": "Bob Li",
                "assignedAt": "2026-06-21T00:00:00Z"
            },
            {
                "principalType": "group",
                "groupId": "g-xxxxxxxxxxxxxx",
                "principalName": "engineering",
                "assignedBy": "Bob Li",
                "assignedAt": "2026-06-21T00:00:00Z"
            },
            {
                "principalType": "apikey",
                "apiKeyId": "key-xxxxxxxxxxxxxx",
                "principalName": "Alice's key",
                "assignedBy": "system",
                "assignedAt": "2026-06-21T00:00:00Z"
            }
        ]
    }
}
Ctrl I