创建API

最近更新时间:2020-07-17 15:30:37

操作说明

  • 创建 API 需要填写API的定义信息:基本信息、定义API请求、定义后端服务和定义返回结果。
  • API 创建成功后需要对API进行调试。经测试证明 API可用后,可发布上线供用户使用。

在 API 网关控制台中 API 列表 页面,单击 创建 API,即进入 API 的创建和定义流程。

设置基本信息

1)API名称:API 名称标识需在所属分组内具有唯一性

2)API 分组:分组是 API 的管理单元。创建 API 之前,您需要先创建分组。

3)类型

  • 公开 类型的 API:所有用户均可以在 API 网关控制台,已发布 API 页面看到 API 的部分信息。公开 类型的 API 会跟随 API 分组上架到云市场,供用户购买和调用。
  • 私有 类型的 API:不能上架到云市场中售卖。如果有用户想要调用您的私有类型的 API ,需要您主动操作授权,否则用户无渠道获取 API 信息。

4)安全认证

  • APP认证:要求请求者调用该 API 时,需通过对 APP 的身份认证。由API网关服务负责接口请求的安全认证。
  • IAM认证:表示借助IAM服务进行安全认证。
  • 无认证:即任何人知晓该 API 的请求定义后,均可发起请求,网关不对其做身份验证,均会将请求转发至您的后端服务。(强烈不建议使用此模式。) 推荐使用APP认证方式

5)描述:API 功能描述。

设置API前端请求定义

这部分是定义用户如何请求您的 API ,包括协议、请求Path、HTTP Method、入参请求模式、和入参定义。

1)域名:系统自动为您分配的对应分组的子域名

2)协议:分三种HTTP、HTTPS、HTTP&HTTPS。传输重要或敏感数据时推荐使用HTTPS。

3)请求Path:Path 指相对于服务 Host, API 的请求路径。请求 Path 可以与后端服务实际 Path 不同,您可以随意撰写合法的有明确语义的 Path 给用户使用。您可以在请求 Path 中配置动态参数,即要求用户在 Path 中传入参数,同时您的后端又可以不在 Path 中接收参数,而是映射为在 Query、Header 等位置接收。

4)匹配模式

  • 绝对匹配:调用的请求Path固定为创建时填写的API请求Path。
  • 前缀匹配:调用的请求Path将以创建时填写的API请求Path为前缀,支持接口定义多个不同Path。
  • 例如,请求路径为/test/aa,使用前缀匹配时,通过/test/aa/cc可以访问,但是通过/test/aacc无法访问。

5)Method:支持GET、POST、DELETE、PUT、PATCH、HEAD、OPTIONS、ANY。其中ANY表示该API支持任意请求方法。

6)支持CORS:是否开启跨域访问CORS(cross-origin resource sharing)。CORS允许浏览器向跨域服务器,发出XMLHttpRequest请求,从而克服了AJAX只能同源使用的限制。目前支持简单跨域请求。

7)入参定义

  • 参数名:展示给用户的参数名称。
  • 参数位置:参数在请求中的位置,包含path、 head、query、body。如果您在 Path 中配置了动态参数,必须存在参数位置为path的同名参数。
  • 类型:字段的类型,支持:string、int、boolean。
  • 必填:指此参数是否为必填。当选择为 是 时,API 网关会校验用户的请求中是否包含了此参数。若不包含此参数,则拒绝该请求。
  • 默认值:当 必填 为 否 时生效。在用户请求中不包含此参数时,API 网关自动添加默认值发送给后端服务。
  • 示例:指参数的填写示例。
  • 描述:参数的用途描述及使用注意事项等。

8)请求body 当body非表单选项,比如二进制、json时。可以填写如下信息:

  • body内容描述:用于描述body的数据格式
  • 模型:可以选择此分组下的模型

定义后端服务信息

这部分主要是定义一些参数的前后端映射,即 API 后端服务的配置,包括后端服务地址、后端Path、后端超时时间、参数映射、常量参数、系统参数。用户请求到达 API 网关后,API 网关会根据您的后端配置,映射为对应的后端服务的请求形式,请求后端服务。

1)后端服务类型:目前支持 HTTP/HTTPS和MOCK两种类型。

2)后端服务地址:格式:“主机:端口”,主机为IP地址/域名,未指定端口时,HTTP协议默认使用80端口,HTTPS协议默认使用443端口。端口范围:1 ~ 65535。如果需要创建变量标识,则填写“#变量名#”,如#ipaddress#。

3)后端请求Path:Path 是您的 API 服务在您后端服务器上的实际请求路径,可以包含路径参数,以{路径参数}形式表示,比如/getUserInfo/{userId}。

如果请求路径中含有环境变量,则使用#变量名#的方式将环境变量定义到请求路径中,如/#path#。

4)后端认证:支持无认证和密钥认证。推荐使用密钥认证。

5)后端请求超时/读超时:指 API 请求到达 API 网关后,API 网关调用 API 后端服务的响应时间,即由 API 网关请求后端服务开始直至 API 网关收到后端返回结果的时长。单位为毫秒。设置值不能超过 30 秒。如果响应时间超过该值,API 网关会放弃请求后端服务,并给用户返回相应的错误信息。

6)mock返回结果:当为mock模式时,无1-5项,只需填写此项。Mock一般用于开发调试验证。在项目初始阶段,后端服务没有搭建好API联调环境,可以使用Mock模式,将预期结果固定返回给API调用方,方便调用方进行项目开发。

7)配置后端服务参数:可根据后端服务实际的参数名称和参数位置修改映射关系;包括参数名称和参数位置。

8)配置常量参数:您可以配置常量参数。您配置常量参数对您的用户不可见,但是 API 网关会在中转请求时,将这些参数加入到请求中的指定位置,再传递至后端服务,实现您的后端的一些业务需求。比如,您需要 API 网关每次向后端服务发送请求都带有一个关键词 ksygateway,您就可以把 ksygateway 配置为常量参数,并指定接收的位置。

9)配置系统参数:指 API 网关的系统参数。默认系统参数不会传递给您,但是如果您需要获取系统参数,您可以在 API 里配置接收位置和名称。具体内容如下表:

注:您需确保您录入的所有参数的参数名称全局唯一,包括 Path 中的动态参数、Headers 参数、Query 参数、Body 参数(非二进制)、常量参数、系统参数。如果您同时在 Headers 和 Query 里各有一个名为 name 的参数,将会导致错误。

定义返回结果

录入正确示例、失败返回结果示例、和错误码定义。

录入后单击完成,即完成API服务的创建。

后续操作

您创建完API后,可以通过调试API,验证服务是否正常。

金山云,开启您的云计算之旅

免费注册