全部产品

创建 API

更新时间:2020-09-18 15:56:28

创建API即录入API的定义,需要录入API的基本信息、服务信息、请求信息、和返回信息,然后对创建的API进行调试,及进行安全配置。经测试证明API可用后,可发布上线供用户使用。

1 定义 API

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

1.1 定义请求的基本信息

参数

描述

API分组

分组是API的管理单元,创建API之前您需要先创建分组,选择分组即选择Region。

API名称

所创建的API的名称。API名称标识需在所属分组内具有唯一性。

安全认证方式

目前支持阿里云APP、OpenID Connect、OpenID Connect&阿里云APP和无认证四种认证方式。

  • 阿里云APP:要求请求者调用该API时,需通过对APP的身份认证。

  • OpenID Connect:是一套基于OAuth 2.0协议的轻量级规范,提供通过RESTful APIs进行身份交互的框架。可以使用OpenID Connect和您的自有账号系统无缝对接。详细介绍请参见API 网关 OpenID Connect 使用指南

  • - OpenID Connect & 阿里云APP:同时进行OpenID Connect和阿里云APP认证。

  • 无认证:即任何人知晓该API的请求定义后,均可发起请求,网关不对其做身份验证,均会将请求转发至您的后端服务。(强烈不建议使用此模式。)

签名算法

参与签名的算法

  • HmacSHA256

  • HmacSHA1和HmacSHA256:表示同时支持这2种签名算法。

描述

填写API的相关描述。

1.2 定义API请求

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

参数

描述

请求类型

请求类型: 有4种类型可选。

普通请求:普通的HTTP(S)协议请求。

注册请求(双向通信):是双向通信的管理信令,是客户端发送给服务端,注册设备使用。

注销请求(双向通信):是双向通信的管理信令,是客户端发送给服务端,注销设备,注销成功后,将不再接受服务端推送的下行通知。

下行通知请求(双向通信):用户后端服务,在收到客户端发送的注册信令后,记住注册信令中的设备ID字段,然后就可以向API网关发送接收方为这个设备的下行通知信令了。只要这个设备在线,API网关就可以将此下行通知发送到端。

请求协议

支持HTTP、HTTPS、WEBSOCKET。

请求Path

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

HTTP Method

支持标准的HTTP Method,可选择PUT、GET、POST、DELETE、PATCH、HEAD、OPTIONS或ANY。

入参定义模式

可选入参映射(过滤未知参数)、入参映射(透传未知参数)和入参透传。

  • 入参映射(过滤未知参数):表示Query,Path 和 Body Form位置的参数需要配置前后端映射,网关只会透传给后端配置过的参数,其他参数会被过滤掉。

  • 入参映射(透传未知参数):表示Query,Path 和 Body Form位置的参数需要配置前后端映射,网关除配置的请求参数外,不对其他位置的请求参数进行映射与校验,用户参数会透明传递给后端。

  • 入参透传:表示不需要在入参定义处配置Query,Body Form参数(PATH参数仍需要配置)。客户端传给网关的参数都会被网关透传给后端

配置入参定义:定义您API的请求入参,即配置用户需要在什么位置传入什么参数。可选位置有Head、Query、Body、Path(Parameter Path),尤其当您在Path中配置了动态参数,那么在入参配置时需要对动态参数做配置说明。支持的参数类型有String、Integer、Boolean。

  • 需要注意所有参数的名称会校验是否唯一。

  • 您可以使用左侧的快捷键快速调整参数顺序。

  • 您可以使用操作图标下的移除选项,移除不需要的参数。

说明

如果您在Path中配置了动态参数,存在参数位置为Parameter Path的同名参数。

设置参数校验规则:您可以单击操作图标中的编辑更多配置校验规则。如String的长度,Number的枚举等等。网关会参照校验规则对请求做初步校验,如果入参不合法,则不会到达您的后端服务,大大的降低了后端服务的压力。

1.3 定义后端服务信息

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

后端基础定义

参数

描述

后端服务类型

