# 通过APIG创建GRPC API API网关支持创建GRPC API。gRPC是RPC（远程过程调用）的一种，只需定义每个API的Request和Response，剩下的gRPC框架就可以完成。它的典型特征就是使用protobuf（protocol buffers）作为其接口定义语言（Interface Definition Language，缩写IDL），同时底层的消息交换格式也是使用protobuf。下表列出了GRPC API与REST API的区别： 表1GRPC 和 REST区别 | 参数 | GRPC | REST | |:---|:---|:---| | 消息编码 | protobuf | JSON | | 传输协议 | HTTP/2 | HTTP | | 传输性能 | 传输内容少，速度快 | 传输内容多 | | 传输形式 | - 简单RPC（Unary RPC） 发送单个请求，接收单个响应。 - 服务端流式RPC （Server streaming RPC） 发送单个请求，接收多个响应。 - 客户端流式RPC （Client streaming RPC） 发送多个请求，接收单个响应。 - 双向流式RPC（Bi-directional streaming RPC） 发送多个请求，接收多个响应。 | 发送单个请求，接收单个响应。 | 当您的客户端和服务端都为GRPC类型时，可以通过创建GRPC类型的API来开放后端能力。GRPC适用于内部服务的调用，性能消耗低，传输率高，便于服务治理。 #### 约束与限制 - 不支持API管理模块中的导入导出API功能、导入API设计文件、导入CSE微服务功能、导入CCE工作负载功能、调试API功能。 - 不支持后端降级策略中后端策略类型为Mock、HTTP\&HTTPS、FunctionGraph的断路器策略。 - 不支持Base64编码配置。 - 不支持参数编排。 - 多模后端模式受限使用，如需使用，请[提交工单](https://support.huaweicloud.com/usermanual-ticket/zh-cn_topic_0127038618.html)开通。 - 多模后端模式仅在后端服务类型为GRPC\&GRPCS时可以选择。 #### 前提条件 - 已创建API分组。如果未创建API分组，请[创建API分组](https://support.huaweicloud.com/usermanual-apig/apig_03_0005.html)。 - 如果后端服务需要使用负载通道，请[创建负载通道](https://support.huaweicloud.com/usermanual-apig/apig_03_0040.html)。 - 后端服务已定义proto文件，即在proto文件中定义API的Request和Response。proto文件是用于定义数据结构和服务接口的文件，通常在gRPC中使用。它基于Protobuf语言，用于描述数据的结构和交互方式，充当客户端和后端服务之间通信的合同。 #### 创建GRPC API 1. 进入[API网关控制台](https://console.huaweicloud.com/apig2/#/overview)页面。 2. 根据实际业务在左侧导航栏上方选择实例。 3. 在左侧导航栏选择"API管理 \> API分组"。 4. 单击分组名称，进入"分组信息"页面。 5. 在"API运行"页面，单击"创建API \> 创建GRPC API"。 1. 根据下表参数信息，配置前端定义。 **创建API时，当API所属分组、请求方法、请求路径、匹配模式都重复时，API无法创建成功。** 表2前端定义 | 参数 | 说明 | |:---|:---| | API名称 | API名称，根据规划自定义。建议您按照一定的命名规则填写API名称，方便您快速识别和查找。 支持中文、英文、数字、中划线、下划线、点、斜杠、中英文格式下的小括号和冒号、中文格式下的顿号，且只能以英文、中文和数字开头，长度为3\~255个字符。 | | 所属分组 | API所属的分组。选择已有的分组，如果需要新建分组，单击"[新建分组](https://support.huaweicloud.com/usermanual-apig/apig_03_0005.html)"即可创建。 | | URL | 前端地址由请求方法、请求协议、子域名和路径组成。 - **请求方法**：默认为POST。 - **请求协议**：默认为GRPCS。 - **子域名**：所在分组的调试域名。 - **路径** ：需要根据实际业务从以下三种配置方式中选择配置。 - / - /{包名}.{服务名} - /{包名}.{服务名}/{方法名} 说明： - 包名、服务名、方法名从[proto文件]中获取。 - 当前端路径设置"/{包名}.{服务名}/{方法名}"时，API的匹配模式才可以使用"绝对匹配"。 | | 网关响应 | 网关响应指未能成功处理API请求，从而产生的错误响应。 API网关提供默认的网关响应（default）。如果您需要自定义响应状态码或网关响应内容，可在API分组管理中[新增网关响应](https://support.huaweicloud.com/usermanual-apig/apig_03_0008.html)，其中响应内容符合JSON格式即可。 | | 匹配模式 | 选择API请求路径的匹配模式。 - **绝对匹配**：API请求中的请求路径要与"路径"的配置一致。 - **前缀匹配** ：API请求中的请求路径要以"路径"的配置为前缀。前缀匹配支持接口定义多个不同Path。 例如，"路径"为/test/AA，使用前缀匹配时，通过/test/AA/BB和/test/AA/CC都可以访问API，但是通过/test/AACC无法访问。 说明： - 使用前缀匹配时，匹配剩余的路径将透传到后端。 例如，使用前缀匹配，前端请求路径定义为/test/，后端请求路径定义为/test2/，通过/test/AA/CC访问API，则后端收到的请求url为/test2/AA/CC。 - 使用前缀匹配时，以最长路径优先规则匹配。 例如，两个API都开启前缀匹配，"路径"为/test/AA和/test/AA/BB，请求/test/AA/BB/c会匹配路径为/test/AA/BB的API。 - 当两个API的所属分组、请求方法、请求路径都相同时，优先调用匹配模式为绝对匹配的API。 | | 标签 | 标签主要用于对API添加分类属性，方便在创建了大量API后，快速过滤和查找。 支持英文，数字，中文，_-\*#%.:，且只能以英文，中文开头，长度为1\~128个字符。支持输入多个标签，不同标签以英文逗号分隔。 | | 描述 | API的描述，长度为1\~1000个字符。 | | 请求体内容描述 | 填写API请求中请求体的描述信息，用于帮助API调用者理解如何正确封装API请求。 | 2. 根据下表参数信息，配置安全配置。 表3安全配置 | 参数 | 说明 | |:---|:---| | 类型 | API类型： - 公开：选择"公开"类型时，API支持上架。 - 私有：选择"私有"类型时，当该API所在分组上架时，该API不会上架。 | | 安全认证 | API认证方式： - **APP认证**：表示由API网关服务负责接口请求的安全认证。推荐使用APP认证方式。 - **华为** **IAM认证**：表示借助IAM服务进行安全认证。 - **自定义认证**：用户有自己的认证系统或服务（如使用OAuth认证），可选择"自定义认证"。 - **无认证** ：表示不需要认证。API网关对收到的调用请求不做身份认证，只需要按照API提供者提供的接口说明，封装规范的请求，发送给API网关即可。 API网关把请求内容**透传**给后端服务。因此，如果您希望在API后端服务进行鉴权，可以使用"无认证"方式，API调用方传递鉴权所需字段给后端服务，由后端服务进行鉴权。 各种认证方式下的API调用稍有不同，具体请参考[调用APIG开放的API](https://support.huaweicloud.com/usermanual-apig/apig_03_0046.html)章节。 注意： - 认证方式为华为IAM认证时，任何API网关租户均可以访问此API，可能存在恶意刷流量，导致过量计费的风险。 - 认证方式为无认证时，任何公网用户均可以访问此API，可能存在恶意刷流量，导致过量计费的风险。 - 认证方式为自定义认证时，需要在函数服务中写一段函数，对接用户自己的认证系统或服务。如果当前Region没有上线**函数工作流服务**，则不支持自定义认证。 | | 支持简易认证 | **仅当"安全认证"选择"APP认证"时可配置**。 简易认证指APP认证方式下调用API时，在GRPC请求头部消息增加一个参数X-Apig-AppCode，而不需要对请求内容签名，API网关也仅校验AppCode，不校验请求签名，从而实现快速响应。 当前支持GRPCS方式调用，不支持GRPC方式。具体使用请参考[配置APIG的API简易认证AppCode](https://support.huaweicloud.com/usermanual-apig/apig_03_0058.html)章节。 说明： 如果首次创建API未开启简易认证，那么之后开启简易认证，需要重新发布API。请参考[发布APIG创建的API](https://support.huaweicloud.com/usermanual-apig/apig_03_0014.html)章节发布。 | | 支持双重认证 | **仅当"安全认证"选择"APP认证"或"华为IAM认证"时可配置**。 是否对API的调用进行双重安全认证。如果选择启用，则在使用APP认证或IAM认证对API请求进行安全认证时，同时使用自定义的函数API对API请求进行安全认证。 | | 自定义认证 | **仅当"安全认证"选择"自定义认证"时需要配置**。 选择已创建的前端类型自定义认证。若没有可用的自定义认证，可单击右侧的"新建自定义认证"，创建一个前端类型的自定义认证。 | | 支持跨域CORS | 是否开启跨域访问CORS（cross-origin resource sharing）。 CORS允许浏览器向跨域服务器发出XMLHttpRequest请求，从而克服了AJAX只能同源使用的限制。 CORS请求分为两类： - 简单请求：头信息之中，增加一个Origin字段。 - 非简单请求：在正式通信之前，增加一次GRPC查询请求。 开启CORS（非简单请求）时，您需要单独创建一个"请求方法"为"OPTIONS"的API，具体操作请参考[开启跨域访问](https://support.huaweicloud.com/usermanual-apig/apig_03_0011.html)章节。 | | 链路追踪 | 是否开启链路追踪，默认关闭。开启后，网关会基于W3C Trace Context协议规范向后端传递请求头traceparent并记录链路追踪字段到请求日志中。 - 当前仅北京四、广州、上海一、上海二、新加坡、利雅得区域支持链路追踪功能。 - 查看调用链以及业务拓扑，需要[配置调用日志](https://support.huaweicloud.com/usermanual-apig/apig_03_0042.html)，选择APM应用。 | | 采样策略 | **仅当开启"链路追踪"时可配置**。 当前仅支持"按比例采样"策略。 | | 采样比例 | **仅当开启"链路追踪"时可配置**。 取值为0-100的整数，默认为100，100为采集每个请求，建议与后端服务的采样率保持一致。 | 6. 单击"下一步"，配置后端服务。 7. 定义默认后端。 添加策略后端前必须定义一个默认后端，当不满足任何一个策略后端的API请求，都将转发到默认的API后端。 在"后端配置"页面，选择API后端服务类型。 后端服务类型有[表4]、[表5]。 ![](https://support.huaweicloud.com/usermanual-apig/public_sys-resources/note_3.0-zh-cn.png) FunctionGraph依赖于函数工作流服务FunctionGraph，如果当前环境中未部署FunctionGraph服务，则后端服务类型FunctionGraph不可用。如果当前环境中已部署FunctionGraph服务，后端配置页面没有此功能，请联系技术支持工程师开通。 GRPC API的后端FunctionGraph类型，当前仅贵阳一、上海一、北京四、上海二、圣地亚哥区域支持。 表4GRPC\&GRPCS类型定义后端服务 | 参数 | 说明 | |:---|:---| | 负载模式 | 是否使用负载通道访问后端服务。 负载模式分为以下几种： - 不使用：指不使用负载通道访问后端服务，直接通过后端服务地址访问后端服务。 - 单模后端：指使用负载通道访问后端服务，并且支持对同一负载通道的不同服务器分组配置相同的请求协议。 - 多模后端：指使用负载通道访问后端服务，并且支持对同一负载通道的不同服务器分组配置不同的请求协议。多模后端模式受限使用，如需使用，请[提交工单](https://support.huaweicloud.com/usermanual-ticket/zh-cn_topic_0127038618.html)开通。 | | URL | URL地址由请求方法、请求协议、负载通道/后端服务地址和路径组成。 - **请求方法** 默认为POST。 - **请求协议** 支持"GRPC"或"GRPCS"。定义的后端服务协议须与用户的后端业务协议保持一致。 - **后端服务地址** **仅在不使用负载通道时，需要设置**。 填写后端服务的访问地址，格式："主机:端口"。主机为后端服务的访问IP地址/域名；端口为后端服务的端口。未指定端口时，GRPC协议默认使用80端口，GRPCS协议默认使用443端口。 如果后端服务地址中需要携带环境变量，则使用"#变量名#"的形式将环境变量添加到后端服务地址中，如#ipaddress#。支持添加多个环境变量，如#ipaddress##test#。 说明： IP地址/域名可以是公网IP（支持云服务器的弹性IP地址、用户自己服务器的公网IP地址、ELB地址）/公网域名，前提需要开启实例的公网出口。可以是内网的IP，不可以是内网域名。 2022年10月30日后创建的实例支持APIG与后端服务tls握手阶段向后端服务传SNI。 - **负载通道** **仅在使用负载通道（单模后端）时，需要设置** 。选择已创建的负载通道名称，或者[新建负载通道](https://support.huaweicloud.com/usermanual-apig/apig_03_0040.html)。 **负载通道中，云服务器的安全组必须允许100.125.0.0/16网段访问，否则将导致健康检查失败及业务不通。** - **路径** 默认为"/"。 | | 选择负载通道 | **仅在使用负载通道（多模后端）时，需要设置** 。选择已创建的负载通道名称，或者[新建负载通道](https://support.huaweicloud.com/usermanual-apig/apig_03_0040.html)。 | | 服务器分组信息 | **仅在使用负载通道（多模后端）时，需要设置**。 单击"添加服务器分组"，设置服务器分组信息。 - 服务器分组只能选择指定负载通道中配置的服务器分组，可以添加的服务器分组数量对应负载通道中配置的服务器分组数量。 - 请求方法和请求路径分别默认为"POST"和"/"，请求协议可选"GRPC"或"GRPCS"。 | | 自定义host头域 | **仅在使用负载通道（单模后端）时，可设置**。 自定义后端服务请求中的Host头域，默认将使用请求中原始的host头域。 | | 后端超时（ms） | 后端服务请求的超时时间，可填写范围1ms\~60000ms。 - 如果在API调试过程中，遇到后端响应超时之类的错误，请适当调大后端超时时间，以便排查原因。 - 如果当前的超时时间范围不能满足实际业务需求，请在实例[配置参数](https://support.huaweicloud.com/usermanual-apig/apig_03_0039.html)中修改超时时间上限，可修改范围为1ms\~600000ms。如果您修改了超时时间上限，需要同步修改此处的超时时间。 | | 重试次数 | 后端服务请求失败后的重试次数，默认值为0，取值范围-1\~10。 - 值为-1时，表示不开启重试功能，但除POST和PATCH外的其他请求类型会默认重试1次。 - 值为0\~10时，表示开启重试功能，并根据设置的值执行重试。当值为0时，不重试。 **使用负载通道时**，重试次数应小于负载通道中已启用的后端服务器个数。 | | TLS双向认证 | **仅在协议为"GRPCS"时，可设置。** 选择是否在API网关和后端服务间启用双向认证，如果选择"使用backend_client_certificate配置的证书做客户端认证"，您需在实例的[配置参数](https://support.huaweicloud.com/usermanual-apig/apig_03_0039.html)中提前配backend_client_certificate证书。 | | 后端认证 | 当您的后端服务需要对API调用增加自己的认证，则开启后端认证。 后端认证需要先添加一个[自定义认证](https://support.huaweicloud.com/usermanual-apig/apig_03_0029.html)，自定义认证通过函数服务实现，在函数服务中编写一个函数，实现您的认证鉴权流程，或者使用函数调用您的统一鉴权服务。 说明： 后端认证依赖函数服务，此功能仅在部分区域开放。 | 表5FunctionGraph类型定义后端服务 | 参数 | 说明 | |:---|:---| | 函数名 | 添加函数后，函数名自动生成。 | | 函数URN | 函数请求唯一标识。 单击"添加"，添加所需的函数URN。 | | 版本或别名 | 选择函数的版本或别名，函数的版本或别名功能请参考[版本管理](https://support.huaweicloud.com/usermanual-functiongraph/functiongraph_01_0180.html)章节或[别名管理](https://support.huaweicloud.com/usermanual-functiongraph/functiongraph_01_1829.html)章节。 | | 网络架构 | 选择函数网络架构。网络架构受限使用，如需使用，请[提交工单](https://support.huaweicloud.com/usermanual-ticket/zh-cn_topic_0127038618.html)开通。 默认V2：对接函数的VPC架构。 | | 调用类型 | 默认为Synchronous，同步调用。指后端函数服务收到调用请求后立即执行并返回调用结果，客户端发送请求后同步等待，收到后端响应后关闭连接。 | | 后端超时（ms） | 后端服务请求的超时时间，可填写范围1ms\~60000ms。 - 如果在API调试过程中，遇到后端响应超时之类的错误，请适当调大后端超时时间，以便排查原因。 - 如果当前的超时时间范围不能满足实际业务需求，请在实例[配置参数](https://support.huaweicloud.com/usermanual-apig/apig_03_0039.html)中修改超时时间上限，可修改范围为1ms\~600000ms。如果您修改了超时时间上限，需要同步修改此处的超时时间。 函数网络架构为"V1"时最大超时时间为60000ms，"V2"时最大超时时间可通过实例特性参数backend_timeout配置修改，可修改的上限为600000ms。 | | 后端认证 | 当您的后端服务需要对API调用增加自己的认证，则开启后端认证。 后端认证需要先添加一个[自定义认证](https://support.huaweicloud.com/usermanual-apig/apig_03_0029.html)，自定义认证通过函数服务实现，在函数服务中编写一个函数，实现您的认证鉴权流程，或者使用函数调用您的统一鉴权服务。 说明： 后端认证依赖函数服务，此功能仅在部分区域开放。 | 8. （可选）添加策略后端。 添加多个后端策略后，通过不同的策略条件，请求被转发到不同的后端服务中。 1. 单击![](https://support.huaweicloud.com/usermanual-apig/zh-cn_image_0000002105042072.png)添加策略后端。 2. 后端策略增加的参数，具体如[表6]所示，其他参数说明参考[表4]、[表5]。 表6后端策略参数 | 参数 | 说明 | |:---|:---| | 后端策略名称 | 您自定义的名称，用于识别不同的后端策略。 支持英文、数字、下划线和中划线，只能以英文字母开头，长度为3\~64个字符。 | | 生效方式 | 选择策略后端的生效方式。 - 满足任一条件：只要满足策略条件中的任意一项，此后端策略就可以生效。 - 满足全部条件：只有满足所有的策略条件，此后端策略才生效。 | | 策略条件 | 添加后端策略生效的条件，具体如[表7]所示。 | 表7策略条件 | 参数 | 说明 | |:---|:---| | 条件来源 | 策略条件中判断条件的来源。 - 源地址：以访问API的请求地址作为策略条件来源。 - 请求入参：以请求入参参数作为策略条件来源。 - Cookie：表示以API请求的Cookie信息作为判断条件。 - 系统参数：以网关内置参数作为策略条件来源。网关内置参数指API网关处理API请求时的系统运行时参数信息。 - 第三方认证响应参数：以第三方认证策略的响应报文头部参数作为策略条件。**第三方认证响应报文头部参数的"键"和"值"最长长度分别为255和1024个字符** 。只有当API绑定了[第三方认证策略](https://support.huaweicloud.com/usermanual-apig/apig_03_0077.html)时，该条件才会生效。 说明： - 选择"请求入参"作为策略条件时，入参需要在API前端请求中配置好，如在Header中添加一个参数。 - 如果未展示"系统参数"请联系技术支持工程师升级实例。 | | 参数名称 | - 当"条件来源"为"请求入参"时，需要设置。选择已创建的入参参数名称。 - 当"条件来源"为"系统参数"时，需要选择参数名称。 - reqPath：请求URI，如"/a/b/c"。 - reqMethod：请求方法，如"GET"。 - 当"条件来源"为"COOKIE"时，需要填写Cookie中的参数名称。 - 当"条件来源"为"第三方认证响应参数"时，需要填写第三方认证策略响应报文头部参数的键。支持英文、数字、点、下划线和中划线，长度为1\~255个字符。 | | 参数位置 | 仅在"条件来源"为"请求入参"时，展示请求入参的参数位置。 | | 条件类型 | 仅在"条件来源"为"请求入参"、"系统参数"、"COOKIE"、"第三方认证响应参数"时需要配置。 - 相等：请求参数值必须为输入值时，条件成立。 - 枚举：请求参数值只需要和枚举值中任何一个值相同，条件成立。 - 匹配：请求参数值只需要和正则表达式中任何一个值相同，条件成立。 说明： 当"条件来源"为"系统参数"并且"参数名称"为"reqMethod"时，"条件类型"仅支持选择相等或枚举。 | | 条件值 | 填写判断条件的值，条件值的长度为1\~1024个字符。 - "条件类型"为"相等"时，输入一个值。 - "条件类型"为"枚举"时，输入多个值，以英文逗号隔开。 - "条件类型"为"匹配"时，输入一个范围，例如：\[0-5\]。 - "条件来源"为"源地址"时，输入一个或多个IP地址，以英文逗号隔开。 - "条件来源"为"系统参数-前端认证参数"时，且当条件值填写boolean类型时，需全部小写。 | 9. 单击"完成"，进入"API运行"页面，可查看API详情。 #### 相关文档 - API创建完成后，通过[调试API](https://support.huaweicloud.com/usermanual-apig/apig_03_0012.html)，验证服务是否正常。 - 创建API相关的FAQ： - [API网关是否支持多后端节点方案？](https://support.huaweicloud.com/apig_faq/apig-faq-180606012.html) - [为什么后端服务调用失败？](https://support.huaweicloud.com/apig_faq/apig_0087908599.html) - [在API网关中创建完成API，调用时报"No backend available"错误，怎么解决？](https://support.huaweicloud.com/apig_faq/apig-faq-181016018.html) - 通过API网关可以实现gRPC服务的路由转发，具体操作，请参考[使用APIG专享版实现gRPC服务的路由转发](https://support.huaweicloud.com/bestpractice-apig/apig-bp-0037.html)章节。 - 如果您希望通过API创建GRPC API，请参考[创建API](https://support.huaweicloud.com/api-apig/CreateApiV2.html)。