本章节汇总了原API网关中API定义相关问题。
API定义问题
API定义问题
API网关是否支持gzip数据压缩，是否需要添加请求头Accept-Encoding ？
支持的，同时符合以下三点时会将应答压缩：
请求中携带Accept-Encoding头，并且这个字段的值必须包含gzip。
应答body大小大于2K。
应答body contenttype为text/xml text/plain text/css application/javascript application/x-javascript application/rss+xml application/xml application/json application/octet-stream。
用户传了一个未定义的参数，网关将如何处理？
入参映射（过滤未知参数）模式下，网关将过滤掉用户多传的参数。
入参映射（透传未知参数）模式和入参透传模式下，网关会将参数透传到后端服务。
后端服务是否可以使用HTTPS？
可以，在录入后端服务地址时，请以https://开头，且需要保证您的后端服务已有SSL证书。
API基础定义是什么？
可以配置您API被访问的方式，包含：http或https，以及使用HTTP方法，目前网关支持所有标准的HTTP方法。
为什么要填写API描述？
对于API功能的具体描述，会展示给您的用户。
API类型是什么？
API的类型包含公开、私有两种。若在云市场上架商品，公开的接口会上架展示给客户，私有接口不会展示给客户。
API名称是什么？
名称是API的标识，一个有意义的名称，可以让您的用户能够快速理解API的功能。
API更新是否会有延迟？
不会，API一旦发布会立即生效。
如何使您的API支持HTTPS？
首先，您需要申请一张SSL证书，然后将SSL证书，将证书绑定到网关（查看分组管理—点击分组名称进入分组详情-找到相应域名-上传证书）。
其次，将您的API请求协议修改为：HTTPS或者HTTP和HTTPS。
后端服务地址如何录入？
后端服务地址可以是域名，也可以是IP，录入时，要以http://或者https://开头
后端服务地址中支持动态参数，用[param]表示。
后端服务地址中可以存在多个动态参数，多个动态参数名称不可重复。
后端服务地址中的动态参数需要配合Path中的动态参数使用，在配置Path时，配置与Path的映射关系。
为什么要定义参数？
参数是API请求的重要组成部分，网关可以根据参数定义为您的用户生成API手册。
参数定义是必须的吗？
不是，但推荐您定义，以便您的API用户能够清楚地理解您的API。
不定义参数网关如何处理？
会根据配置的入参请求模式进行处理。
参数定义包含什么？
描述参数在请求中的位置（path、header、query、body）、参数说明、参数示例及参数值限制。
可以对参数做哪些限制？
网关不仅支持参数最大值、最小值、长度、枚举校验，还支持正则、Json Schema校验。
Path是什么？
Path是您的API调用时展示给客户的固定路径，也是API的标识，在同一分组下HTTP Method+Path不可以重复。
在Restful API中，一般表示为资源，格式为资源/子资源，如：instance/disk。
Path中支持动态参数，用[param]表示，如：instance/disk/[diskid]，可以与后端服务地址中的动态参数进行映射。
如何配置Path与后端服务地址中的动态参数？
在配置Path时，控制台可以自动带出后端服务地址中的动态参数，您需要将其与Path中动态参数对应上即可。
Path与后端服务地址中的动态参数名称、顺序是否必须保持一致？
不需要。在配置Path时，可以建立映射关系。
APP是什么，怎么从用户实际的应用关联到我们定义的APP，实际应用是移动端还是Web端？
APP是您在阿里云的一个虚拟应用，是调用API时的身份标识，它可以是您的一个Web应用，也可以是移动端应用，或者其他。API网关会自动给每个APP分配一对APP Key和Secret，用以签名请求，调用API。
如何指定调用环境？
调用API时，默认是调用线上环境的API。
如果要调用测试环境，请在header中增加参数：X-Ca-Stage:TEST。
如果要调用预发环境，请在header中增加参数：X-Ca-Stage:PRE。
如何获取API网关报错信息？
所有的 API 请求只要到达了网关，网关就会返回请求结果信息。
用户需要查看应答的Header部分。其中X-Ca开头的均为网关返回，比较重要信息是：
X-Ca-Request-Id：请求唯一ID，请求一旦进入API网关应用后，API网关就会生成请求ID并通过响应头返回给客户端，建议客户端与后端服务都记录此请求ID，以便用于问题排查与跟踪。X-Ca-Error-Message：API网关返回的错误消息，当请求出现错误时API网关会通过响应头将错误消息返回给客户端。X-Ca-Error-Code：API网关系统错误码，当请求出现错误被网关拦截后，由API网关提供的错误码。
在应答的Header中获得X-Ca-Error-Code与X-Ca-Error-Message可以基本明确报错原因，而X-Ca-Request-Id可以用于在日志服务中查询请求日志、通过控制台查询结果、或提供给支持人员进行日志排查。
X-Ca-Error-Code可以查找错误代码表来获取更详细的排错解释。
如何关闭公网访问？
API网关支持关闭分组的公网访问，仅通过内网访问。操作步骤如下：
登录API网关控制台，在左侧栏单击开放API——分组管理。
在分组列表中找到想要关闭公网访问的分组，单击分组名称进入分组详情页。
在分组详情页的公网二级域名后面找到关闭公网访问按钮，单击确定后即可关闭公网访问。
关闭公网访问后，所有来自公网的访问，包括自定义公网域名的访问都将被拒绝，仅支持通过内网域名调用。
API网关调试功能不支持内网域名的调试。
HTTP/HTTPS请求的返回值为空
HTTP/HTTPS 请求的返回结果有 HttpCode、Header、Body 三部分。当请求报错时，由于没有进入业务逻辑，所以返回的 Body 可能为空，表现为“返回值为空”，但实际上，重要信息都在 Header 里面。
用户发起的 API 请求只要能够到达网关，就会返回成功/错误的结果信息。
重要的返回信息都在Header里面，以X-Ca开头的为网关返回的信息。其中较主要的为下面的几个信息：
X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF
//请求唯一ID，请求一旦进入API网关应用后，API网关就会生成请求ID并通过响应头返回给客户端，建议客户端与后端服务都记录此请求ID，可用于问题排查与跟踪
X-Ca-Error-Message: Invalid Url
//API网关返回的错误消息，当请求出现错误时API网关会通过响应头将错误消息返回给客户端
X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}
//当打开Debug模式后会返回Debug信息，此信息后期可能会有变更，仅用做联调阶段参考所以如果发送请求后，发现返回值为空，那么看一下返回的 Header 信息。如果请求到达网关就错误返回了，那么 Body 为空很正常，会表现为返回值为空，但是在 Header 里面会有重要信息。
如果Header也为空，那么说明请求没有达到网关，请自行检查网络状况等。
各种语言获取和查看 HTTP/HTTPS 头部信息的方法均可在网上查询到。
HTTPS 证书报错
调用 HTTPS 接口出现证书认证错误或者提示证书已经过期。
原因及解决方案
证书不合法
API 提供者使用的证书是其他非主流机构颁发的证书，此类证书使用浏览器访问是没有问题的，因为浏览器会自动更新根证书。但老版本操作系统的根证书对这些机构（证书颁发机构）的不信任或者信任时间已经过期。
解决方案：
升级客户端根证书。如：Java+Linux 升级 OpenSSL 客户端即可，其他操作系统+编程语言，请升级编程语言中 HTTPS 使用的根证书。
联系 API 提供者，要求其更换兼容性更好的主流 SSL 证书。
程序中忽略检查 SSL 证书有效性（不推荐），忽略后会有请求被劫持的安全风险。只在与 API 提供商无法提供兼容性更好的主流 SSL 证书，且安全风险可控的前提下，可以考虑使用此方法。
API提供者的 SSL 证书过期
提供者的 SSL 证书过期。
解决方案：
联系 API 提供者，要求其更换 SSL 证书。
程序中忽略检查 SSL 证书有效性（不推荐），忽略后会有请求被劫持的安全风险。只在与 API 提供商无法提供兼容性更好的主流 SSL 证书，且安全风险可控的前提下，可以考虑使用此方法。
后端服务调不通
如果您在使用API网关的过程中，遇到后端服务调不通的情况，您可参考如下方法进行排查：
需要检查您录入的后端服务地址是否正确。
需要保证您的后端服务可以被网关访问到。
检查您API定义的“后端超时”时间。
在API定义时会要求您录入一个超时时间，当您的后端服务没有在您指定的时间内返回时，API网关仍然会提示您无法连接后端服务。您可以根据后端服务的实际耗时对"后端超时"进行调整，共享实例最大支持30000ms，专享实例最大支持5min。
说明注意：单位是ms（毫秒）。
后端超时时间注意不能设置为0，更多关于超时时间的描述可参考TCP连接超时时间配置。
如后端服务在 ECS ，请检查安全组设置，是否可以被外部访问。请保证安全组可以被API网关的出口IP段访问。
需要强调，API网关访问外部的出口IP不能保证不会变动，通过设置安全组来判断请求来源的方法可能会由于API网关出口IP变化而导致API网关访问后端服务失败，因此我们不建议使用安全组方法。API网关提供了完整的后端签名验证的方式来做身份认证，使用后端签名机制可以完全避免这种不确定性，我们强烈建议使用此方法来确认请求来源。使用具体文档：后端签名插件。
API网关实例出口IP查看方法：
API网关的出口IP请查看分组所在实例的出口IP，具体查看方法：
1、 先登录API网关控制台-【API管理】-【分组管理】-【分组详情】查看分组所在实例信息。
2、到【实例与集群】页面查看对应实例的出口地址。