角色管理 API

创建、查询、更新和删除项目角色及其权限与限额。

角色管理 API

💡

接口参考待联调：需确认角色类型与预算周期枚举、接口权限，以及管理接口采用的签名编码。界面的中文身份不能直接当作 API 枚举提交。以下是待核对的接口资料，不作为可直接接入的正式示例。控制台操作请按对应使用指南完成。

概述

角色管理API用于创建和管理项目角色，定义RAM用户在项目中的权限和资源限制。角色包含访问权限（manager/viewer）和API调用限额（RPM、TPM、Budget）。

基础信息

Base URL: YOUR_GATEWAY_MANAGEMENT_BASE_URL
认证方式: AccessKey/SecretKey签名或 JWT Token
请求格式: JSON
响应格式: JSON

权限说明

操作	主账号	RAM管理员	RAM成员
创建角色	✅	✅	❌
查看角色列表	✅	✅	✅
更新角色	✅	✅	❌
删除角色	✅	✅	❌

角色类型说明

权限类型（permissions）

类型	说明	可执行操作
manager	项目管理员	管理项目配置、路由、模型、成员
viewer	项目查看者	只能查看项目信息和生成API Token

限额类型

限额项	说明	单位
rpm_limit	每分钟请求数限制	次/分钟
tpm_limit	每分钟Token数限制	Token/分钟
budget	预算限制	元
budget_kind	预算周期	dayily/monthily

API接口列表

1. 创建角色

创建一个新的项目角色。

接口信息

Path: /role/create
Method: POST
权限: 主账号、RAM管理员

请求参数

参数名	类型	必填	说明	示例
role_name	string	是	角色名称	开发团队角色
desc	string	否	角色描述	用于开发环境的角色
permissions	string	是	权限类型：manager/viewer	manager
tpm_limit	integer	否	TPM限制	1000000
rpm_limit	integer	否	RPM限制	100
budget	integer	否	预算限制	1000
budget_kind	string	是	预算周期：dayily/monthily	monthily

请求示例

POST /role/create
Content-Type: application/json
X-Access-Key-Id: AK_xxx
X-Timestamp: 2024-01-01T12:00:00+00:00
X-Signature: xxx

{
  "role_name": "开发团队角色",
  "desc": "开发环境使用的管理员角色",
  "permissions": "manager",
  "tpm_limit": 1000000,
  "rpm_limit": 100,
  "budget": 5000,
  "budget_kind": "monthily"
}

响应示例

成功响应 (200 OK):

{
  "code": 0,
  "data": {},
  "msg": "创建成功"
}

错误响应 (403 Forbidden):

{
  "code": 403,
  "msg": "权限不足，需要以下权限之一: admin"
}

Python调用示例

先将>认证文档的 Python 签名实现保存为 signature_helper.py，并安装 requests。本段依赖该文件；签名编码仍须完成本页顶部所述核准。

import requests
import json
from signature_helper import calculate_signature

# 配置
base_url = "http://your-domain.com"
access_key_id = "AK_xxx"
secret_key = "SK_xxx"

# 请求参数
body = {
    "role_name": "开发团队角色",
    "desc": "开发环境使用的管理员角色",
    "permissions": "manager",
    "tpm_limit": 1000000,
    "rpm_limit": 100,
    "budget": 5000,
    "budget_kind": "monthily"
}

# 计算签名
method = "POST"
uri = "/role/create"
timestamp, signature = calculate_signature(method, uri, body, secret_key)

# 发送请求
response = requests.post(
    f"{base_url}{uri}",
    data=json.dumps(body, separators=(',', ':')).encode('utf-8'),
    timeout=30,
    headers={
        "Content-Type": "application/json",
        "X-Access-Key-Id": access_key_id,
        "X-Timestamp": timestamp,
        "X-Signature": signature
    }
)

print(response.json())

2. 获取角色列表

查询角色列表。

接口信息

Path: /role/list
Method: GET
权限: 所有用户

请求示例

GET /role/list?page=1&pageSize=10
X-Access-Key-Id: AK_xxx
X-Timestamp: 2024-01-01T12:00:00+00:00
X-Signature: xxx

响应示例

