文档首页/ 智能体开发平台 AgentArts/ API参考/ API/ 网关/ 网关后端管理/ 更新目标服务 - UpdateCoreGatewayTarget
更新时间：2026-04-15 GMT+08:00
查看PDF
分享

更新目标服务 - UpdateCoreGatewayTarget

功能介绍

更新现有目标服务的配置。

URI

PUT /v1/core/gateways/{gateway_id}/targets/{target_id}

表1 路径参数

参数

是否必选

参数类型

描述

gateway_id

是

String

参数解释：

网关的唯一标识符。

网关ID获取方式：

  1. 进入AgentArts平台，在左侧导航栏选择“开发中心 > 组件库 ”，选择“网关”页签。

  2. 在网关列表中“网关名称/ID”处复制网关ID即可。

约束范围：

不涉及。

取值范围：

匹配标准的UUID格式（8-4-4-4-12的十六进制数字串，由连字符分隔），符合正则条件^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$。

默认取值：

不涉及。

target_id

是

String

参数解释：

目标服务的唯一标识符。

约束范围：

不涉及。

取值范围：

匹配标准的UUID格式（8-4-4-4-12的十六进制数字串，由连字符分隔），符合正则条件^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$。

默认取值：

不涉及。

请求参数

表2 请求Body参数

参数

是否必选

参数类型

描述

name

否

String

参数解释：

更新后的目标服务名称。

约束范围：

同一网关内目标服务名称唯一。

取值范围：

长度为 1-50 个字符，匹配以字母数字开头和结尾、中间可含0到48个字母数字或短横线的字符串，符合正则条件^[a-zA-Z0-9]([a-zA-Z0-9-]{0,48}[a-zA-Z0-9])?$。

默认取值：

不涉及。

description

否

String

参数解释：

更新后的目标服务描述。

约束范围：

不涉及。

取值范围：

长度为 0-200 个字符。

默认取值：

不涉及。

target_configuration

否

CoreGatewayTargetConfiguration object

参数解释：

目标服务配置，支持多种目标服务类型。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

credential_provider_configuration

否

CoreGatewayCredentialProviderConfiguration object

参数解释：

凭证提供者配置。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表3 CoreGatewayTargetConfiguration

参数

是否必选

参数类型

描述

mcp_server

否

CoreGatewayMcpServerTargetConfiguration object

参数解释：

MCP目标服务配置。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

openapi

否

CoreGatewayOpenApiTargetConfiguration object

参数解释：

OpenAPI 规范目标配置，支持内联文档或从 OBS 获取规范文档。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表4 CoreGatewayMcpServerTargetConfiguration

参数

是否必选

参数类型

描述

endpoint

是

String

参数解释：

MCP服务器端点 URL。

约束范围：

不涉及。

取值范围：

长度为 1-512个字符，匹配以 https:// 开头的任意字符串，符合正则条件https://.*。

默认取值：

不涉及。

server_type

是

String

参数解释：

MCP 服务器类型。

约束范围：

不涉及。

取值范围：

  • sse: 使用 Server-Sent Events 长连接

  • streamable_http: 使用可流式 HTTP 请求

默认取值：

不涉及。
表5 CoreGatewayOpenApiTargetConfiguration

参数

是否必选

参数类型

描述

payload

否

String

参数解释：

OpenAPI 规范文档内容（JSON 或 YAML 格式的内联内容）。

约束范围：

不涉及。

取值范围：

长度为 1-1048576 个字符。

默认取值：

不涉及。

obs

否

CoreGatewayObsConfiguration object

参数解释：

OBS（对象存储服务）配置，用于从 OBS 获取 OpenAPI 规范文档。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表6 CoreGatewayObsConfiguration

参数

是否必选

参数类型

描述

bucket_name

是

String

参数解释：

OBS 桶名称。

约束范围：

不涉及。

取值范围：

长度为 3-63 个字符，匹配单个小写字母或数字，或者以字母数字开头和结尾、中间可含1到61个小写字母/数字/点/短横线的字符串，符合正则条件^[a-z0-9]([a-z0-9.-]{1,61}[a-z0-9])?$。

默认取值：

不涉及。

object_key

是

String

参数解释：

OBS 对象键名（文件路径）：

  • 示例：specs/petstore.yaml

约束范围：

不涉及。

取值范围：

长度为 1-1024 个字符。

默认取值：

不涉及。
表7 CoreGatewayCredentialProviderConfiguration

参数

是否必选

参数类型

描述

credential_provider_type

是

String

参数解释：

凭证提供者类型。

约束范围：

不涉及。

