文档

API 属性说明

更新时间:
一键部署

本文将列出在 CNStack 控制台创建并发布 API 时,您需要配置的相关属性。

API 定义

基本信息

属性

必填项

说明

API 名称

  • 用于识别 API。

  • 支持中文、英文、数字、下划线(_)、连接符(-),且只能以英文和中文开头。32 个字符以内。

  • 同一个 工作空间下 API 名称不能相同。

是否基于已有API创建

  • 默认关闭

  • 开启后可选择已创建的 API 作为模板。

API 分组

  • 用于将 API 进行逻辑的分组,分组下的 API 相同的分组 ID 进行隔离。

  • 同一个环境下,API 分组名称不能相同。

  • API 分组名称:支持英文字母、中文、数字、下划线(_)、连接符(-),32 个字符以内。

API 描述

用于描述 API 的作用等,64 个字符以内。

应用

  • 应用:表示 API 发布后支持 web 浏览器、H5 容器、小程序、JS、业务系统的调用。

  • mPaas移动应用:表示 API 发布后支持 mPaaS 移动客户端(iOS、Android)的调用。

  • 应用以及 mPaas 移动应用:表示 API 发布后支持 web 浏览器、H5 容器、小程序、JS、业务系统的调用,同时也支持 mPaaS 移动客户端(iOS、Android)的调用。

OperationType

  • 针对 mPaaS 移动应用设置的 API 服务标识,用于定位要访问的资源。

  • 支持英文字母、数字、英文句号(.),200 字符以内。

  • 需按照 com.xxx.opt1的格式输入。

请求路径

  • 表示请求的资源的 URL,通过请求路径可以定位到要请求的资源。

  • 支持英文字母、数字、下划线(_)、连接符(-),200 字符以内。

  • 以斜杠(/ )开头,不能以斜杠(/ )结尾,格式示例:/getUserInfo

  • 支持占位符模式 /home/{id},如果需要占位符透传控制面,API 的后端请求路径需要为空。

方法

表明要对给定的 HTTP 资源执行的操作:

  • GET:检索服务器中的数据。

  • POST:将数据发送到服务器进行处理。

  • PUT:更新服务器中存储的数据。

  • DELETE:删除服务器中的数据。