{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "user_id": 1,
        "name": "开发团队角色",
        "desc": "开发环境使用的管理员角色",
        "auth": "manager",
        "tpm_limit": 1000000,
        "rpm_limit": 100,
        "budget": 5000,
        "budget_kind": "monthily",
        "created_at": "2024-01-01T12:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z"
      },
      {
        "id": 2,
        "user_id": 1,
        "name": "测试团队角色",
        "desc": "测试环境使用的查看者角色",
        "auth": "viewer",
        "tpm_limit": 500000,
        "rpm_limit": 50,
        "budget": 1000,
        "budget_kind": "monthily",
        "created_at": "2024-01-01T13:00:00Z",
        "updated_at": "2024-01-01T13:00:00Z"
      }
    ]
  },
  "msg": "success"
}

3. 更新角色

更新现有角色的信息。

接口信息

Path: /role/update
Method: POST
权限: 主账号、RAM管理员

请求参数

参数名	类型	必填	说明	示例
role_id	integer	是	角色ID	1
role_name	string	否	新的角色名称	更新后的角色名
desc	string	否	新的角色描述	更新后的描述
permissions	string	否	新的权限类型	viewer
tpm_limit	integer	否	新的TPM限制	2000000
rpm_limit	integer	否	新的RPM限制	200
budget	integer	否	新的预算限制	10000
budget_kind	string	否	新的预算周期	dayily

请求示例

POST /role/update
Content-Type: application/json
X-Access-Key-Id: AK_xxx
X-Timestamp: 2024-01-01T12:00:00+00:00
X-Signature: xxx

{
  "id": 1,
  "desc": "更新后的角色描述",
  "tpm_limit": 2000000,
  "budget": 8000
}

响应示例

{
  "code": 0,
  "data": {},
  "msg": "更新成功"
}

4. 删除角色

删除指定的角色。

接口信息

Path: /role/delete
Method: POST
权限: 主账号、RAM管理员

请求参数

参数名	类型	必填	说明	示例
role_id	integer	是	角色ID	1

请求示例

POST /role/delete
Content-Type: application/json
X-Access-Key-Id: AK_xxx
X-Timestamp: 2024-01-01T12:00:00+00:00
X-Signature: xxx

{
  "role_id": 1
}

响应示例

成功响应:

{
  "code": 0,
  "msg": "删除成功"
}

错误响应（角色被使用）:

{
  "code": 400,
  "msg": "该角色正在被使用，无法删除"
}

完整调用示例

Python完整示例

import requests
import hashlib
import hmac
import base64
import json
from datetime import datetime, timezone
from urllib.parse import urlencode

class RoleAPI:
    def __init__(self, base_url, access_key_id, secret_key):
        self.base_url = base_url
        self.access_key_id = access_key_id
        self.secret_key = secret_key

    def _calculate_signature(self, method, uri, body):
        # 计算Body哈希
        body_bytes = json.dumps(body, separators=(',', ':')).encode('utf-8') if body is not None else b''
        body_hash = base64.b64encode(hashlib.sha256(body_bytes).digest()).decode('utf-8')

        # 生成时间戳
        timestamp = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%S%z')
        timestamp = timestamp[:-2] + ':' + timestamp[-2:]

        # 构造StringToSign
        string_to_sign = f"{method}\n{uri}\n{timestamp}\n{body_hash}"

        # 计算签名
        signature = base64.b64encode(
            hmac.new(
                self.secret_key.encode('utf-8'),
                string_to_sign.encode('utf-8'),
                hashlib.sha256
            ).digest()
        ).decode('utf-8')

        return timestamp, signature

    def _request(self, method, uri, body=None, params=None):
        # 对于GET请求，URI需要包含查询参数
        full_uri = uri
        if params:
            full_uri = f"{uri}?{urlencode(params)}"

        timestamp, signature = self._calculate_signature(method, full_uri, body)

        response = requests.request(
            method=method,
            url=f"{self.base_url}{full_uri}",
            data=json.dumps(body, separators=(',', ':')).encode('utf-8') if body is not None else None,
            timeout=30,
            headers={
                "Content-Type": "application/json",
                "X-Access-Key-Id": self.access_key_id,
                "X-Timestamp": timestamp,
                "X-Signature": signature
            }
        )
        return response.json()

    def create_role(self, name, auth, tpm_limit, rpm_limit, budget, budget_kind, desc=""):
        """创建角色"""
        return self._request("POST", "/role/create", {
            "name": name,
            "desc": desc,
            "auth": auth,
            "tpm_limit": tpm_limit,
            "rpm_limit": rpm_limit,
            "budget": budget,
            "budget_kind": budget_kind
        })

    def list_roles(self, page=1, page_size=10):
        """获取角色列表"""
        return self._request("GET", "/role/list", params={
            "page": page,
            "pageSize": page_size
        })

    def update_role(self, role_id, **updates):
        """更新角色"""
        body = {"id": role_id}
        body.update(updates)
        return self._request("POST", "/role/update", body)

    def delete_role(self, role_id):
        """删除角色"""
        return self._request("POST", "/role/delete", {
            "id": role_id
        })


