前置介绍

来自小游戏端发起的网络请求，会通过平台网关转发到外部云服务，网关会自动带上一些开放相关的上下文参数信息，因此针对使用外部云服务的情况，需要进行外部云服务的对接。每个外部云服务，对应可在平台录入外部域名白名单用作游戏内的网络请求，域名录入完成后，会针对对应的外部云服务，生成一个唯一的标识：cloudAppId。详细内容请看：外部云服务对接。

一、外部域名添加

1. 开通云服务

先选择云服务——点击的【云应用套件（推荐）】。

点击后，可进行域名白名单添加。

2. 添加

在小游戏开发 > 开发设置 > 服务器域名白名单>域名白名单 > 添加白名单 > 添加 。   

填入想要申请的域名，如果有多个域名点击添加，最多可以添加20个域名白名单，如果需要20个以上域名需求，请联系运营小二单独申请。

申请理由请填入小游戏域名申请。

注意：填写域名时请不要携带http://部分，否则会提示域名格式不正确。  

点击确定后，创建成功。

注意：域名白名单的有效时间为365天，到期前请使用续期功能，进行续期。

3. 小游戏前端调用外部域名服务端

小游戏前后端通信时，需要使用cloudAppId参数，参数位置如下

调用示例如下：

//game.js文件初始化示例代码
import cloud from '@tbmp/mp-cloud-sdk';

cloud.init({
  //test、online
  env: 'test'
});

----------------------------------
  //调用接口的方法
  async function testCloud() {
    let result
    try {
      result = await cloud.application.httpRequest({
        //不需要完整域名，只需要接口访问路径即可
        'path': '/welcome',
        'method': 'POST',
        //POST请求需要指定下请求格式，只支持application/json。 如："content-type":"application/json;charset=UTF-8"
        'headers': { "Content-Type":"application/json;charset=UTF-8"},
        'params': {"name":"hanruo","action":"test"},
        'body': { "xftest":"hhh",  "id":"1234"},
        'exts': { 
          //cloudAppId为域名白名单配置后获取，在配置处查看具体参数
          "cloudAppId": "xxxx",
          // 单位ms
          "timeout": 4000,
          //调用需要填写该字段，包括协议头以及端口号（可省略），支持http、https
          "domain":"https://www.taobao.com"
        }
      });
    } catch (error) {
      console.log(error)
    }
    console.log("result:", JSON.stringify(result));
  }

----------------------------------
  //执行方法
  testCloud();



==================================
  //如果需要用户授权，服务端获取对应token，则如下调用：
  //执行方法
  my.authorize({
    scopes: 'scope.userInfo', //需要授权的权限包，此处以用户信息权限包为例
    success: (res) => {
      console.log("res:", res);
      testCloud();
    },
    fail(res) {
      console.log("fail:", res);
    }
  });

二、服务端处理前端请求

前端通过cloud.application.httpRequest调用服务端。服务端接收到请求后，可获取除自定义参数外的系统参数。具体参数：云应用调用。

注意：用户自定义的参数不能和系统参数同名，否则会被覆盖掉。

示例

服务端获取到的参数

JAVA为例：

request.getParameterMap()

获取参数如下：

{
    "access_token":[
        "50000800a35OYySsAHauUie7oudnphrweajdphmVUgolwL318fcaedeiwtFKxxxxx"//用户授权 sessionKey
    ],
    "source_app_id":[
        "3000000083xxxx"
    ],
    "app_key":[
        "3427xxxx"
    ],
    "mix_nick":[
        "专01iX1c6xL0GdYGnCEZeOviGFE6pjWHaaOS6xxxxx"//混淆用户昵称
    ],
    "open_id":[
        "AAFDUQQSAOIKi_Utxxxxxxx"  //当前登录用户的openId
    ],
    "mini_app_id":[
        "3000000083xxxx"
    ],
    "sign":[
        "D40C31902FED8D55A181C53xxxxxx"//除sign字段外的所有参数的加签信息，可参考文件验签：https://open.taobao.com/v2/doc#/abilityToOpen?treeId=780&docType=1&docId=118394
    ],
    "env":[
        "test" //当前外部服务的调用环境，入参为：test或者online，对应在云开发中绑定的云容器的测试环境和正式环境。在发布上线前注意调整env为online，调用正式环境。
    ],
    "app_owner_open_id":[
        "AAFDUQQSAOIKi_UtQxxxxx"
    ],
    "request_id":[
        "213e21d716787092743006675e1d16"
    ],
    "source_ip":[
        "42.120.74.xxx"
    ],
    "name":[
        "hanruo"//业务自定义参数
    ],
    "action":[//业务自定义参数
        "test"
    ],
}

三、资源/websocket域名白名单

如果使用了空应用，则已经支持直接访问外部的服务器http接口。

但如果需要访问【外部资源域名或websocket】需要额外申请域名白名单。

目前平台可通过以下路径申请域名白名单：          

其中Request类已不建议接入，其他具体该申请哪类，需要游戏前端同学参考下面具体使用的哪些API，然后服务端或前端同学将使用的api对应的访问域名地址申请域名白名单。

具体请查看：小游戏域名管控。

申请审核流程：联系对应业务对接人去内部后台查询。

四、服务端调用开放API示例

小游戏的后端，可以通过TOP API，调用平台侧提供的业务能力API。操作流程：申请对应权限包后，下载最新SDK，然后编写服务端代码。

下载最新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 接口对应的请求类为TradeFullinfoGetReques
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());

五、服务端实现官方奇门SPI

1）业务方先授权需要实现的奇门SPI，开发者不用感知。

2）进入开发者控制查看需要实现的SPI：

注意此处必须要申请权限的appkey的拥有者才能看到已授权的场景。

3）下载上述SDK。

4）实现对应接口。

根据api文档定义返回结构，并提供接口地址。

奇门需要域名并配置云SLB。