目前支持HTTP/HTTPS、函数计算、VPC、Mock四种类型。

  • HTTP(s): 默认类型,后端是HTTP或者HTTPS协议的服务接入,当网关和后端服务网络能直接连通时使用。若是HTTPS服务,后端服务必须有SSL证书。

  • 函数计算:若选择函数计算为后端服务,需先在函数计算控制台中创建函数,并需填入函数服务名称和函数名称,和获取函数计算角色Arn。

  • VPC: 当后端服务在某个VPC内时使用。

  • Mock: 用于模拟最初预定的返回结果HTTP/HTTPS:若您的服务为HTTP/HTTPS服务,则选择此项。

VPC授权名称

当您的后端服务在VPC中时,需要填写创建VPC授权时设置的VPC授权名称。

后端服务地址

后端服务的Host,可以是一个域名,也可以是http(s)://host:port的形式。填写时,必须包含http://或https://。

后端请求Path

Path是您的API服务在您后端服务器上的实际请求路径。若您后端Path需要接收动态参数,则需要声明调用者需传入参数的具体位置和参数名,即声明映射关系。

HTTP Method

支持标准的HTTP Method,可选择PUT、GET、POST、DELETE、PATCH、HEAD、OPTIONS或ANY。

后端超时

指API请求到达网关后,网关去调API后端服务的响应时间。由网关请求后端开始到网关收到后端返回结果。该值不能超过30秒。超过该值网关会放弃请求后端服务,并给用户返回相应的错误信息。

配置后端服务参数: 网关支持参数在前端、后端的全映射,包括名称映射和位置映射。位置映射包括Path、Header、Query、Body的混排映射。也就是说,您可以将您的后端服务通过映射完成包装成更规范、更专业的API形态。这部分就是在声明前后端API映射关系的。

配置常量参数:您可以配置常量参数。您配置的常量参数对您的用户不可见,但是API网关会在中转请求时,将这些参数加入到请求中的指定位置,再传递至后端服务,实现您的后端的一些业务需求。比如您需要网关每次请求您后端时都带有参数abc,您可以直接将abc配置为常量参数。请求达到网关后,网关会自动在指定位置加上该参数再去请求您的后端。

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

参数名称

参数含义

CaClientIp

发送请求的客户端IP(若您配置了WAF、CDN等,则记录的是回源IP,真实IP需要在X-Forwarded-For中查看)

CaDomain

发送请求的域名

CaRequestHandleTime

请求时间(格林威治时间)

CaAppId

请求的APP的ID

CaRequestId

RequestId

CaApiName

API名称

CaHttpSchema

用户调用API使用的协议,http或者https

CaProxy

代理(AliCloudApiGateway)

CaClientUa

请求客户端的User-Agent

CaCloudMarketInstanceld

请求的云市场商品的实例ID

CaAppKey

请求的APP的KEY

CaStage

请求的环境(RELEASE、TEST、PRE)

目前共享实例可以在分组详情中设置透传HOST头(域名头),专享实例若有需求可提交工单开启此功能,开启后API网关会将请求域名透传至后端,若没有开启,后端收到的是用户在API网关填写的后端HOST。示例如下:

示例中API分组绑定的请求HOST为xuemeng.XXXX.com,API后端HOST为apigatewayXXXXXXalicloudapi.com:8080,配置前后如下

透传HOST头(域名头)开启时:

开启host透传

透传HOST头(域名头)未开启时:

透传host未开

说明

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

1.4 定义返回结果

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

2 API 调试

API定义录入完成后,您可以在API调试页面调试API,以确定API的可用性。

API创建、定义完成后,页面自动跳转到API列表页。您可以通过此页面按钮,测试创建的API是否可用,请求链路是否正确。

  1. 单击API名称或管理按钮,进入API定义页面。

  2. 单击左侧导航栏中调试API

  3. 输入请求参数,单击发送请求

返回结果将显示在右侧页面。

如果调试返回成功结果,则说明该API可以使用。

如果返回代码为4XX或5XX,则表示存在错误。请参见如何获取错误信息错误代码表

3 后续步骤

完成以上定义后和初步调试后,您就完成了API的创建。您可以发布API到测试、预发、线上环境,继续调试或供用户使用。还可以为API绑定客户端签名说明文档等安全配置。