一、核心链路

外部云服务相关的http请求可分为两大类：接收淘宝平台的请求 和 发起淘宝平台请求，两类请求均会经过淘宝的开放网关。

说明

1）TOP API：是平台提供的业务API，通常用于外部生态的服务端调用，获取平台的可开放数据或将数据同步淘宝业务后端，比如获取虚拟直充商品信息的能力；

2）奇门 API：是平台定义好的接口，需要外部生态实现对应的能力，供平台调用并获取生态的数据返回，比如虚拟直充的充值到账能力；

3）这两类API，和平台的交互，均可通过淘宝开放平台的SDK进行，SDK提供了验签的工具等，以及一些出入参的封装。文档最后附上了SDK的下载方式。

二、接收请求

1. 来自小游戏端发起的网络请求

小游戏在淘宝客户端内请求外部云服务，必须通过平台网关转发。每个外部云服务，对应可在平台申请注册一个空应用，空应用可以理解为外部云服务在淘内申请的一个合法请求凭证，每个空应用拥有一个唯一的标识：cloudAppId，前端发起调用时，通过cloudAppId 、domain、path进行具体的api调用。

调用后端的方式，请参考：小游戏前端开发文档 中，调用服务端的部分。

后端获取登录用户的openId

openId可通过云服务请求的上下文获取，详细可参考：获取openId的方式

2. 来自淘宝平台业务系统发起的网络请求（奇门API）

小游戏在对接虚拟直充和广告能力时，部分能力的调用是由平台侧后端向小游戏后端发起的，这部分调用是通过奇门API实现的，通常是平台定义了奇门场景，以及该场景下的API，由小游戏开发者实现对应的API。

小游戏的后端，需要查看对应的奇门API的出入参定义，并按该API的规范实现具体的逻辑和返回。具体的API出入参以及对接流程，可以参考直充和广告能力的开发对接文档，每个API都有独立的参数规范，需要以具体API的定义为准。

奇门场景的介绍文档可参考：奇门官方场景接入说明。其中，虚拟直充使用的奇门API，为较低版本的奇门，入口名字为“API服务提供”，API对接方式与新的奇门场景没有区别。

3. 请求加签&验签

小游戏里发起的http请求，以及平台发起的奇门API请求，均可以通过淘宝开放平台的SDK做请求的验签。

需要注意，小游戏发起http请求，必须使用 cloud.application.httpRequest 发起调用，否则会导致验签无法通过。

1）签名算法

如果签名算法如下。

/**
     * 
     * 
     * @param params
     *            所有字符型的TOP请求参数（这个是除了sign以外的所有字段）
     * @param body
     *            请求主体内容
     * @param secret
     *            签名密钥
     * @param signMethod
     *            签名方法，目前支持：空（老md5)、md5, hmac_md5三种
     * @return 签名
     */
public static String signTopRequest(Map<String, String> params, String body, String secret, String signMethod)
throws IOException {
  // 第一步：检查参数是否已经排序
  String[] keys = params.keySet().toArray(new String[0]);
  Arrays.sort(keys);
  // 第二步：把所有参数名和参数值串在一起
  StringBuilder query = new StringBuilder();
  if (Constants.SIGN_METHOD_MD5.equals(signMethod)) {
    query.append(secret);
  }
  for (String key : keys) {
    String value = params.get(key);
    if (StringUtils.areNotEmpty(key, value)) {
      query.append(key).append(value);
    }
  }
  // 第三步：把请求主体拼接在参数后面
  if (body != null) {
    query.append(body);
  }
  // 第四步：使用MD5/HMAC加密
  byte[] bytes;
  if (Constants.SIGN_METHOD_HMAC.equals(signMethod)) {
    bytes = encryptHMAC(query.toString(), secret);
  } else if (Constants.SIGN_METHOD_HMAC_SHA256.equals(signMethod)) {
    bytes = encryptHMACSHA256(query.toString(), secret);
  }  else {
    query.append(secret);
    bytes = encryptMD5(query.toString());
  }
  // 第五步：把二进制转化为大写的十六进制
  return byte2hex(bytes);
}

