创建API
API提供者把API接口配置在API网关中,开放后端能力。创建API分以下步骤:
- 前端配置
支持配置前端定义、安全配置和请求参数。
- 后端配置
支持配置默认后端、策略后端和返回结果。
- (可选)为API添加策略
支持配置传统策略和插件策略。
API网关服务基于REST的API架构,API的开放和调用需要遵循RESTful相关规范。
前端配置
- 进入API网关控制台页面。
- 根据实际业务在左侧导航栏上方选择实例。
- 在左侧导航栏选择“API管理 > API分组”。
- 单击分组名称。
- 在“API运行”页面,单击“创建API > 创建API”。
- 根据下表参数信息,配置前端定义。
创建API时,当API所属分组、请求方法、请求路径、匹配模式都重复时,API无法创建成功。
表1 前端定义 参数
说明
API名称
API名称,根据规划自定义。建议您按照一定的命名规则填写API名称,方便您快速识别和查找。
所属分组
API所属的分组。
URL
前端地址由请求方法、请求协议、子域名和路径组成。
网关响应
网关响应指未能成功处理API请求,从而产生的错误响应。
API网关提供默认的网关响应(default)。如果您需要自定义响应状态码或网关响应内容,可在API分组管理中新增网关响应,其中响应内容符合JSON格式即可。
匹配模式
选择API请求路径的匹配模式。
标签
标签主要用于对API添加分类属性,方便在创建了大量API后,快速过滤和查找。
描述
API的描述。
内容格式类型
是否开启API请求的内容格式类型,开启后APIG会按照选择的内容格式类型向后端传输API请求。支持选择“application/json”、“application/xml”、“text/plain”和“multipart/form-data”。选择内容格式类型前,请确保后端服务支持待选择的内容格式类型。
请求体内容描述
填写API请求中请求体的描述信息,用于帮助API调用者理解如何正确封装API请求。
请求体Base64编码
对与FunctionGraph交互场景的Body体进行Base64编码,默认开启。仅当满足以下任意条件时,Base64编码才生效:
- 自定义认证
- 后端配置为FunctionGraph类型
- 绑定断路器策略,且断路器后端降级策略FunctionGraph类型
如需关闭Base64编码,仅当内容格式类型为“application/json”时才可关闭。
- 根据下表参数信息,配置安全配置。
表2 安全配置 参数
说明
类型
API类型:
- 公开:选择“公开”类型时,API支持上架。
- 私有:选择“私有”类型时,当该API所在分组上架时,该API不会上架。
安全认证
API认证方式:
- APP认证:表示由API网关服务负责接口请求的安全认证。推荐使用APP认证方式。
- 华为IAM认证:表示借助IAM服务进行安全认证。
- 自定义认证:用户有自己的认证系统或服务(如使用OAuth认证),可选择“自定义认证”。
- 无认证:表示不需要认证。
各种认证方式下的API调用稍有不同,具体请参考调用API。
须知:- 认证方式为华为IAM认证时,任何API网关租户均可以访问此API,可能存在恶意刷流量,导致过量计费的风险。
- 认证方式为无认证时,任何公网用户均可以访问此API,可能存在恶意刷流量,导致过量计费的风险。
- 认证方式为自定义认证时,需要在函数服务中写一段函数,对接用户自己的认证系统或服务。如果当前Region没有上线函数工作流服务,则不支持自定义认证。
支持简易认证
仅当“安全认证”选择“APP认证”时可配置。
简易认证指APP认证方式下调用API时,在HTTP请求头部消息增加一个参数X-Apig-AppCode,而不需要对请求内容签名,API网关也仅校验AppCode,不校验请求签名,从而实现快速响应。
注意支持HTTPS或GRPCS方式调用,不支持HTTP方式。具体使用请参考为简易认证绑定AppCode。
说明:如果首次创建API未开启简易认证,那么之后开启简易认证,需要重新发布API。请参考发布API发布。
支持双重认证
仅当“安全认证”选择“APP认证”或“华为IAM认证”时可配置。
是否对API的调用进行双重安全认证。如果选择启用,则在使用APP认证或IAM认证对API请求进行安全认证时,同时使用自定义的函数API对API请求进行安全认证。
自定义认证
仅当“安全认证”选择“自定义认证”时需要配置。
自定义认证需要提前创建,可单击右侧的“新建自定义认证”链接创建。
支持跨域CORS
是否开启跨域访问CORS(cross-origin resource sharing)。
CORS允许浏览器向跨域服务器,发出XMLHttpRequest请求,从而克服了AJAX只能同源使用的限制。
CORS请求分为两类:
- 简单请求:头信息之中,增加一个Origin字段。
- 非简单请求:在正式通信之前,增加一次HTTP查询请求。
开启CORS(非简单请求)时,您需要单独创建一个“请求方法”为“OPTIONS”的API,具体操作请参考开启跨域访问。
- (可选)根据实际需要定义API的请求参数,请求参数定义见下表。
建议不要设置敏感信息,防止泄露。
表3 请求参数 参数
说明
参数名
参数的名称,如果参数在“Path”位置,参数名称会同步“路径”中的名称。
- 参数名不能以x-apig- 、x-sdk-开头,不能是x-stage,不区分大小写。
- 参数位置为HEADER时,参数名不能是“Authorization”和“X-Auth-Token”,不区分大小写,也不支持下划线。
参数类型
字段的类型,包含STRING和NUMBER。入参如果为boolean,请选择STRING。
必填
请求API时,此参数是否为必填。如果选择“是”,API网关将校验请求中是否包含此参数,如果不包含,则拒绝该请求。
透传
请求参数是否透传到后端服务。
枚举
请求参数的枚举值,请求参数的值只能从枚举值中选择,多个枚举值间用英文逗号隔开。
默认值
“必填”为“否”时,默认值生效。请求中不包含此参数时,API网关自动增加默认值发送给后端服务。
编排规则
选择编排规则。创建编排规则请参考编排规则管理。
字节限制
- 最大长度/最大值:“类型”为“STRING”时,设置参数值的最大字符串长度,“类型”为“NUMBER”时,设置参数值的最大值。
- 最小长度/最小值:“类型”为“STRING”时,设置参数值的最小字符串长度,“类型”为“NUMBER”时,设置参数值的最小值。
示例
参数值的填写示例。
描述
对于此参数的描述。
- 根据下表参数信息,配置前端定义。
- 单击“下一步”,进入后端配置。
后端配置
支持定义多个策略后端,即满足一定条件后转发给指定的API后端服务,用以满足不同的调用场景。例如为了区分普通调用与特殊调用,可以定义一个“策略后端”,通过调用方的源IP地址,为特殊调用方分配专用的后端服务。
除了定义一个默认的API后端服务,一个API共可以定义5个策略后端。
- 定义默认后端。
添加策略后端前必须定义一个默认后端,当不满足任何一个策略后端的API请求,都将转发到默认的API后端。
在“后端配置”页面,选择API后端服务类型。
后端服务类型有HTTP&HTTPS、FunctionGraph和Mock,具体参数描述见表4、表5、表6。
- FunctionGraph依赖于函数工作流服务FunctionGraph,如果当前环境中未部署FunctionGraph服务,则后端服务类型FunctionGraph不可用。
- 在后端服务还不具备的场景下,可以使用Mock模式,将预期结果固定返回给API调用方,方便调用方进行调试验证。
表4 HTTP&HTTPS类型定义后端服务 参数
说明
负载通道
是否使用负载通道访问后端服务。如果选择“使用”,您需要提前创建负载通道。
URL
URL地址由请求方法、请求协议、负载通道/后端服务地址和路径组成。
- 请求方法
GET、POST、DELETE、PUT、PATCH、HEAD、OPTIONS、ANY,其中ANY表示该API支持任意请求方法。
- 请求协议
HTTP或HTTPS,传输重要或敏感数据时推荐使用HTTPS。
说明:- API网关支持WebSocket数据传输,请求协议中的HTTP相当于WebSocket的ws,HTTPS相当于WebSocket的wss。
- 定义的后端服务协议须与用户的后端业务协议保持一致。
- 负载通道(可选)
说明:
负载通道中,云服务器的安全组必须允许100.125.0.0/16网段访问,否则将导致健康检查失败及业务不通。
- 后端服务地址(可选)
填写后端服务的访问地址,格式:“主机:端口”。主机为后端服务的访问IP地址/域名;端口为后端服务的端口。未指定端口时,HTTP协议默认使用80端口,HTTPS协议默认使用443端口。
如果后端服务地址中需要携带环境变量,则使用“#变量名#”的形式将环境变量添加到后端服务地址中,如#ipaddress#。支持添加多个环境变量,如#ipaddress##test#。
说明:2022年10月30日后创建的实例支持APIG与后端服务tls握手阶段向后端服务传SNI。
- 路径
后端服务的路径,即服务的uri,可以包含路径参数,以{路径参数}形式表示,比如/getUserInfo/{userId}。
如果请求路径中含有环境变量,则使用#变量名#的方式将环境变量定义到请求路径中,如/#path#。支持创建多个环境变量,如/#path##request#。
自定义host头域
仅在使用负载通道时,可设置。
在请求被发送到负载通道中主机前,允许您自定义请求的host头域,默认将使用请求中原始的host头域。
后端超时(ms)
后端服务请求的超时时间,可填写范围1ms~60000ms。
如果在API调试过程中,遇到后端响应超时之类的错误,请适当调大后端超时时间,以便排查原因。
说明:如果当前的超时时间范围不能满足实际业务需求,请在实例配置参数中修改超时时间上限,可修改范围为1ms~600000ms。如果您修改了超时时间上限,需要同步修改此处的超时时间。
重试次数
后端服务请求失败后的重试次数,默认值为0,取值范围-1~10。
- 值为-1时,表示不开启重试功能,但除POST和PATCH外的其他请求类型会默认重试1次。
- 值为0-10时,表示开启重试功能,并根据设置的值执行重试。当值为0时,不重试。
使用负载通道时,重试次数应小于负载通道中已启用的后端服务器个数。
TLS双向认证
仅在协议为“HTTPS”时,可设置。
选择是否在API网关和后端服务间启用双向认证,如果选择“使用backend_client_certificate配置的证书做客户端认证”,您需在实例的“配置参数”中提前配backend_client_certificate证书。
后端认证
当您的后端服务需要对API调用增加自己的认证,则开启后端认证。
后端认证需要先添加一个自定义认证,自定义认证通过函数服务实现,在函数服务中编写一个函数,实现您的认证鉴权流程,或者使用函数调用您的统一鉴权服务。
说明:后端认证依赖函数服务,此功能仅在部分区域开放。
表5 FunctionGraph类型定义后端服务 参数
说明
函数名
添加函数后,函数名自动生成。
函数URN
函数请求唯一标识。
单击“添加”,添加所需的函数URN。
版本或别名
调用类型
- Synchronous:同步调用。指后端函数服务收到调用请求后立即执行并返回调用结果,客户端发送请求后同步等待,收到后端响应后关闭连接。
- Asynchronous:异步调用。客户端不关注请求调用的结果,服务端收到请求后将请求排队,排队成功后请求就返回,服务端在空闲的情况下会逐个处理排队的请求。
后端超时(ms)
API网关请求后端服务的超时时间,请参考表4后端超时。
后端认证
请参考表4后端认证。
表6 Mock类型定义后端服务 参数
说明
Mock自定义返回码
选择API响应的HTTP状态码。
Mock返回结果
Mock一般用于开发调试验证。在项目初始阶段,后端服务没有搭建好API联调环境,可以使用Mock模式,将预期结果固定返回给API调用方,方便调用方进行项目开发。
后端认证
参考表4后端认证。
添加header参数
自定义API响应的header参数。
单击“添加header参数”,并填写参数名、参数值和参数描述。
- 在URL中配置了变量标识后,在API调试页面将无法调试。
- 如果在URL中设置变量,那么必须在待发布环境上配置变量名和变量值,否则变量无法赋值,API将无法正常调用。
- 变量名严格区分大小写。
- (可选)配置默认后端的后端服务参数,将调用API时传入的请求参数映射到后端服务请求的对应位置。如果5.c中未定义请求参数,可直接跳过此步骤。
- 在“后端服务参数”下,可通过以下任意一种方法添加后端服务参数。
- 单击“导入入参定义”,把所有已定义的API请求参数添加到后端服务参数。
- 单击“添加后端参数映射”,按需逐个添加后端服务参数。
- 根据后端服务实际的参数名称和参数位置修改映射关系,如图1所示。
- 后端参数在“PATH”位置,那么参数名称需要和“路径”中的名称相同。
- 调用API的请求参数名称、位置可以与后端参数名称、位置不同。
- 参数名不能是x-apig- 、x-sdk-开头,不区分大小写。
- 参数名不能是x-stage,不区分大小写。
- 参数位置为HEADER时,参数名不区分大小写,也不支持下划线开头。
- 如上图,test01和test03在调用API时分别配置于PATH和QUERY位置,后端服务通过映射,将在HEADER位置接收test01和test03的值。test02在调用API时配置于HEADER位置,后端服务通过映射,将在PATH位置以参数名test05来接收test02的值。
假设test01为aaa,test02为bbb,test03为ccc。
API调用请求:
curl -ik -H 'test02:bbb' -X GET https://example.com/v1.0/aaa?test03=ccc
后端服务请求:
curl -ik -H 'test01:aaa' -H 'test03:ccc' -X GET https://example.com/v1.0/bbb
- 在“后端服务参数”下,可通过以下任意一种方法添加后端服务参数。
- (可选)配置默认后端的常量参数。如果后端服务需要接收固定的常量信息,可以通过设置常量参数来实现。API网关向后端服务发送请求时,将常量参数添加到请求的指定位置,然后将请求发送给后端服务。
在“常量参数”下,单击“添加常量参数”,添加后端服务请求的常量参数。
常量参数会明文展示,为防止信息泄露,请谨慎配置。
表7 常量参数配置 参数
说明
常量参数名
填写常量参数的名称。“参数位置”为“PATH”时,参数名需要与“路径”中的参数名称一致。
说明:- 参数名不能以x-apig- 、x-sdk-开头,不能是x-stage,不区分大小写。
- 参数位置为HEADER时,参数名不支持下划线开头,不区分大小写。
参数位置
选择常量参数在后端服务请求中的位置,可选择“PATH”、“HEADER”和“QUERY”。
参数值
填写常量参数的值。
描述
填写常量参数的描述信息。
- API网关将包含常量参数的请求发送给后端服务前,会对特殊参数值进行百分号编码,请确保后端服务支持百分号编码。例如,参数值[api],在百分号编码后变为%5Bapi%5D。
- 对于PATH位置的参数值,API网关会对如下字符进行百分号编码:ASCII码为0到31的字符、?、>、<、/、%、#、"、[、\、]、^、`、{、|、}、空白符、ASCII码为127到255的字符。
- 对于QUERY位置的参数值,API网关会对如下字符进行百分号编码:ASCII码为0到31的字符、>、=、<、+、&、%、#、"、[、\、]、^、`、{、|、}、空白符、ASCII码为127到255的字符。
- (可选)配置默认后端的系统参数。如果后端服务需要接收系统运行时产生的参数信息,如网关内置参数、前端认证参数和后端认证参数等,可以通过设置系统参数来实现。API网关向后端服务发送请求时,将系统参数添加到请求的指定位置,然后将请求发送给后端服务。
- 在“系统参数”下,单击“添加系统参数”,添加后端服务请求的系统参数。
表8 系统参数配置 参数
说明
系统参数类型
选择系统参数的类型。
系统参数名
填写系统参数的名称。
- “系统参数类型”为“网关内置参数”时,支持选择如下参数:
- sourceIp:API调用者的源地址。
- stage:API调用的部署环境。
- apiId:API的ID。
- appId:API调用者的APP ID。
- requestId:当次调用API所生成的请求ID。
- serverAddr:网关服务器的地址 。
- serverName:网关服务器的名称。
- handleTime:本次调用API的处理时间。
- providerAppId:API提供者的凭据ID。
- apiName:API的名称,需要发布API后才可使用此参数。
- appName:调用API所使用的凭据名称。
- clientCertCN:开启客户端认证时,API请求携带的客户端证书中的CN(Common Name)字段。
- 系统参数类型为“前端认证参数”或“后端认证参数”时,支持自定义参数,但是此参数必须为自定义认证返回结果中的参数。
自定义认证函数的编写以及返回结果参数的获取方法,请参考《开发指南》。
后端参数名称
填写系统参数需要映射的后端参数名称。
说明:- 参数名不能以x-apig- 、x-sdk-开头,不能是x-stage,不区分大小写。
- 参数位置为HEADER时,参数名不支持下划线开头,不区分大小写。
后端参数位置
选择后端参数在后端服务请求中的位置,可选择“PATH”、“HEADER”和“QUERY”。
描述
填写系统参数的描述信息。
- “系统参数类型”为“网关内置参数”时,支持选择如下参数:
- 在“系统参数”下,单击“添加系统参数”,添加后端服务请求的系统参数。
- (可选)添加策略后端。
添加多个后端策略后,通过不同的策略条件,请求被转发到不同的后端服务中。
- 单击添加策略后端。
- 后端策略增加的参数,具体如表9所示,其他参数说明参考表4、表5和表6。
表9 后端策略参数 参数
说明
后端策略名称
您自定义的名称,用于识别不同的后端策略。
生效方式
- 满足任一条件:只要满足策略条件中的任意一项,此后端策略就可以生效。
- 满足全部条件:只有满足所有的策略条件,此后端策略才生效。
策略条件
使后端策略生效的条件,具体如表10所示。
表10 策略条件 参数
说明
条件来源
- 源地址:以访问API的请求地址作为策略条件来源。
- 请求入参:以请求入参参数作为策略条件来源。
- Cookie:表示以API请求的Cookie信息作为判断条件。
- 系统参数-网关内置参数:以网关内置参数作为策略条件来源。网关内置参数指API网关处理API请求时的系统运行时参数信息。
- 系统参数-前端认证参数:前端自定义认证返回结果中的参数。在前端配置中,“安全认证”选择“自定义认证”或使用双重认证时,才可以选择此参数。
须知:- 选择“请求入参”作为策略条件时,入参需要在API前端请求中配置好,如在Header中添加一个参数。
- 如果未展示“系统参数”请联系技术支持升级实例。
参数名称
- 当“条件来源”为“请求入参”时,需要设置。选择已创建的入参参数名称。
- 当“条件来源”为“系统参数”时,需要选择参数名称。
- reqPath:请求URI,如“/a/b/c”。
- reqMethod:请求方法,如“GET”。
- 当“条件来源”为“COOKIE”时,需要填写Cookie中的参数名称。
参数位置
仅在“条件来源”为“请求入参”时,展示请求入参的参数位置。
条件类型
仅在“条件来源”为“请求入参”、“系统参数”、“COOKIE”时需要配置。
- 相等:请求参数值必须为输入值时,条件成立。
- 枚举:请求参数值只需要和枚举值中任何一个值相同,条件成立。
- 匹配:请求参数值只需要和正则表达式中任何一个值相同,条件成立。
说明:当“条件来源”为“系统参数”并且“参数名称”为“reqMethod”时,“条件类型”仅支持选择相等或枚举。
条件值
- “条件类型”为“相等”时,输入一个值。
- “条件类型”为“枚举”时,输入多个值,以英文逗号隔开。
- “条件类型”为“匹配”时,输入一个范围,例如:[0-5]。
- “条件来源”为“源地址”时,输入一个或多个IP地址,以英文逗号隔开。
- “条件来源”为“系统参数-前端认证参数”时,且当条件值填写boolean类型时,需全部小写。
- 定义返回结果。
在“返回结果基础定义”区域,填写返回信息。
表11 定义返回结果 参数
说明
成功响应示例
成功调用API时,返回的响应信息示例。
失败响应示例
调用API失败时,返回的响应信息示例。
- 单击“完成”,进入“API运行”页面,可查看API详情。
(可选)为API添加策略
发布API后,方可添加策略。
- 在“API运行”页面,单击“添加策略”。
- 选择策略类型,配置策略。
- 选择已有策略:单击“选择已有策略”后,选择策略。
- 创建新策略:请参考创建策略并绑定API。
- 单击“确定”,完成策略的创建。
后续操作
API创建完成后,通过调试API,验证服务是否正常。