# 使用示例
if __name__ == "__main__":
    api = RoleAPI(
        base_url="http://your-domain.com",
        access_key_id="AK_xxx",
        secret_key="SK_xxx"
    )

    # 1. 创建角色
    result = api.create_role(
        name="开发团队角色",
        desc="开发环境使用的管理员角色",
        auth="manager",
        tpm_limit=1000000,
        rpm_limit=100,
        budget=5000,
        budget_kind="monthily"
    )
    print("创建角色:", result)

    # 2. 获取角色列表
    result = api.list_roles(page=1, page_size=10)
    print("角色列表:", result)

    # 3. 更新角色
    role_id = 1
    result = api.update_role(
        role_id=role_id,
        desc="更新后的角色描述",
        budget=8000
    )
    print("更新角色:", result)

    # 4. 删除角色
    # result = api.delete_role(role_id=role_id)
    # print("删除角色:", result)

Node.js完整示例

使用 Node.js 18 或以上版本，先执行 npm install axios，将代码保存为 .cjs 文件。替换为获准的测试环境和凭证；底部示例包含写入操作，接口契约仍需按页首说明核准。

const crypto = require('crypto');
const axios = require('axios');

class RoleAPI {
    constructor(baseUrl, accessKeyId, secretKey) {
        this.baseUrl = baseUrl;
        this.accessKeyId = accessKeyId;
        this.secretKey = secretKey;
    }

    calculateSignature(method, uri, body) {
        // 1. 计算Body哈希
        const bodyStr = body ? JSON.stringify(body) : '';
        const bodyHash = crypto
            .createHash('sha256')
            .update(bodyStr)
            .digest('base64');

        // 2. 生成时间戳
        const timestamp = new Date().toISOString().replace('Z', '+00:00');

        // 3. 构造StringToSign
        const stringToSign = `${method}\n${uri}\n${timestamp}\n${bodyHash}`;

        // 4. 计算签名
        const signature = crypto
            .createHmac('sha256', this.secretKey)
            .update(stringToSign)
            .digest('base64');

        return { timestamp, signature };
    }

    async request(method, uri, body = null, params = null) {
        // 对于GET请求，URI需要包含查询参数
        let fullUri = uri;
        if (params) {
            const queryString = new URLSearchParams(params).toString();
            fullUri = `${uri}?${queryString}`;
        }

        const { timestamp, signature } = this.calculateSignature(method, fullUri, body);

        const config = {
            method: method.toLowerCase(),
            url: `${this.baseUrl}${fullUri}`,
            headers: {
                'Content-Type': 'application/json',
                'X-Access-Key-Id': this.accessKeyId,
                'X-Timestamp': timestamp,
                'X-Signature': signature
            }
        };

        if (method === 'POST' && body) {
            config.data = body;
        }

        const response = await axios(config);
        return response.data;
    }

    async createRole(name, auth, tpmLimit, rpmLimit, budget, budgetKind, desc = '') {
        return this.request('POST', '/role/create', {
            name,
            desc,
            auth,
            tpm_limit: tpmLimit,
            rpm_limit: rpmLimit,
            budget,
            budget_kind: budgetKind
        });
    }

    async listRoles(page = 1, pageSize = 10) {
        return this.request('GET', '/role/list', null, {
            page,
            pageSize
        });
    }

