如何通过录入API的定义来创建API - API 网关

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

1 定义 API

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

1.1 定义请求的基本信息

参数	描述
API分组	分组是API的管理单元，创建API之前您需要先创建分组，选择分组即选择Region。
API名称	所创建的API的名称。API名称标识需在所属分组内具有唯一性。
安全认证方式	目前支持阿里云APP、和无认证。阿里云APP：要求请求者调用该API时，需通过对APP的身份认证。无认证：即任何人知晓该API的请求定义后，均可发起请求，网关不对其做身份验证，均会将请求转发至您的后端服务。（强烈不建议使用此模式。）
签名算法	参与签名的算法 HMAC_SHA256 HMAC_SHA1和HMAC_SHA256：表示同时支持这2种签名算法。
描述	填写API的相关描述。

1.2 定义API请求

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

参数	描述
请求协议	支持HTTP、HTTPS。
请求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、OSS、Mock五种类型。 HTTP(s): 默认类型，后端是HTTP或者HTTPS协议的服务接入，当网关和后端服务网络能直接连通时使用。若是HTTPS服务，后端服务必须有SSL证书。函数计算：若选择函数计算为后端服务，需先在函数计算控制台中创建函数，并需填入函数服务名称和函数名称，和获取函数计算角色Arn。 VPC: 当后端服务在某个VPC内时使用。 OSS：当后端是OSS时使用。 Mock: 用于模拟最初预定的返回结果HTTP/HTTPS：若您的服务为HTTP/HTTPS服务，则选择此项。说明海外region及中国香港不支持新建HTTP/OSS类型后端服务。
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	请求时间（格林威治时间）
CaRequestId	RequestId
CaApiName	API名称
CaHttpSchema	用户调用API使用的协议，http或者https
CaProxy	代理（AliCloudApiGateway）
CaClientUa	请求客户端的User-Agent
CaCloudMarketInstanceId	云市场商品首次购买的实例ID
CaAppId	请求的APP的ID
CaAppKey	请求的APP的KEY
CaAppExtendInfo	请求的APP的拓展字段
CaStage	请求的环境（RELEASE、TEST、PRE）
CaInstanceId	API所属的实例ID
CaSourceVpcId	客户端IP所属的Vpc

可以在分组详情中设置透传HOST头（域名头），开启后API网关会将请求域名透传至后端，若没有开启，后端收到的是用户在API网关填写的后端HOST。示例如下：

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

透传HOST头（域名头）开启时：

Host: xuemeng.XXXX.com

透传HOST头（域名头）未开启时：

Host: apigatewayXXXXXXalicloudapi.com:8080

说明

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

1.4 定义返回结果

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

2 API 调试

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

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

单击API名称或管理按钮，进入API定义页面。
单击左侧导航栏中调试API。
输入请求参数，单击发送请求。

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

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

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

3 后续步骤

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