取值范围：

  • iam: 使用网关 IAM 角色（目前暂不支持）

  • oauth: 使用 OAuth 2.0

  • api_key: 使用 API 密钥

  • none: 无认证

默认取值：

不涉及。

credential_provider

否

CoreGatewayCredentialProvider object

参数解释：

凭证提供者配置。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表8 CoreGatewayCredentialProvider

参数

是否必选

参数类型

描述

api_key_credential_provider

否

CoreGatewayApiKeyCredentialProvider object

参数解释：

API KEY凭证提供者配置。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

oauth_credential_provider

否

CoreGatewayOAuthCredentialProvider object

参数解释：

OAuth凭证提供者配置。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

iam_credential_provider

否

CoreGatewayIamCredentialProvider object

参数解释：

Iam凭证提供者配置。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表9 CoreGatewayApiKeyCredentialProvider

参数

是否必选

参数类型

描述

provider_name

是

String

参数解释：

凭证提供者名称。

约束范围：

不涉及。

取值范围：

长度为 1-56 个字符，由字母、数字、下划线或短横线组成的、长度为1到56个字符的字符串，符合正则条件^[a-zA-Z0-9_-]{1,56}$。

默认取值：

不涉及。

credential_location

是

String

参数解释：

凭证传递位置。

约束范围：

不涉及。

取值范围：

  • header: 通过 HTTP 请求头传递 API 密钥

  • query: 通过 URL 查询参数传递 API 密钥

默认取值：

不涉及。

credential_parameter_name

否

String

参数解释：

凭证参数名称。

约束范围：

不涉及。

取值范围：

长度为 0-64 个字符。

默认取值：

Authorization。

credential_prefix

否

String

参数解释：

凭证前缀（如 "Bearer "）。

约束范围：

不涉及。

取值范围：

长度为 0-64 个字符。

默认取值：

不涉及。
表10 CoreGatewayOAuthCredentialProvider

参数

是否必选

参数类型

描述

provider_name

是

String

参数解释：

凭证提供者名称。

约束范围：

不涉及。

取值范围：

长度为 1-56 个字符，由字母、数字、下划线或短横线组成的、长度为1到56个字符的字符串，符合正则条件^[a-zA-Z0-9_-]{1,56}$。

默认取值：

不涉及。

grant_type

是

String

参数解释：

OAuth 授权类型。

约束范围：

不涉及。

取值范围：

  • client_credentials: 适用于服务器到服务器通信

  • authorization_code: 适用于需要用户授权的应用

默认取值：

不涉及。

scopes

否

Array of strings

参数解释：

OAuth 作用域列表。

约束范围：

不涉及。

取值范围：

数组长度为 0-100。

默认取值：

不涉及。

default_return_url

否

String

参数解释：

默认返回 URL。

约束范围：

不涉及。

取值范围：

长度为 0-2048，匹配由单词字符组成的协议名、冒号、零到两个斜杠，以及后续非空白字符序列的字符串，符合正则条件\w+:(/?/?)[^\s]+。

默认取值：

不涉及。

custom_parameters

否

Map<String,String>

参数解释：

自定义参数，键值对形式。

约束范围：

不涉及。

取值范围：

  • 键：遵循 RFC 3986 URL 查询参数规范，最大长度 64，不允许为空

  • 值：支持任意可打印 ASCII 字符，最大长度 255，可以为空

默认取值：

不涉及。
表11 CoreGatewayIamCredentialProvider

参数

是否必选

参数类型

描述

provider_name

是

String

参数解释：

凭证提供者名称。

约束范围：

不涉及。

取值范围：

长度为 1-56 个字符，由字母、数字、下划线或短横线组成的、长度为1到56个字符的字符串，符合正则条件^[a-zA-Z0-9_-]{1,56}$。

默认取值：

不涉及。

响应参数

状态码：200

表12 响应Body参数

参数

参数类型

描述

target

CoreGatewayTarget object

参数解释：

目标服务详情。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表13 CoreGatewayTarget

参数

参数类型

描述

target_id

String

参数解释：

目标服务的唯一标识符。

约束范围：

不涉及。

取值范围：

匹配标准的UUID格式（8-4-4-4-12的十六进制数字串，由连字符分隔），符合正则条件^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$。

默认取值：

不涉及。

gateway_id

String

参数解释：

所属网关的标识符。

约束范围：

不涉及。

取值范围：

匹配标准的UUID格式（8-4-4-4-12的十六进制数字串，由连字符分隔），符合正则条件^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$。

默认取值：

不涉及。

name

String

参数解释：

目标服务名称。