路径匹配规则

  • 绝对匹配:调用时完全匹配以上填写的路径,例如:/path

  • 前缀匹配:以请求路径为前缀,可匹配多个前缀一样的不同路径,例如:填写 /path的匹配效果为 /path/*

安全认证

  • 根据实际需要自行选择。支持密钥认证、无需认证、OAuth 认证、Key-Auth 认证、Basic-Auth 认证和 JWT 认证。

接口名称

  • 客户端 RPC 服务或者 DUBBO 服务需要订阅的接口名称。

  • API 接口名称,支持英文字母、数字、英文句号(.)、冒号(:)、@,以小写字母作为开头。

  • 格式示例:com.alipay.testapp.facade.ConfigFacade:1.0@DEFAULT

服务标识

选填,支持通过 uniqueId 指定服务。

方法名

  • 客户端 RPC 服务或者 DUBBO 服务需要订阅的接口名称。

  • API 服务方法名,支持英文字母、数字组成,以字母作为开头。

  • 格式示例:getUserID

报文类型

表示请求和响应中的媒体类型信息,用来告诉服务端如何处理请求的数据,以及告诉客户端(一般是浏览器)如何解析响应的数据。

报文编码

表示客户端接受文本内容的字符集样式。

实体参数

客户端 DUBBO 服务接口方法使用的实体参数全路径,例如:Ljava/lang/String,自定义参数实体时注意以分号(;)结尾。

返回参数

客户端 DUBBO 服务接口方法返回参数全路径,例如:Ljava/lang/String,自定义参数实体时注意以分号(;)结尾。

DUBBO 分组

客户端 DUBBO 服务接口订阅时的服务分组。

请求参数

请求参数表示客户端向网关发起请求时要配置的参数。

属性

必填项

说明

参数名

参数的唯一标识。

参数位置

  • Header:自定义 API 请求头。例如 X-MyHeader: Value

  • Path:参数为请求 URL 路径的一部分。例如 /users/{id}

  • Query:参数在请求 URL 末尾的问号 ?之后以 name=value形式出现。参数之间以 &分隔。例如 /users?role=admin&id=12345

类型

  • String

  • Int

  • Long

  • Double

  • Float

  • Boolean

默认值

在 API 请求的参数值为空时使用的默认值。 默认值类型必须和参数类型一致。

描述

参数的业务描述。

请求 Body 类型

请求 Body 类型表示客户端向网关发起请求时要配置的参数,可以依赖已经创建数据模型。

API 在使用编排功能时必须选择数据模型才能实现参数转换以及透传,在 API 分组中若想要生成 SDK 必须在请求 Body 或者响应 Body 选择数据模型才能成功。

  • Long

  • Int

  • Float

  • Double

  • Boolean

  • Byte

  • Short

  • String

  • List:可以选择基础类型或者数据模型作为参数模板。

  • Object:需要选择数据模型作为参数模板。

  • Map:可以选择基础类型或者数据模型作为参数模板。

响应参数

属性

必填项

说明

成功响应示例

为 API 订阅者提供请求成功时的返回数据参考。

失败响应示例

为 API 订阅者提供请求失败时的返回数据参考。

错误码

HTTP 默认错误代码。

错误信息

自定义错误提示信息。

描述

错误码的业务描述。

响应body类型

响应的参数,可以依赖数据模型

API 在使用编排功能时必须选择数据模型才能实现参数转换以及透传,在 API 分组中若想要生成 SDK 必须在请求 Body 或者响应 Body 选择数据模型才能成功。

  • Long

  • Int

  • Float

  • Double

  • Boolean

  • Byte

  • Short

  • String

  • List:可以选择基础类型或者数据模型作为参数模板。

  • Object:需要选择数据模型作为参数模板。

  • Map:可以选择基础类型或者数据模型作为参数模板。

后端配置

属性

必填项

说明

后端服务类型

表示网关接收到请求后转发给的后端服务类型:

  • Mock:表示如果接口后端还没有提供,使用 Mock 用于模拟一个后端服务。

  • 系统集群:表示网关接收到前端请求后转发到真实业务系统的集群。

协议类型

表示网关接收到请求后转发给的后端服务使用的通信协议类型:

  • HTTP

  • SOFARPC

  • SOFAREST

  • DUBBO

  • DUBBOX

请求路径

服务端的实际请求路径,不填默认使用 API 定义中的请求路径。

路径截取级数

仅支持数字格式。

拼接路径前缀

表示请求到后端时显示的路径信息,必须以 / 开头,但不能以 / 结尾。

超时时间

API 请求超时时间,单位为毫秒(ms),默认 3000 毫秒。

路由策略

表示当网关接收到语法后使用的路由策略:

  • 根据 Header 路由:根据 Header 里带的参数路由

  • 根据 LDC 路由:使用 LDC 单元化路由。

  • 根据权重路由:数值范围为 0-100,所有规则加起来为 100。

  • 根据请求路径路由:直接转发。

接口名称

  • 服务端 RPC 服务、SOFAREST、DUBBO 服务发布的接口名称。

  • API 接口名称,支持英文字母、数字、英文句号(.)、冒号(:)、@,以小写字母作为开头。

  • 格式示例:com.alipay.testapp.facade.ConfigFacade:1.0@DEFAULT

方法名

  • 服务的 RPC 服务或者 DUBBO 服务需要订阅的接口方法名称。

  • API 服务方法名,支持英文字母、数字组成,以字母作为开头。

  • 格式示例:getUserID

实体参数

服务端 DUBBO 服务接口方法使用的实体参数全路径,例如:Ljava/lang/String,自定义参数实体时注意以分号(;)结尾。

返回参数

服务端 DUBBO 服务接口方法返回参数全路径,例如:Ljava/lang/String,自定义参数实体时注意以分号(;)结尾。

DUBBO 分组

服务端 DUBBO 服务接口订阅时的服务分组。

系统集群

选择后端需要绑定的系统集群。

参数映射配置

配置响应参数和请求参数映射,可选已创建的参数映射规则。

  • 本页导读 (0)
文档反馈