2）SDK验签

开发者要求使用验签算法来对请求合法性进行校验。服务端验签可以使用淘宝开放平台sdk提供的工具类SpiUtils，验签失败时候返回“验签失败回应示例”的内容即可，验签逻辑如下。SDK提供有java,c#,php,C,NodeJS版本，如果您不使用SDK，可以把该工具类拷贝到工程中；如果您使用的语言没有对应的SDK版本，可以参考签名算法翻译成对应的语言。

/**
* 使用该方法同时请务必要阅读该方法的源码，大致了解该方法的实现。
*
* 如果验签失败则需要返回验签失败的结果，并且需要和配置对应的上，系统才认为是验签成功；
* 
* 如果正确的请求老是误认为验签错误了，则确认以下几点：
* 1编码是否UTF8 
* 2密钥是否写错了，特别是沙箱和线上密钥别搞错
* 3request如果是json,xml类型（form不用理会）则确认inputstream是否被读取过了？如果需要使用body但不想改动麻烦，可以先执行验签，
* 然后在验签结果中获取body（checkResult.getRequestBody()方法）来执行业务逻辑
* 4上层框架是否有做封装导致参数变更
* 如果名以上几点检查没问题，请提供加签前的最终字符串给小二协助排查
*/
CheckResult result = SpiUtils.checkSign(request, targetAppSecret);  //这里执行验签逻辑
if(!result.isSuccess()) {  //如果验签失败则需要返回 验签失败的结果，并且需要和配置对应的上，系统才认为是验签成功
  //按验签失败回应示例
}

三、发送请求

小游戏的后端，可以通过TOP API，调用平台侧提供的业务能力API，比如主动上报直充充值结果。

建议使用淘宝开放平台SDK进行调用，使用该方式，无需关注请求协议、加签等逻辑。

示例代码

/** url为请求的服务地址：
* 正式环境【HTTP请求地址 http://gw.api.taobao.com/router/rest
* HTTPS请求地址 https://eco.taobao.com/router/rest】
* 海外正式环境【HTTP请求地址 http://api.taobao.com/router/rest
* HTTPS请求地址 https://api.taobao.com/router/rest】
**/
TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);

//找到对应类，比如 taobao.trade.fullinfo.get 接口对应的请求类为TradeFullinfoGetRequest

TradeFullinfoGetRequest req = new TradeFullinfoGetRequest();

//设置业务参数

req.setFields("tid,type,status,payment,orders,promotion_details");

req.setTid(123456789L);

// 针对需要用户授权的api，sessionKey为用户授权后获得的accessToken，通常此处为商家授权，目前获得商家授权的方式，可以通过虚拟直充的对接文档查看。 无需用户授权的API，可直接调用。

TradeFullinfoGetResponse rsp = client.execute(req, sessionKey);

System.out.println(rsp.getBody());

四、淘宝开放平台SDK下载

每个小游戏对应的应用方案页面，均提供了SDK下载入口。

每个应用，根据自身拥有的TOP API权限包列表不同，下载的SDK内拥有的API调用代码不同。TOP API的权限，可以通过小游戏应用方案的 权限管理 - 应用服务端 申请需要的权限包，新获得权限以后，需要重新生成SDK，才会有新API的调用代码。

以JAVA版本下载为例。点击“JAVA版本”，可以直接“点击下载”平台默认的JAVA SDK版本；如果您需要下载最新版本的SDK，可以点击“生成”，在跳出的弹框中点击“确定”，系统会生成最新版本的SDK，请耐心等待更新完成，再刷新获取。如下图所示。

注意：生成的SDK不会提示更新完成，一般3-5分钟会生成最新版，需要您手动刷新页面查看。

更新完成后再次点击“JAVA版本”，就能看到最新的SDK，并点击下载。