约束范围：

同一网关内目标服务名称唯一。

取值范围：

长度为 1-50 个字符，匹配以字母数字开头和结尾、中间可含0到48个字母数字或短横线的字符串，符合正则条件^[a-zA-Z0-9]([a-zA-Z0-9-]{0,48}[a-zA-Z0-9])?$。

默认取值：

不涉及。

description

String

参数解释：

目标服务描述。

约束范围：

不涉及。

取值范围：

长度为 1-200 个字符。

默认取值：

不涉及。

status

String

参数解释：

目标服务状态。

约束范围：

不涉及。

取值范围：

  • creating: 创建中

  • updating: 更新中

  • ready: 就绪可用

  • failed: 失败

  • deleting: 删除中

默认取值：

不涉及。

target_type

String

参数解释：

目标服务类型。

约束范围：

不涉及。

取值范围：

  • mcp_server: MCP 服务器

  • openapi: 基于 OpenAPI 规范的 REST API

默认取值：

不涉及。

target_configuration

CoreGatewayTargetConfiguration object

参数解释：

目标服务配置，支持多种目标服务类型。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

credential_provider_configuration

CoreGatewayCredentialProviderConfiguration object

参数解释：

凭证提供者配置。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

created_at

String

参数解释：

创建时间。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

updated_at

String

参数解释：

最后更新时间。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表14 CoreGatewayTargetConfiguration

参数

参数类型

描述

mcp_server

CoreGatewayMcpServerTargetConfiguration object

参数解释：

MCP目标服务配置。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

openapi

CoreGatewayOpenApiTargetConfiguration object

参数解释：

OpenAPI 规范目标配置，支持内联文档或从 OBS 获取规范文档。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表15 CoreGatewayMcpServerTargetConfiguration

参数

参数类型

描述

endpoint

String

参数解释：

MCP服务器端点 URL。

约束范围：

不涉及。

取值范围：

长度为 1-512个字符，匹配以 https:// 开头的任意字符串，符合正则条件https://.*。

默认取值：

不涉及。

server_type

String

参数解释：

MCP 服务器类型。

约束范围：

不涉及。

取值范围：

  • sse: 使用 Server-Sent Events 长连接

  • streamable_http: 使用可流式 HTTP 请求

默认取值：

不涉及。
表16 CoreGatewayOpenApiTargetConfiguration

参数

参数类型

描述

payload

String

参数解释：

OpenAPI 规范文档内容（JSON 或 YAML 格式的内联内容）。

约束范围：

不涉及。

取值范围：

长度为 1-1048576 个字符。

默认取值：

不涉及。

obs

CoreGatewayObsConfiguration object

参数解释：

OBS（对象存储服务）配置，用于从 OBS 获取 OpenAPI 规范文档。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表17 CoreGatewayObsConfiguration

参数

参数类型

描述

bucket_name

String

参数解释：

OBS 桶名称。

约束范围：

不涉及。

取值范围：

长度为 3-63 个字符，匹配单个小写字母或数字，或者以字母数字开头和结尾、中间可含1到61个小写字母/数字/点/短横线的字符串，符合正则条件^[a-z0-9]([a-z0-9.-]{1,61}[a-z0-9])?$。

默认取值：

不涉及。

object_key

String

参数解释：

OBS 对象键名（文件路径）：

  • 示例：specs/petstore.yaml

约束范围：

不涉及。

取值范围：

长度为 1-1024 个字符。

默认取值：

不涉及。
表18 CoreGatewayCredentialProviderConfiguration

参数

参数类型

描述

credential_provider_type

String

参数解释：

凭证提供者类型。

约束范围：

不涉及。

取值范围：

  • iam: 使用网关 IAM 角色（目前暂不支持）

  • oauth: 使用 OAuth 2.0

  • api_key: 使用 API 密钥

  • none: 无认证

默认取值：

不涉及。

credential_provider

CoreGatewayCredentialProvider object

参数解释：

凭证提供者配置。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表19 CoreGatewayCredentialProvider

参数

参数类型

描述

api_key_credential_provider

CoreGatewayApiKeyCredentialProvider object

参数解释：

API KEY凭证提供者配置。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

oauth_credential_provider

CoreGatewayOAuthCredentialProvider object

参数解释：

OAuth凭证提供者配置。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

iam_credential_provider

CoreGatewayIamCredentialProvider object

参数解释：

Iam凭证提供者配置。

约束范围：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表20 CoreGatewayApiKeyCredentialProvider

参数

参数类型

描述

provider_name

String

参数解释：

凭证提供者名称。

约束范围：

