# 开放平台介绍
# 1 授权认证
F6开放平台采取的是摘要签名认证方式，客户端在调用API时，需要使用签名密钥对请求内容进行签名计算，并将签名同步传输给服务器端进行签名验证。API网关提供的SDK内置了签名实现，您只需要将签名密钥配置在SDK中，即可实现发起携带正确签名的请求。如果您需要自己在客户端实现签名计算过程，可以参考文档。
# 2 SDK使用
# 2.1 环境准备
- API网关Java SDK适用于
JDK 1.6及以上版本 - 我们会给您准备一对授权密钥供SDK生成鉴权和签名信息，即 AppKey和AppSecret
应用（APP）是您调用 API 服务时的身份。每个 APP 有一组 Key 和 Secret，您可以理解为账号密码，您调用 API 的时候需要将 AppKey 做参数传入，AppSecret 用于签名计算，网关会校验这对密钥对您进行身份认证。
调用 API 需要这个 APP 具备调用该API的权限，这个授权和鉴权也是面向 APP 的。
您可以在 API 网关控制台 应用管理 页面创建您的 APP。
创建成功后，系统会为 APP 分配一对 AppKey 和 AppSecret。您需要使用 AppSecret 完成签名计算，您请求时需要携带签名信息，网关会通过签名信息对您做身份验证。
重要提示：**AppKey**和**AppSecret**是网关认证用户请求的密钥，这两个配置如果保存在客户端，请妥善加密。
- 在pom.xml中添加如下依赖：
<dependency>
<groupId>com.aliyun.api.gateway</groupId>
<artifactId>sdk-core-java</artifactId>
<version>1.1.0</version>
</dependency>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
<version>1.2.68</version>
</dependency>
# 2.2 示例代码
f6-gateway-demo-master-ed5f1f568ba43a5a4ebce6d69dfc625212738191.zip
# 2.3 初始化通信通道类
要提交请求至API网关，您首选要将所有的通道类初始化。您可以参考示例代码，使用对应的ClientBuilderParams类来初始化所有通道：
# 2.3.1 HTTP通道类的初始化
HttpClientBuilderParams httpParam = new HttpClientBuilderParams();
httpParam.setAppKey("");
httpParam.setAppSecret("");
HttpApiClientchuxiang.getInstance().init(httpParam);
####注意####
HttpClientBuilderParams里面有很多构造参数，主要是对ApacheHttpClient开源组件的包装，具体参数含义可以自行搜索这个开源组件的参数说明（官方文档：https://hc.apache.org/httpcomponents-client-4.5.x/current/tutorial/html/index.html）。
# 2.4 调用API接口
SDK为您封装了单例模式的调用方法，您可以使用getInstance()方法来获得通道类对象。
每个API同时提供同步和异步的调用方法，下面是调用示例：
//异步调用示例
public void test06HttpCommon() throws Exception {
HttpClientUnitTest.getInstance().getUser(userId , new ApiCallback() {
@Override
public void onFailure(ApiRequest request, Exception e) {
e.printStackTrace();
}
@Override
public void onResponse(ApiRequest request, ApiResponse response) {
try {
System.out.println(response.getCode());
System.out.println(response.getMessage());
System.out.println(response.getFirstHeaderValue("x-ca-request-id"));
}catch (Exception ex){
ex.printStackTrace();
}
}
});
}
//同步调用示例
public void test06HttpGetUser(int userId) throws Exception {
ApiResponse response = HttpClientUnitTest.getInstance().getUserSyncMode(userId);
System.out.println(response.getCode());
System.out.println(response.getMessage());
System.out.println(response.getFirstHeaderValue("x-ca-request-id"));
}
####注意####
- 您必须先
init()初始化后，才可以调用getInstance()方法，否则会抛出异常。 - 建议使用异步调用，在整个等待应答期间，主线程不会被hang住。
# 2.5 环境说明
X-Ca-Stage: 表示的不同的环境，目前只有 TEST、PRE、RELEASE(默认)
在http的header上增加上述指定头可以调用不同环境 默认为生产环境
# 2.6 请求参数说明
目前网关参数均通过body传递 并且存在公共类如下
{
"paramValues": [
]
}
即请求需要通过paramValues进行包裹
一个典型的请求参数如下
{
"paramValues": [
{
"pageSize": 5
}
]
}
# 2.7 返回结果说明
返回结果通过结果类包装
通常使用http语义
比如典型错误如下
{"code":500,"message":"remote invoke failed"}
一个成功的请求 判断200
{"code":200,"data":{}, "message":"SUCCESS"}
除了业务系统返回出错 还存在网关的错误 排查见下一章节
# 2.8 网关常见排查
- 当客户端收到的应答中
X-Ca-Error-Code头不为空，表示应答码由API网关产生，错误码由一个6位长度的字符描述，请参考下表，而X-Ca-Error-Message表示错误的应答信息，用于描述改场景下更详细的一些错误信息。 - 如果
X-Ca-Error-Code头为空，则表示这个Http应答码由后端服务产生，API网关透传了来自后端的错误信息。
| 错误代码 | Http状态码 | Message | 描述 |
|---|---|---|---|
| I400HD | 400 | Invalid Header ${HeaderName} ${Reason} | HTTP请求头非法 |
| I400MH | 400 | Header ${HeaderName} is Required | 缺少HTTP请求头 |
| I400BD | 400 | Invalid Body: ${Reason} | HTTP请求包体非法 |
| I400PA | 400 | Invalid Request Path ${Reason} | HTTP请求路径非法 |
| I405UM | 405 | Unsupported Method ${Reason} | 不支持的HTTP请求方法 |
| I400RU | 400 | Invalid Request Uri ${Reason} | HTTP请求Url非法 |
| I403PT | 403 | Invalid protocol ${Protocol} unsupported | 使用了API配置中不支持的协议，请检查API配置 |
| I413RL | 413 | Request body too Large | 请求包体过长 |
| I413UL | 413 | Request URL too Large | 请求URL过长 |
| I400CT | 400 | Invalid Content-Type: ${Reason} | 非法的Content-Type |
| I404DO | 404 | Invalid Domain ${DomainName} | 未知的请求域名 |
| I410GG | 410 | Group's instance invalid | 请求了非法的实例，分组可能已经不属于当前实例 |
| I400SG | 400 | Invalid Stage | 请求了未知的环境 |
| I404NF | 404 | API not found ${Reason} | 根据请求的Path,Method在当前的环境中未找到API |
| X400PM | 400 | Invalid plugin meta ${PluginName} ${Reason} | 插件元数据非法，请工单联系客服人员 |
| X500ED | 500 | Expired api definition | API元数据定义非法，请工单联系客服人员 |
| X500AM | 500 | Invalid Api Meta, try deploy again or contact us via ticket | API元数据定义非法，请工单联系客服人员 |
| X403DG | 403 | Bad Domain or Group: ${Reason} | 分组数据非法,请工单联系客服人员 |
| B451DO | 451 | Unavailable Domain for Legal Reasons | 域名因法律法规问题被禁 |
| B451GO | 451 | Unavailable Group for Legal Reasons | 分组因法律法规问题被禁 |
| B403OD | 403 | Provider Account Overdue | API提供方欠费 |
| A400AC | 400 | Invalid AppCode ${Reason} | 当使用AppCode模式授权时，未找到AppCode |
| A400IK | 400 | Invalid AppKey | 当使用Key/Secret签名授权时，未找到AppKey |
| A403IS | 403 | Invalid Signature, Server StringToSign:${StringToSign} | 签名不匹配，请参考API网关签名文档 |
| A403EP | 403 | App authorization expired | 授权已过期 |
| A403PR | 403 | Plugin Authorization Needed | 需要插件授权 |
| A400MA | 400 | Need authorization, X-Ca-Key or Authorization: APPCODE ... is required | 需要使用Key/Secret签名授权或AppCode授权 |
| I400I5 | 400 | Invalid Content-MD5 ${Reason} | 不匹配的Content-MD5 |
| I400NC | 400 | X-Ca-Nonce is required | 当设置了使用X-Ca-Nonce防重放选项时，必须提供X-Ca-Nonce头 |
| S403NU | 403 | Nonce Used | 检测到请求重放，请求的X-Ca-Nonce头重复 |
| S403TE | 403 | X-Ca-Timestamp is expired | X-Ca-Timestamp头中提供的时间戳已过期 |
| I400MP | 400 | Parameter ${ParameterName} is required | API中配置的必选参数未传值 |
| I400IP | 400 | Invalid parameter ${ParameterName} ${Reason} | API中配置的参数值非法 |
| I400JR | 400 | JWT required | 未找到JWT参数 |
| S403JI | 403 | Claim jti is required when preventJtiReplay:true | 当在JWT授权插件中配置了防重放功能时，请求未提供有效的jti |
| A403SV | 403 | Claim jti in JWT is used | 当在JWT授权插件中配置了防重放功能时，请求提供的jti已被使用 |
| I400JD | 400 | JWT Deserialize Failed: ${Token} | 请求中提供的JWT解析失败 |
| A403JT | 403 | Invalid JWT: ${Reason} | 请求中提供的JWT非法 |
| A403JK | 403 | No matching JWK, ${kid} not found | 请求JWT中的kid没有匹配的JWK |
| A403JE | 403 | JWT is expired at ${Date} | 请求中提供的JWT已过期 |
| I400JP | 400 | Invalid JWT plugin config: ${JWT} | JWT授权插件配置错误 |
| A403OL | 403 | OAuth2 Login failed: ${Reason} | |
| A403OU | 403 | OAuth2 Get User Info failed: ${Reason} | |
| A401OT | 401 | Invalid OAuth2 Access Token | |
| A401OM | 401 | OAuth2 Access Token is required | |
| T429ID | 429 | Throttled by INNER DOMAIN Flow Control, ${Domain} is a test domain, only 1000 requests per day | 当使用默认二级域名访问时，限制1000次/天，请绑定正式域名以解除这个限制 |
| T429IN | 429 | Throttled by INSTANCE Flow Control | 触发当前实例的流控限制 |
| T429GR | 429 | Throttled by GROUP Flow Control | 触发当前分组的流控限制 |
| T429PA | 429 | Throttled by API Flow Control | 触发插件上的默认API流控 |
| T429PR | 429 | Throttled by PLUGIN Flow Control | 触发插件的特殊流控 |
| T429UP | 429 | Throttled by Usage Plan Flow Control | 触发使用计划的流控 |
| T429SR | 429 | Throttled by SERVER Flow Control | |
| T429MR | 429 | Too Many Requests, throttle by ${Description} | |
| A403IP | 403 | Access denied by IP Control Policy | 被IP访问控制插件阻止访问 |
| A403IN | 403 | Access from internet is disabled ${Reason} | API或API分组禁止从公网访问 |
| A403VN | 403 | Access from invalid VPC is disabled | 来源VPC被阻止 |
| A403AC | 403 | Access Control Forbidden by ${RuleName} | 被授权控制插件阻止 |
| A403CO | 403 | Cross origin resource forbidden ${Domain} | 被CORS策略阻止访问 |
| I404CO | 404 | Cross origin resource not found ${Method} - ${Path} | 根据CORS预检请求中的Path与Method，无法找到API定义 |
| I404CH | 404 | Content not cached, with Cache-Control:only-if-cached | |
| I404NR | 404 | ${Resource} not found | |
| I404SR | 404 | Stage route missing: ${Reason} | |
| B403MO | 403 | Api Market Subscription overdue | API提供商欠费 |
| B403MQ | 403 | Api Market Subscription quota exhausted | 购买的云市场API配额已耗尽 |
| B403ME | 403 | Api Market Subscription expired | API订购关系已过期 |
| B403MI | 403 | Api Market Subscription invalid | API市场订购关系非法 |
| D504RE | 504 | Backend domain ${Domain} resolve failed | 后端域名解析失败 |
| D504IL | 504 | Backend domain ${Domain} resolve to illegal address ${Address} | 后端域名解析结果非法 |
| D504CO | 504 | Backend service connect failed ${Reason} | 后端连接失败，请检查安全组、后端服务器启动状态、或防火墙配置 |
| D504CS | 504 | Backend http ssl connect failed ${Reason} | 后端HTTPS连接失败，请检查后端配置的协议与端口是否匹配 |
| D504TO | 504 | Backend service request timeout | 后端请求超时 |
| X504VE | 504 | Backend service vpc mapped failed | 后端VPC映射错误，请工单联系客服人员 |
| D503BB | 503 | Backend circuit breaker busy | API被断路器阻止 |
| D503CB | 503 | Backend circuit breaker open, ${Reason} | API处于熔断/断路器开状态，请检查后端性能 |
| I508LD | 508 | Loop Detected | 检测到环回调用 |
| I404DD | 404 | Device id ${DeviceId} not found | 当使用WebSocket双向通信调用时，DeviceId未找到 |
| A403FC | 403 | Function Compute AssumeRole failed ${RequestId} ${Reason} | 后端是函数计算时授权错误 |
| D502FC | 502 | Function Compute response invalid: ${Reason} | 后端是函数计算时，来自后端的应答非法 |
| X500ER | 500 | Service Internal Error | 服务器内部错误，请工单联系工作人员 |
| X503BZ | 503 | Service Busy | API网关服务忙，请稍后再试或工单联系工作人员 |
| X504TO | 504 | Service timeout | API网关处理超时 |
部分错误代码可能随着升级或新功能的加入而改变。
# 3 调用域名
http://api.f6car.cn
# 4 Postman示例（V2版）
使用时需将向商户分发的appKey和appSecret填写到Pre-request的脚本中
门店列表 →