    async updateRole(roleId, updates) {
        return this.request('POST', '/role/update', {
            id: roleId,
            ...updates
        });
    }

    async deleteRole(roleId) {
        return this.request('POST', '/role/delete', {
            id: roleId
        });
    }
}

// 使用示例
(async () => {
    const api = new RoleAPI(
        'http://your-domain.com',
        'AK_xxx',
        'SK_xxx'
    );

    try {
        // 1. 创建角色
        const createResult = await api.createRole(
            '开发团队角色',
            'manager',
            1000000,
            100,
            5000,
            'monthily',
            '开发环境使用的管理员角色'
        );
        console.log('创建角色:', createResult);

        // 2. 获取角色列表
        const listResult = await api.listRoles(1, 10);
        console.log('角色列表:', listResult);

        // 3. 更新角色
        const updateResult = await api.updateRole(1, {
            desc: '更新后的角色描述',
            budget: 8000
        });
        console.log('更新角色:', updateResult);

    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
    }
})();

使用场景示例

场景1：为不同环境创建不同限额的角色

api = RoleAPI(base_url, access_key_id, secret_key)

# 生产环境 - 高限额管理员角色
prod_role = api.create_role(
    name="生产环境管理员",
    desc="生产环境的完整管理权限",
    auth="manager",
    tpm_limit=5000000,    # 500万TPM
    rpm_limit=500,         # 500 RPM
    budget=50000,          # 5万元预算
    budget_kind="monthily"
)

# 测试环境 - 中等限额查看者角色
test_role = api.create_role(
    name="测试环境查看者",
    desc="测试环境的只读权限",
    auth="viewer",
    tpm_limit=1000000,    # 100万TPM
    rpm_limit=100,         # 100 RPM
    budget=5000,           # 5千元预算
    budget_kind="monthily"
)

# 开发环境 - 低限额角色
dev_role = api.create_role(
    name="开发环境角色",
    desc="开发环境使用",
    auth="manager",
    tpm_limit=500000,     # 50万TPM
    rpm_limit=50,          # 50 RPM
    budget=1000,           # 1千元预算
    budget_kind="monthily"
)

场景2：动态调整角色限额

# 月初增加预算
api.update_role(
    role_id=1,
    budget=100000,
    budget_kind="monthily"
)

# 临时提升限额（如压测期间）
api.update_role(
    role_id=1,
    tpm_limit=10000000,
    rpm_limit=1000
)

# 压测结束后恢复
api.update_role(
    role_id=1,
    tpm_limit=5000000,
    rpm_limit=500
)

错误码说明

错误码	说明	解决方法
400	参数错误	检查请求参数是否符合要求
401	未认证	检查AccessKey和签名是否正确
403	权限不足	确认账号具有admin权限
404	角色不存在	检查角色ID是否正确
409	角色名称已存在	更换角色名称
409	角色正在使用中	先解除角色绑定再删除
500	服务器错误	联系技术支持

注意事项

角色名称唯一性: 角色名称在主账号下必须唯一
删除限制: 正在被RAM用户使用的角色无法删除
权限粒度: manager可以管理项目，viewer只能查看和生成Token
限额设置: 建议根据实际需求合理设置RPM、TPM和Budget
预算周期: dayily 表示日预算周期，monthily 表示月预算周期；这是限额周期，不是套餐计费周期

示例运行范围

完整客户端示例需要 Python 3 与 requests；JavaScript 客户端需要 Node.js 与 axios。后续业务片段复用前文创建的客户端实例，不是独立脚本。执行创建、修改或删除前，仅使用获准的测试环境及测试数据。这里的本地语法检查不代表接口联调通过。

角色管理 API

角色管理 API

概述

基础信息

权限说明

角色类型说明

权限类型（permissions）

限额类型

API接口列表

1. 创建角色

接口信息

请求参数

请求示例

响应示例

Python调用示例

2. 获取角色列表

接口信息

请求示例

响应示例

3. 更新角色

接口信息

请求参数

请求示例

响应示例

4. 删除角色

接口信息

请求参数

请求示例

响应示例

完整调用示例

Python完整示例

Node.js完整示例

使用场景示例

场景1：为不同环境创建不同限额的角色

场景2：动态调整角色限额

错误码说明

注意事项

相关文档

示例运行范围