通过APIG创建GRPC API
API网关支持创建GRPC API。gRPC是RPC(远程过程调用)的一种,只需定义每个API的Request和Response,剩下的gRPC框架就可以完成。它的典型特征就是使用protobuf(protocol buffers)作为其接口定义语言(Interface Definition Language,缩写IDL),同时底层的消息交换格式也是使用protobuf。下表列出了GRPC API与REST API的区别:
参数 |
GRPC |
REST |
---|---|---|
消息编码 |
protobuf |
JSON |
传输协议 |
HTTP/2 |
HTTP |
传输性能 |
传输内容少,速度快 |
传输内容多 |
传输形式 |
发送单个请求,接收单个响应。 |
当您的客户端和服务端都为GRPC类型时,可以通过创建GRPC类型的API来开放后端能力。GRPC适用于内部服务的调用,性能消耗低,传输率高,便于服务治理。
约束与限制
- 不支持API管理模块中的导入导出API功能、导入API设计文件、导入CSE微服务功能、导入CCE工作负载功能、调试API功能。
- 不支持后端降级策略中后端策略类型为Mock、HTTP&HTTPS、FunctionGraph的断路器策略。
- 不支持Base64编码配置。
- 不支持参数编排。
前提条件
创建GRPC API
- 进入API网关控制台页面。
- 根据实际业务在左侧导航栏上方选择实例。
- 在左侧导航栏选择“API管理 > API分组”。
- 单击分组名称,进入“分组信息”页面。
- 在“API运行”页面,单击“创建API > 创建GRPC API”。
- 根据下表参数信息,配置前端定义。
创建API时,当API所属分组、请求方法、请求路径、匹配模式都重复时,API无法创建成功。
表2 前端定义 参数
说明
API名称
API名称,根据规划自定义。建议您按照一定的命名规则填写API名称,方便您快速识别和查找。
支持中文、英文、数字、中划线、下划线、点、斜杠、中英文格式下的小括号和冒号、中文格式下的顿号,且只能以英文、汉字和数字开头,长度为3~255个字符。
所属分组
API所属的分组。选择已有的分组,如果需要新建分组,单击“新建分组”即可创建。
URL
前端地址由请求方法、请求协议、子域名和路径组成。
- 请求方法:默认为POST。
- 请求协议:默认为GRPCS.。
- 子域名:所在分组的调试域名。
- 路径:需要根据实际业务从以下三种配置方式中选择配置。
- /
- /{包名}.{服务名}
- /{包名}.{服务名}/{方法名}
网关响应
网关响应指未能成功处理API请求,从而产生的错误响应。
API网关提供默认的网关响应(default)。如果您需要自定义响应状态码或网关响应内容,可在API分组管理中新增网关响应,其中响应内容符合JSON格式即可。
匹配模式
选择API请求路径的匹配模式。
标签
标签主要用于对API添加分类属性,方便在创建了大量API后,快速过滤和查找。
支持英文,数字,中文,_-*#%.:,且只能以英文,中文开头,长度为1~128个字符。支持输入多个标签,不同标签以英文逗号分隔。
描述
API的描述,长度为1~1000个字符。
请求体内容描述
填写API请求中请求体的描述信息,用于帮助API调用者理解如何正确封装API请求。
- 根据下表参数信息,配置安全配置。
表3 安全配置 参数
说明
类型
API类型:
- 公开:选择“公开”类型时,API支持上架。
- 私有:选择“私有”类型时,当该API所在分组上架时,该API不会上架。
安全认证
API认证方式:
- APP认证:表示由API网关服务负责接口请求的安全认证。推荐使用APP认证方式。
- 华为IAM认证:表示借助IAM服务进行安全认证。
- 自定义认证:用户有自己的认证系统或服务(如使用OAuth认证),可选择“自定义认证”。
- 无认证:表示不需要认证。API网关对收到的调用请求不做身份认证,只需要按照API提供者提供的接口说明,封装规范的请求,发送给API网关即可。
API网关把请求内容透传给后端服务。因此,如果您希望在API后端服务进行鉴权,可以使用“无认证”方式,API调用方传递鉴权所需字段给后端服务,由后端服务进行鉴权。
各种认证方式下的API调用稍有不同,具体请参考调用APIG开放的API。
须知:- 认证方式为华为IAM认证时,任何API网关租户均可以访问此API,可能存在恶意刷流量,导致过量计费的风险。
- 认证方式为无认证时,任何公网用户均可以访问此API,可能存在恶意刷流量,导致过量计费的风险。
- 认证方式为自定义认证时,需要在函数服务中写一段函数,对接用户自己的认证系统或服务。如果当前Region没有上线函数工作流服务,则不支持自定义认证。
支持简易认证
仅当“安全认证”选择“APP认证”时可配置。
简易认证指APP认证方式下调用API时,在GRPC请求头部消息增加一个参数X-Apig-AppCode,而不需要对请求内容签名,API网关也仅校验AppCode,不校验请求签名,从而实现快速响应。
注意支持GRPCS方式调用,不支持GRPC方式。具体使用请参考配置APIG的API简易认证AppCode。
支持双重认证
仅当“安全认证”选择“APP认证”或“华为IAM认证”时可配置。
是否对API的调用进行双重安全认证。如果选择启用,则在使用APP认证或IAM认证对API请求进行安全认证时,同时使用自定义的函数API对API请求进行安全认证。
自定义认证
仅当“安全认证”选择“自定义认证”时需要配置。
选择已创建的前端类型自定义认证。若没有可用的自定义认证,可单击右侧的“新建自定义认证”,创建一个前端类型的自定义认证。
支持跨域CORS
是否开启跨域访问CORS(cross-origin resource sharing)。
CORS允许浏览器向跨域服务器,发出XMLHttpRequest请求,从而克服了AJAX只能同源使用的限制。
CORS请求分为两类:
- 简单请求:头信息之中,增加一个Origin字段。
- 非简单请求:在正式通信之前,增加一次GRPC查询请求。
开启CORS(非简单请求)时,您需要单独创建一个“请求方法”为“OPTIONS”的API,具体操作请参考开启跨域访问。
- 根据下表参数信息,配置前端定义。
- 单击“下一步”,配置后端服务。
- 定义默认后端。
添加策略后端前必须定义一个默认后端,当不满足任何一个策略后端的API请求,都将转发到默认的API后端。
在“后端配置”页面,选择API后端服务类型。
说明:
FunctionGraph依赖于函数工作流服务FunctionGraph,如果当前环境中未部署FunctionGraph服务,则后端服务类型FunctionGraph不可用。
GRPC API的后端FunctionGraph类型,当前仅贵阳一、上海一、北京四、上海二、圣地亚哥区域支持。
表4 GRPC&GRPCS类型定义后端服务 参数
说明
负载通道
是否使用负载通道访问后端服务。
URL
URL地址由请求方法、请求协议、负载通道/后端服务地址和路径组成。
- 请求方法
- 请求协议
- 负载通道
仅在使用负载通道时,需要设置。选择已创建的负载通道名称,或者新建负载通道。
负载通道中,云服务器的安全组必须允许100.125.0.0/16网段访问,否则将导致健康检查失败及业务不通。
- 后端服务地址
填写后端服务的访问地址,格式:“主机:端口”。主机为后端服务的访问IP地址/域名;端口为后端服务的端口。未指定端口时,GRPC协议默认使用80端口,GRPCS协议默认使用443端口。
如果后端服务地址中需要携带环境变量,则使用“#变量名#”的形式将环境变量添加到后端服务地址中,如#ipaddress#。支持添加多个环境变量,如#ipaddress##test#。
说明:
IP地址/域名可以是公网IP(支持云服务器的弹性IP地址、用户自己服务器的公网IP地址、ELB地址)/公网域名,前提需要开启实例的公网出口。可以是内网的IP,不可以是内网域名。
2022年10月30日后创建的实例支持APIG与后端服务tls握手阶段向后端服务传SNI。
- 路径
后端服务的路径,即服务的uri,可以包含路径参数,以{路径参数}形式表示,比如/getUserInfo/{userId}。
如果请求路径中含有环境变量,则使用#变量名#的方式将环境变量定义到请求路径中,如/#path#。支持创建多个环境变量,如/#path##request#。
说明:
- 在URL中配置了变量标识后,在API调试页面将无法调试。
- 如果在URL中设置变量,那么必须在待发布环境上配置变量名和变量值,否则变量无法赋值,API将无法正常调用。
- 变量名严格区分大小写。
自定义host头域
仅在使用负载通道时,可设置。
自定义后端服务请求中的Host头域,默认将使用请求中原始的host头域。
后端超时(ms)
后端服务请求的超时时间,可填写范围1ms~60000ms。
- 如果在API调试过程中,遇到后端响应超时之类的错误,请适当调大后端超时时间,以便排查原因。
- 如果当前的超时时间范围不能满足实际业务需求,请在实例配置参数中修改超时时间上限,可修改范围为1ms~600000ms。如果您修改了超时时间上限,需要同步修改此处的超时时间。
重试次数
后端服务请求失败后的重试次数,默认值为0,取值范围-1~10。
- 值为-1时,表示不开启重试功能,但除POST和PATCH外的其他请求类型会默认重试1次。
- 值为0~10时,表示开启重试功能,并根据设置的值执行重试。当值为0时,不重试。
使用负载通道时,重试次数应小于负载通道中已启用的后端服务器个数。
TLS双向认证
仅在协议为“GRPCS”时,可设置。
选择是否在API网关和后端服务间启用双向认证,如果选择“使用backend_client_certificate配置的证书做客户端认证”,您需在实例的配置参数中提前配backend_client_certificate证书。
后端认证
当您的后端服务需要对API调用增加自己的认证,则开启后端认证。
后端认证需要先添加一个自定义认证,自定义认证通过函数服务实现,在函数服务中编写一个函数,实现您的认证鉴权流程,或者使用函数调用您的统一鉴权服务。
说明:
后端认证依赖函数服务,此功能仅在部分区域开放。
表5 FunctionGraph类型定义后端服务 参数
说明
函数名
添加函数后,函数名自动生成。
函数URN
函数请求唯一标识。
单击“添加”,添加所需的函数URN。
版本或别名
调用类型
默认为Synchronous,同步调用。指后端函数服务收到调用请求后立即执行并返回调用结果,客户端发送请求后同步等待,收到后端响应后关闭连接。
后端超时(ms)
后端服务请求的超时时间,可填写范围1ms~60000ms。
- 如果在API调试过程中,遇到后端响应超时之类的错误,请适当调大后端超时时间,以便排查原因。
- 如果当前的超时时间范围不能满足实际业务需求,请在实例配置参数中修改超时时间上限,可修改范围为1ms~600000ms。如果您修改了超时时间上限,需要同步修改此处的超时时间。
后端认证
当您的后端服务需要对API调用增加自己的认证,则开启后端认证。
后端认证需要先添加一个自定义认证,自定义认证通过函数服务实现,在函数服务中编写一个函数,实现您的认证鉴权流程,或者使用函数调用您的统一鉴权服务。
说明:
后端认证依赖函数服务,此功能仅在部分区域开放。
- (可选)添加策略后端。
添加多个后端策略后,通过不同的策略条件,请求被转发到不同的后端服务中。
- 单击
添加策略后端。
- 后端策略增加的参数,具体如表6所示,其他参数说明参考表4、表5。
表6 后端策略参数 参数
说明
后端策略名称
您自定义的名称,用于识别不同的后端策略。
支持英文、数字、下划线和中划线,只能以英文字母开头,长度为3-64个字符。
生效方式
选择策略后端的生效方式。
- 满足任一条件:只要满足策略条件中的任意一项,此后端策略就可以生效。
- 满足全部条件:只有满足所有的策略条件,此后端策略才生效。
策略条件
添加后端策略生效的条件,具体如表7所示。
表7 策略条件 参数
说明
条件来源
策略条件中判断条件的来源。
- 源地址:以访问API的请求地址作为策略条件来源。
- 请求入参:以请求入参参数作为策略条件来源。
- Cookie:表示以API请求的Cookie信息作为判断条件。
- 系统参数:以网关内置参数作为策略条件来源。网关内置参数指API网关处理API请求时的系统运行时参数信息。
须知:- 选择“请求入参”作为策略条件时,入参需要在API前端请求中配置好,如在Header中添加一个参数。
- 如果未展示“系统参数”请联系技术支持升级实例。
参数名称
- 当“条件来源”为“请求入参”时,需要设置。选择已创建的入参参数名称。
- 当“条件来源”为“系统参数”时,需要选择参数名称。
- reqPath:请求URI,如“/a/b/c”。
- reqMethod:请求方法,如“GET”。
- 当“条件来源”为“COOKIE”时,需要填写Cookie中的参数名称。
参数位置
仅在“条件来源”为“请求入参”时,展示请求入参的参数位置。
条件类型
仅在“条件来源”为“请求入参”、“系统参数”、“COOKIE”时需要配置。
- 相等:请求参数值必须为输入值时,条件成立。
- 枚举:请求参数值只需要和枚举值中任何一个值相同,条件成立。
- 匹配:请求参数值只需要和正则表达式中任何一个值相同,条件成立。
说明:
当“条件来源”为“系统参数”并且“参数名称”为“reqMethod”时,“条件类型”仅支持选择相等或枚举。
条件值
填写判断条件的值,条件值的长度为1~1024个字符。
- “条件类型”为“相等”时,输入一个值。
- “条件类型”为“枚举”时,输入多个值,以英文逗号隔开。
- “条件类型”为“匹配”时,输入一个范围,例如:[0-5]。
- “条件来源”为“源地址”时,输入一个或多个IP地址,以英文逗号隔开。
- “条件来源”为“系统参数-前端认证参数”时,且当条件值填写boolean类型时,需全部小写。
- 单击
- 单击“完成”,进入“API运行”页面,可查看API详情。