奇门中心
接入流程
1. 入驻奇门
登录 qimen.taobao.com。
2. 创建场景
选择『奇门云网关』 -> 『企业云网关』 -> 『创建场景』。
创建成功以后，会给该场景下的所有API分配一个随机二级泛域名。
如果帐号还没有创建过应用，则需要在应用管理里面创建一个应用再做创建。
3. 定义API
1）在场景列表中点击『管理』，可以进入到API管理页面。
2）点击『创建API』，可以进入到API创建页面。
① 填写基本信息
API取名通用规则：公司.[业务线].数据[s].[属性].操作; API名称全部由小写字母组成，并且不少于3个词; []为可选词，如果操作的数据为列表，建议加上复数形式（词尾加s）。
② 填写请求参数，可以使用query参数和Body参数
query参数：
日志索引：query参数中允许勾选一个参数作为奇门的索引条件，建议勾选能快速搜索数据的字段，比如唯一的订单号，后面方便在奇门日志中搜到。
body参数：
报文类型： 报文类型支持 XML 和 JSON。 按实际需求选择，注意不要选错。
Body类型： 包括：String,Number,Boolean,Struct,String[],Number[],Boolean[],Struct[]。Struct为复杂类型。
公共参数：
另外，调用奇门的时候需要传递公共参数（如果使用SDK默认已经被SDK封装在内了），可以参考公共参数说明。注意！公共参数是传递给奇门云网关使用的，并不一定会传递给业务方，所以不能作为业务参数使用！并且自定义参数也不能命名同公共参数。
③ 请求映射
请求映射用来配置目标服务后端的正式地址以及测试地址（提供服务的地址，必须以http://和https://开头），服务的超时时间设置（最多不超过30秒），以及API被调用时候，用户需要透传的targetAppkey，主要用于安全验签，验签的目的是防止黑客恶意调用你的服务，确保服务发起来源来自奇门云网关。
i）服务后端正式URL：填写实现API的服务的正式地址，做为正式提供服务。
ii）服务后端测试URL：填写实现API的服务的测试地址，以便测试使用。
④ 请求映射地址修改
用来修改目标服务后端的正式地址以及测试地址 ，修改地址需要到左侧授权配置》配置奇门授权里面修改。
⑤ 响应配置
响应参数的配置如下：
响应失败参数配置如下：
i）参数名：奇门云网关标准输出字段。响应失败的时候，请求奇门的时候会返回该结构。
ii）成功失败判断条件flag为判断失败的标准。这里也可以使用自己的字段来判断是否成功。
iii）sub_code 为二级错误码，可以映射自己的字段。
iv）sub_message 二级错误信息，可以映射自己的字段。
如果请求异常或者业务错误，请以响应失败参数的结构来返回。如果返回的结构不符合响应参数的结构，则网关会报无法解析的错误。
4. API实现
1）接口实现
按照之前定义的API来实现服务的逻辑。
2）验签
为了防止接口被人乱掉用，需要在服务端做验签的逻辑，校验请求的合法性。那么， API服务后端如何进行验签 ？由于API请求带有targetAppkey，而API服务后端可以通过应用管理拿到对应的appSecret，将奇门云网关生成的签名，与自己服务后端代码生成的签名进行校验，当然TOP API SDK也提供了相关的验签工具（SpiUtils）， 需要在执行接口逻辑前完成验签校验逻辑 。
验签返回报文
验签的返回内容需要和响应失败的格式（参考上文响应失败参数）对应的上，系统要求如下：
| 奇门参数名 | 类型映射值 | 参数值 |
| flag | 以实际配置为准 | 满足失败条件 |
| sub_code | 以实际配置为准 | sign-check-failure |
| sub_message | 以实际配置为准 | Illegal request |
如果还不知道验签需要返回什么内容，可以查看『接口文档预览』里面的『验签demo』。
其中参数名为系统要求的值，如果映射值不同，则以实际映射值为准。返回格式可以参考『接口文档预览』页面的验签demo。如果没有完成验签逻辑，API发布时候会提示验签失败。
java代码示例如下：
CheckResult result = SpiUtils.checkSign(request, targetAppSecret);? //这里执行验签逻辑 if(!result.isSuccess()) { //如果验签失败则需要返回 验签失败的结果，并且需要和配置对应的上，系统才认为是验签成功 HttpSampleResponse httpSampleResponse = new HttpSampleResponse(); httpSampleResponse.setErrorMessage("Illegal request"); httpSampleResponse.setErrorCode("sign-check-failure"); httpSampleResponse.setFlag("failure); //return }
5. API自测
这里的测试环境和正式环境分别对应前面填写的正式和测试的两个地址。
注意：API没有发布之前无法选择正式环境，请选择测试环境。
6. API发布
如果自测通过，则可以点击『自测通过请发起服务验证』，此时系统会发起非法请求请求服务后端，如果后端不满足验签逻辑则提示错误。具体验签逻辑参考上文。验证通过可以点击发布上线。
注意：
1）发布会进入平台小二流程，一般审核时间5-7个工作日，需要详细描述接口使用场景。
2）发布上线后，请在自测页面选择正式环境测试是否成功发布成功。
7. 添加授权
API上线后想让别的应用调用还需要在后台配置授权。如图中步骤添加即可。
8. SDK的使用
API发布后，别人想调用可以通过SDK来调用。 注意必须API发布后下载的SDK的结构才是没问题的，如果变更了API需要重新上线并重新生成SDK才能看到对应的数据结构。
1）SDK的下载
点击『应用管理』， 『SDK下载』可以下载SDK。
2）SDK的使用
String appkey = ""; String appSecret = ""; String format = "JSON"; /* * 这里的URL可以参考测试工具上的链接，域+后缀 * 后缀如果测试环境地址则为/router/qmtest，如果是正式地址则为/router/qm */ String url = "https://j6778fdz70.api.taobao.com/router/qmtest"; String apiName = ""; String targetAppkey = ""; DefaultQimenCloudClient client = new DefaultQimenCloudClient(url, appkey, appSecret, format); QimenCloudRequest request = new QimenCloudRequest(); request.setApiMethodName(apiName); //注意！ 千万不能少了这一步 request.setTargetAppKey(targetAppkey); //添加参数 //request.addQueryParam(key, value); QimenCloudResponse response = null; try { response = client.execute(request); } catch (ApiException e) { e.printStackTrace(); }
如果接入过程还有任何问题，可以加技术支持钉钉群（1群：11746343（已满）、2群 : 21771580（已满）、3群：23396781）。