不涉及。

取值范围：

长度为 1-56 个字符，由字母、数字、下划线或短横线组成的、长度为1到56个字符的字符串，符合正则条件^[a-zA-Z0-9_-]{1,56}$。

默认取值：

不涉及。

credential_location

String

参数解释：

凭证传递位置。

约束范围：

不涉及。

取值范围：

  • header: 通过 HTTP 请求头传递 API 密钥

  • query: 通过 URL 查询参数传递 API 密钥

默认取值：

不涉及。

credential_parameter_name

String

参数解释：

凭证参数名称。

约束范围：

不涉及。

取值范围：

长度为 0-64 个字符。

默认取值：

Authorization。

credential_prefix

String

参数解释：

凭证前缀（如 "Bearer "）。

约束范围：

不涉及。

取值范围：

长度为 0-64 个字符。

默认取值：

不涉及。
表21 CoreGatewayOAuthCredentialProvider

参数

参数类型

描述

provider_name

String

参数解释：

凭证提供者名称。

约束范围：

不涉及。

取值范围：

长度为 1-56 个字符，由字母、数字、下划线或短横线组成的、长度为1到56个字符的字符串，符合正则条件^[a-zA-Z0-9_-]{1,56}$。

默认取值：

不涉及。

grant_type

String

参数解释：

OAuth 授权类型。

约束范围：

不涉及。

取值范围：

  • client_credentials: 适用于服务器到服务器通信

  • authorization_code: 适用于需要用户授权的应用

默认取值：

不涉及。

scopes

Array of strings

参数解释：

OAuth 作用域列表。

约束范围：

不涉及。

取值范围：

数组长度为 0-100。

默认取值：

不涉及。

default_return_url

String

参数解释：

默认返回 URL。

约束范围：

不涉及。

取值范围：

长度为 0-2048，匹配由单词字符组成的协议名、冒号、零到两个斜杠，以及后续非空白字符序列的字符串，符合正则条件\w+:(/?/?)[^\s]+。

默认取值：

不涉及。

custom_parameters

Map<String,String>

参数解释：

自定义参数，键值对形式。

约束范围：

不涉及。

取值范围：

  • 键：遵循 RFC 3986 URL 查询参数规范，最大长度 64，不允许为空

  • 值：支持任意可打印 ASCII 字符，最大长度 255，可以为空

默认取值：

不涉及。
表22 CoreGatewayIamCredentialProvider

参数

参数类型

描述

provider_name

String

参数解释：

凭证提供者名称。

约束范围：

不涉及。

取值范围：

长度为 1-56 个字符，由字母、数字、下划线或短横线组成的、长度为1到56个字符的字符串，符合正则条件^[a-zA-Z0-9_-]{1,56}$。

默认取值：

不涉及。

状态码：400

表23 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。

取值范围：

取值为固定18个字符，匹配以 AgentArts. 开头、后接恰好8位数字的字符串，符合正则条件^AgentArts.[0-9]{8}$。

error_msg

String

参数解释：

错误消息。

取值范围：

