# 更新API Key #### 功能介绍 修改接口赋予了管理员对现有API Key进行动态配置与状态调整的能力。随着业务的迭代，API Key的用途或归属可能会发生变化，该接口支持更新密钥的描述信息以及访问权限范围，确保密钥资产与业务需求保持同步。保障安全的同时保留了业务恢复的灵活性。 接口约束： - 鉴权：调用本接口需在请求头携带有效IAM token（X-Auth-Token），并具备对应细粒度权限：更新操作应使用modelarts:apiKey:create - 租户隔离：接口操作范围由当前 token 所属的Project / Domain 决定，project_id由鉴权上下文自动带入，不支持跨租户操作。 - 不可修改字段：label、id，请求体中传入会被服务端忽略，保留原值。可修改字段：description、allow_all、ip_whitelist、resident_model_version_whitelist、endpoint_whitelist。 #### URI PUT /v2/{project_id}/maas/api-auth/api-keys/{key_id} 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释** ：项目ID，是华为云中用于标识租户资源的唯一编号，与具体的区域（Region）相关联。在调用华为云API时用于定位资源所属的项目空间。 可通过[获取项目ID和名称](https://support.huaweicloud.com/api-maas/api-maas-0028.html)接口获取。 **约束限制**：不涉及 。 **取值范围**：不涉及。 **默认取值**：不涉及。 | | key_id | 是 | String | **参数解释** ：API Key ID。可通过[查询API Key列表](https://support.huaweicloud.com/api-maas/ListApiKeysV2.html)接口获取。 **约束限制**：不涉及 。 **取值范围**：不涉及。 **默认取值**：不涉及。 | #### 请求参数 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | id | 否 | String | **参数解释** ：API Key ID。可通过[查询API Key列表](https://support.huaweicloud.com/api-maas/ListApiKeysV2.html)接口获取。 **约束限制**：不可被修改。 **取值范围**：不涉及。 **默认取值**：不涉及。 | | description | 否 | String | **参数解释**：API Key的描述信息。 最大长度100 字符。 **约束限制**：不涉及。 **取值范围**：不涉及。 **默认取值**：空字符串。 | | allow_all | 是 | Boolean | **参数解释**：是否允许所有IP访问。 **约束限制**：不涉及。 **取值范围**： - true：表示不限制IP。 - false：限制IP。 **默认取值**：true。 | | ip_whitelist | 否 | Array of strings | **参数解释**：API Key的IP白名单是华为云MaaS（模型即服务）中API Key的一项安全功能，用于限制只有指定IP地址才能使用该API Key调用模型服务，防止API Key泄露后被非法利用。取值示例： - 单个IP地址(如：192.168.1.1)。 - IP地址段范围(如：192.168.1.10-192.168.1.100)。 - CIDR网段(如：192.168.10.0/24)。 **约束限制**： - 数量 ≤ 100； - 每个IP须为合法IPv4，支持CIDR格式（如 192.168.0.0/24）； - 不可有重复IP； - CIDR掩码须连续合法； - 当allow_all=true时此项必须为空。 **IP校验规则**： 1. IP单段数值校验：IPv4的每一个段（Octet）必须是0到255之间的有效十进制整数。 2. IP格式与子网掩码校验： - 整体格式必须符合x.x.x.x 或 x.x.x.x/y的正则规范。 - 若包含子网掩码，其数值必须在0到32之间。 - **特殊业务规则**：子网掩码的位数必须大于或等于该IP地址转换为32位二进制后最后一个1所在的位置（即掩码不能截断IP的有效标识位）。 3.**IP 大小比较规则**：比较两个IP时，按从左到右（高位到低位）逐段进行数值比对，以此确定大小关系。 4.**IP 范围校验**：一个合法的IP范围必须严格包含2个IP，且这两个IP均需通过上述的格式与掩码校验，同时起始IP必须小于或等于结束IP。 | | resident_model_version_whitelist | 否 | [ResidentModelVersionWhitelist] object | **参数解释**：常驻模型版本白名单，限制可访问的常驻模型版本。 **取值范围**：不涉及。 | | endpoint_whitelist | 否 | [EndpointWhitelist] object | **参数解释**：自定义接入点白名单，限制可访问的自定义接入点。 **取值范围**：不涉及。 | 表3ResidentModelVersionWhitelist | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | overall | 否 | String | **参数解释**：API Key生效的模型服务范围（包括模型服务以及对应的版本）。 **约束限制**：不涉及。 **取值范围**： 1. all: 表示全部生效。 2. 空字符串：表示非全部生效。 **默认取值**：空字符串。 | | whitelist | 否 | Array of [Whitelist] objects | **参数解释**：常驻模型版本白名单列表，逐条指定可访问的常驻模型及其版本。 **取值范围**：Whitelist对象数组，见下方拆解字段。 | 表4Whitelist | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | resident_model_id | 否 | String | **参数解释**：常驻模型ID。以Chrome浏览器为例，获取常驻模型ID操作如下： 在MaaS控制台的"在线推理-预置服务"页面，使用快捷键F12打开开发者工具，选择"Network"页签，搜索"query"，单击以"query?business_type=payment"开头的名称，在"Response"页签中，按需搜索模型名称，例如搜索DeepSeek-V4.1-Flash，resident_model_id参数值即为常驻模型ID。 **约束限制**：不涉及。 **取值范围**：不涉及。 **默认取值**：不涉及。 | | version_whitelist | 否 | String | **参数解释**：该常驻模型允许访问的版本白名单，多个版本以逗号分隔。以Chrome浏览器为例，获取常驻模型版本名称操作如下： 在MaaS控制台的"在线推理-预置服务"页面，使用快捷键F12打开开发者工具，选择"Network"页签，搜索"query"，单击以"query?business_type=payment"开头的名称，在"Response"页签中，按需搜索模型名称，例如搜索DeepSeek-V4.1-Flash，version_list下对应version_name为DeepSeek-V4.1-Flash的那条数据的id即为常驻模型版本值。 **约束限制**：不涉及。 **取值范围**：不涉及。 **默认取值**：不涉及。 | 表5EndpointWhitelist | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | overall | 否 | String | **参数解释**：整体放行策略。 **约束限制**：不涉及。 **取值范围**："all" 表示放行全部，空字符串表示不启用整体放行。 **默认取值**：空字符串。 | | whitelist | 否 | Array of strings | **参数解释** ：自定义接入点ID白名单列表，仅允许列表内的自定义接入点被访问。可通过[查询自定义接入点](https://support.huaweicloud.com/api-maas/api-maas-0015.html)接口获取ID。 **约束限制**：不涉及。 | #### 响应参数 **状态码：200** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释**：API Key的唯一标识ID，系统自动生成。 **取值范围**：不涉及。 | | api_key | String | **参数解释**：推理服务生成的原始API Key明文（仅在创建时返回一次）。长度 ≤ 255 的字符串。 **取值范围**：不涉及。 | | label | String | **参数解释**：API Key的显示名称，回显请求中的label。 **取值范围**：不涉及。 | | description | String | **参数解释**：API Key的描述信息，回显请求中的description。最大长度100字符。 **取值范围**：不涉及。 | | allow_all | Boolean | **参数解释**：是否允许所有IP访问。 **取值范围**： - true：表示不限制IP。 - false ：限制IP。 | | ip_whitelist | Array of strings | **参数解释**：IP白名单列表，回显实际生效值。 **取值范围**：不涉及。 | | resident_model_version_whitelist | [ResidentModelVersionWhitelist] object | **参数解释**：常驻模型版本白名单信息，回显请求中的值。 **取值范围**：不涉及。 | | endpoint_whitelist | [EndpointWhitelist] object | **参数解释**：自定义接入点白名单信息，回显请求中的值。 **取值范围**：不涉及 。 | 表7ResidentModelVersionWhitelist | 参数 | 参数类型 | 描述 | |:---|:---|:---| | overall | String | **参数解释**：API Key生效的模型服务范围（包括模型服务以及对应的版本）。 **取值范围**： 1. all: 表示全部生效。 2. 空字符串：表示非全部生效。 | | whitelist | Array of [Whitelist] objects | **参数解释**：常驻模型版本白名单列表，逐条指定可访问的常驻模型及其版本。 **取值范围**：Whitelist对象数组，见下方拆解字段。 | 表8Whitelist | 参数 | 参数类型 | 描述 | |:---|:---|:---| | resident_model_id | String | **参数解释**：常驻模型ID。以Chrome浏览器为例，获取常驻模型ID操作如下： 在MaaS控制台的"在线推理-预置服务"页面，使用快捷键F12打开开发者工具，选择"Network"页签，搜索"query"，单击以"query?business_type=payment"开头的名称，在"Response"页签中，按需搜索模型名称，例如搜索DeepSeek-V4.1-Flash，resident_model_id参数值即为常驻模型ID。 **取值范围**：不涉及。 | | version_whitelist | String | **参数解释**：该常驻模型允许访问的版本白名单，多个版本以逗号分隔。以Chrome浏览器为例，获取常驻模型版本名称操作如下： 在MaaS控制台的"在线推理-预置服务"页面，使用快捷键F12打开开发者工具，选择"Network"页签，搜索"query"，单击以"query?business_type=payment"开头的名称，在"Response"页签中，按需搜索模型名称，例如搜索DeepSeek-V4.1-Flash，version_list下对应version_name为DeepSeek-V4.1-Flash的那条数据的id即为常驻模型版本值。 **取值范围**：不涉及。 | 表9EndpointWhitelist | 参数 | 参数类型 | 描述 | |:---|:---|:---| | overall | String | **参数解释**：整体放行策略。 **取值范围**："all" 表示放行全部，空字符串表示不启用整体放行。 | | whitelist | Array of strings | **参数解释** ：自定义接入点ID白名单列表，仅允许列表内的自定义接入点被访问。可通过[查询自定义接入点](https://support.huaweicloud.com/api-maas/api-maas-0015.html)接口获取ID。 | **状态码：403** 表10响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_msg | String | **参数解释**：错误信息描述。 **取值范围**：不涉及。 | | error_code | String | **参数解释**：错误码。 **取值范围**：不涉及。 | #### 请求示例 - 权限范围不限制 ``` PUT https://{endpoint}/v2/{project_id}/maas/api-auth/api-keys/801dbb99-34e6-43c0-a6b0-a45695c2a653 { "description" : "test-修改", "allow_all" : true } ``` - 权限范围自定义 ``` PUT https://{endpoint}/v2/{project_id}/maas/api-auth/api-keys/801dbb99-34e6-43c0-a6b0-a45695c2a653 { "description" : "test-修改1", "allow_all" : false, "ip_whitelist" : [ "192.168.1.1", "192.168.1.10-192.168.1.100", "192.168.10.0/24" ], "resident_model_version_whitelist" : { "overall" : "", "whitelist" : [ { "resident_model_id" : "8f7b4934-88a5-48ed-8188-f479e202453f", "version_whitelist" : "all" }, { "resident_model_id" : "2e34e492-5920-4d12-9910-7cef0d0f6a44", "version_whitelist" : "91d41083-2b04-4f78-b346-ba455ee4fa62" } ] }, "endpoint_whitelist" : { "overall" : "none", "whitelist" : [ ] } } ``` #### 响应示例 **状态码：200** ``` { "id" : "801dbb99-34e6-43c0-a6b0-a45695c2a653", "label" : "ak-ooKnYK", "description" : "test-修改1", "allow_all" : false, "ip_whitelist" : [ "192.168.1.1", "192.168.1.10-192.168.1.100", "192.168.10.0/24" ], "resident_model_version_whitelist" : { "overall" : "", "whitelist" : [ { "resident_model_id" : "8f7b4934-88a5-48ed-8188-f479e202453f", "version_whitelist" : "all" }, { "resident_model_id" : "2e34e492-5920-4d12-9910-7cef0d0f6a44", "version_whitelist" : "91d41083-2b04-4f78-b346-ba455ee4fa62" } ] }, "endpoint_whitelist" : { "overall" : "none", "whitelist" : [ ] } } ``` **状态码：403** ``` { "error_msg" : "Invalid token.", "error_code" : "ModelArts.0104" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 修改API Key成功 | | 403 | 用户鉴权token异常 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-maas/ErrorCode.html)。