取值为 1-256 个字符，匹配由字母、数字、空格、中文汉字以及常见中英文标点符号组成的非空字符串，符合正则条件^[a-zA-Z0-9\s\u4e00-\u9fff.,!?;:()'"-\u3002\uff0c\uff01\uff1f\uff1b\uff1a\uff08\uff09]+$。

error_reason

String

参数解释：

错误原因。

取值范围：

取值为 1-256 个字符，匹配由字母、数字、空格、中文汉字以及常见中英文标点符号组成的非空字符串，符合正则条件^[a-zA-Z0-9\s\u4e00-\u9fff.,!?;:()'"-\u3002\uff0c\uff01\uff1f\uff1b\uff1a\uff08\uff09]+$。

error_suggestion

String

参数解释：

错误处理建议。

取值范围：

取值为 1-256 个字符，匹配由字母、数字、空格、中文汉字以及常见中英文标点符号组成的非空字符串，符合正则条件^[a-zA-Z0-9\s\u4e00-\u9fff.,!?;:()'"-\u3002\uff0c\uff01\uff1f\uff1b\uff1a\uff08\uff09]+$。

状态码：404

表24 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。

取值范围：

取值为固定18个字符，匹配以 AgentArts. 开头、后接恰好8位数字的字符串，符合正则条件^AgentArts.[0-9]{8}$。

error_msg

String

参数解释：

错误消息。

取值范围：

取值为 1-256 个字符，匹配由字母、数字、空格、中文汉字以及常见中英文标点符号组成的非空字符串，符合正则条件^[a-zA-Z0-9\s\u4e00-\u9fff.,!?;:()'"-\u3002\uff0c\uff01\uff1f\uff1b\uff1a\uff08\uff09]+$。

error_reason

String

参数解释：

错误原因。

取值范围：

取值为 1-256 个字符，匹配由字母、数字、空格、中文汉字以及常见中英文标点符号组成的非空字符串，符合正则条件^[a-zA-Z0-9\s\u4e00-\u9fff.,!?;:()'"-\u3002\uff0c\uff01\uff1f\uff1b\uff1a\uff08\uff09]+$。

error_suggestion

String

参数解释：

错误处理建议。

取值范围：

取值为 1-256 个字符，匹配由字母、数字、空格、中文汉字以及常见中英文标点符号组成的非空字符串，符合正则条件^[a-zA-Z0-9\s\u4e00-\u9fff.,!?;:()'"-\u3002\uff0c\uff01\uff1f\uff1b\uff1a\uff08\uff09]+$。

状态码：500

表25 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。

取值范围：

取值为固定18个字符，匹配以 AgentArts. 开头、后接恰好8位数字的字符串，符合正则条件^AgentArts.[0-9]{8}$。

error_msg

String

参数解释：

错误消息。

取值范围：

取值为 1-256 个字符，匹配由字母、数字、空格、中文汉字以及常见中英文标点符号组成的非空字符串，符合正则条件^[a-zA-Z0-9\s\u4e00-\u9fff.,!?;:()'"-\u3002\uff0c\uff01\uff1f\uff1b\uff1a\uff08\uff09]+$。

error_reason

String

参数解释：

错误原因。

取值范围：

取值为 1-256 个字符，匹配由字母、数字、空格、中文汉字以及常见中英文标点符号组成的非空字符串，符合正则条件^[a-zA-Z0-9\s\u4e00-\u9fff.,!?;:()'"-\u3002\uff0c\uff01\uff1f\uff1b\uff1a\uff08\uff09]+$。

error_suggestion

String

参数解释：

错误处理建议。

取值范围：

取值为 1-256 个字符，匹配由字母、数字、空格、中文汉字以及常见中英文标点符号组成的非空字符串，符合正则条件^[a-zA-Z0-9\s\u4e00-\u9fff.,!?;:()'"-\u3002\uff0c\uff01\uff1f\uff1b\uff1a\uff08\uff09]+$。

请求示例

{
  "name" : "my-updated-target",
  "description" : "更新后的目标服务描述",
  "target_configuration" : {
    "mcp_server" : {
      "endpoint" : "https://example.com/mcp-updated",
      "server_type" : "streamable_http"
    }
  },
  "credential_provider_configuration" : {
    "credential_provider_type" : "oauth",
    "credential_provider" : {
      "oauth_credential_provider" : {
        "provider_name" : "my-oauth-provider",
        "grant_type" : "client_credentials",
        "scopes" : [ "read", "write" ]
      }
    }
  }
}

响应示例

状态码：200

目标服务更新成功

{
  "target" : {
    "target_id" : "6960fa91-d304-4a01-94c4-90c03bf3df14",
    "gateway_id" : "b2fc0463-8b28-46c5-87ba-6267295ffc57",
    "name" : "my-updated-target",
    "description" : "更新后的目标服务描述",
    "status" : "ready",
    "target_type" : "mcp_server",
    "target_configuration" : {
      "mcp_server" : {
        "endpoint" : "https://example.com/mcp",
        "server_type" : "sse"
      }
    },
    "credential_provider_configuration" : {
      "credential_provider_type" : "api_key",
      "credential_provider" : {
        "api_key_credential_provider" : {
          "provider_name" : "my-secret-provider",
          "credential_location" : "header",
          "credential_parameter_name" : "X-API-Key"
        }
      }
    },
    "created_at" : "2024-01-15T10:30:00Z",
    "updated_at" : "2024-01-15T11:30:00Z"
  }
}

状态码：400

无效的请求体

{
  "error_code" : "AgentArts.02000001",
  "error_msg" : "请求体格式不正确"
}

状态码：404

网关或目标服务未找到

{
  "error_code" : "AgentArts.02000201",
  "error_msg" : "网关或目标服务未找到"
}

状态码：500

内部服务器错误

{
  "error_code" : "AgentArts.02000500",
  "error_msg" : "内部服务器错误"
}

状态码

状态码

描述

200

目标服务更新成功

400

无效的请求体

404

网关或目标服务未找到

500

内部服务器错误

错误码

请参见错误码。

父主题： 网关后端管理

相关文档