文档中心 > 店铺动态卡片-开发指引

店铺动态卡片-开发指引

云应用调用

更新时间：2024/08/01 访问次数：64625

一、云应用调用标准

为了对用户的应用提供统一的服务和管理，云应用模式必须要遵循平台提供的标准和限制，才能调用成功。

1.服务返回值

为了对用户的服务进行统计以及提供平台级错误排查能力，用户的http服务必须按照以下格式统一返回，其他字段云网关会自动过滤。

{  
   "success": true, // 布尔值，表示本次调用是否成功
   "data":{}, //调用成功（success为true）时，服务端返回的数据。 不允许返回JS中undefine结果，0，false，"" 等
   "errorCode": "xxxx", //字符串，调用失败（success为false）时，服务端返回的错误码
   "errorMessage": "xxxx" ////字符串，调用失败（success为false）时，服务端返回的错误信息
}

 

2.系统参数标准

为了方便用户获取到当前商家应用的一些上下文数据，云网关会自动将这些数据加到http param中（url后的参数），用户自定义的参数不能和这些参数同名，否则会被覆盖，目前支持的系统参数如下。

注意：区别于无线互动的逻辑。 open_id 等参数，在网络请求时会自动添加到url的参数上。

 

B端应用会存在使用商家子账号授权登录的情况，获取到的userNick为子账号nick。 若需要通过该nick查询主账号nick，可以使用正则表达式匹配。 淘宝子账号的命名规则是 “主账号:xxx” ，冒号前面的为店铺主账号名，冒号后面的值可以由店铺自定义； 例如：店铺主账号nick为 “淘宝官方旗舰店” ，子账号nick就会是 “淘宝官方旗舰店:张三”。

上下文参数

释义

app_key

商家应用的appKey

user_nick

当前登录用户的昵称(需要用户授权)

说明：登录不等于授权，请先获取用户授权

open_id

当前登录用户的openId

env

当前云应用调用环境，入参为：test或者online，对应在云开发中绑定的云容器的测试环境和正式环境。在发布上线前注意调整env为online，调用正式环境。

mini_app_id

运行时使用的小程序ID，1,如果是BC模式，那么这里是B端小程序ID;2,如果是模板开发模式，这里是模板小程序ID;3,如果是插件开发模式，这里是宿主小程序的小程序ID;

access_token

当前登录用户的授权token，也是sessionkey（需要用户授权）

sign

使用当前小程序appkey和secret进行对参数进行加签后的签名

mix_nick

当前登录用户的混淆nick

user_id

当前登录用户的userId，仅对老应用迁移生效

main_user_id

主账号userId，千牛子账号登录授权后可与获取，仅对老应用迁移生效

source_app_id

当前调用小程序的小程序ID1,如果是BC模式，那么这里是C端小程序ID;
2,如果是模板开发模式，这里是实例化小程序ID;
3,如果是插件开发模式，这里是插件的小程序ID;

app_owner_open_id

当前小程序的拥有者的openId，用于BC打通。

对于BC打通场景，在B端，openId是当前登录用户ID，由于是商家使用B端，这里openId即为商家ID；

在C端，小程序拥有者为商家，appOwnerOpenId即为商家Id ;

 

注：sign签名逻辑参考奇门签名方法：点击查看。

 

env参数：为了帮助开发者在新版本开发时，提供的指定环境的功能，这样做代码调试开发而不影响线上云容器的数据。开发者可以在云容器中配置一个测试环境集群和正式环境集群， 把代码和数据通过集群隔离开，然后绑定云应用，测试环境绑定测试环境的SLB，正式环节绑定正式环境的SLB, 就能使用env参数来指定test或者online环境调用了。

 

1) 注意正式发布前env参数要改为正式环境。

2）这里云应用的测试环境和调用API的沙箱测试环境没有关系。

3）如果不需要使用测试环境，在绑定SLB的时候，测试环境和正式环境可以填同一个正式环境的SLB。

 

3.请求方法限制

目前仅支持GET和POST两种请求，POST请求的方式中只支持application/json的格式。

说明：在使用POST请求时，请指定header为application/json格式，否则调用到云端的是application/octet-stream格式，导致调用报错。

二、云应用调用说明

1.前提条件

1）调用API前先确认小程序已绑定云应用，具体绑定方式请参考关联云应用。

2）确保小程序IDE中引入云SDK版本>=1.1.0，建议云SDK始终保持最新版本*。

 

2.调用方法名

cloud.application.httpRequest

3.参数说明

字段名

类型

必选

默认值

说明

path

string

是

-

HTTP接口路径

method

object

否

POST

GET,POST。必须是大写

params

object

否

-

URL参数

body

object

否

 

放置在BODY中的参数

headers

object

否

 

HTTP请求头参数

exts

object

否

 

扩展协议参数。

 

cloudAppId：如果云服务关联了多个云应用，非默认云应用调用须指定

 

timeout：服务调用超时时间，不填默认3000，单位毫秒，最大不超过10000。

 

domain：域名，空应用调用需要填写该字段，包括协议头以及端口号（可省略），支持http、https，例如：https://www.taobao.com。

 

cacheType：服务缓存类型，不填默认不使用缓存，值为数字

缓存类型枚举：

0 ：标准缓存，命中条件为相同小程序+相同用户+相同请求

1：用户无关缓存，命中条件为相同小程序+相同请求

2：小程序无关缓存，命中条件为相同用户+相同请求

3：全局缓存，命中条件为相同的请求

 

cacheTime：缓存失效时间，cacheType不为空的情况下生效，不填默认300，单位为秒，最大不超过3600

 

4.调用说明

1）后端有多个云应用ID，小程序端在调用时若扩展参数中不指定cloudAppId，调用的是默认云应用。且小程序上线后，暂不支持对默认云应用进行修改。

2）云应用调用接口路径无需填写完整域名访问信息，只需要填写接口实际的访问路径。关联了相应聚石塔云应用后，平台在调用时会自行帮您拼接好域名，调到相应云应用的后端服务接口。

假设要调用的HTTP服务为http://aaa.bbb.com/ccc/list， 则云应用调用path为/ccc/list 。

5.调用限制

1）对于请求的内容大小，不能超过128KB(1Mb)。

2）请求URI链接长度过长会被截断。

6.接口返回值示例

{  
   "success": false, // 布尔值，表示本次调用是否成功
   "data":{}, //类型不限，调用成功（success为true）时，服务端返回的数据
   "errorCode": "404", //字符串，调用失败（success为false）时，服务端返回的错误码
   "errorMessage": "接口调用失败" ////字符串，调用失败（success为false）时，服务端返回的错误信息
}

 

云应用在端上调用此接口与在控制台进行服务测试返回的结构不一致。

1）控制台服务测试完全按照平台规范的返回格式进行返回；

2）端上调用接口时，云SDK进行了处理，当success 为true时只返回 data，当success为false时 才会返回errorCode和errorMessage。

7.接口调用环境指定

云应用在小程序端调用时，需要在初始化时，指定要调用的环境。云应用只有测试(test)和正式(online)两套环境，预发环境下调用会自动路由到正式环境。

8.接口调用示例

在MiniApp的入口app.js中初始化sdk, 将cloud实例挂载到App全局对象中, 方便在page中引用。

//app.js文件初始化示例代码
import cloud from '@tbmp/mp-cloud-sdk';
cloud.init({
  //test、online
  env: 'test' 
}); 
App({
  cloud,  
  onLaunch(options) {
     //执行相关代码
  } 
});
----------------------------------
//page调用接口的方法
async httptest (){
  const {cloud} = getApp();
  try {
  const result = await cloud.application.httpRequest({
 //不需要完整域名，只需要接口访问路径即可
  'path' : '/miniapp/test', 
  'method':'POST',
  //POST请求需要指定下请求格式，只支持application/json。 如："content-type":"application/json;charset=UTF-8"
  'headers':{ "Content-Type":"application/json;charset=UTF-8"},
  'params':{  "name":"cx",  "age": 18,  },
  'body':{  "xftest":"hhh",  "id":"1234",  },
 //对于一个小程序关联多个云应用的场景，调用非默认云应用，需要指定对应的云应用Id,超时时间单位ms
  'exts':{  "cloudAppId":"123" ,"timeout":100}  });
   console.log(JSON.stringify(result));
  } catch(e) {
  my.alert({
  content: 'error ' + e.message  
 });  
 } 
}

三、云应用调用日志

开发者可在控制台处查看云应用日志。

FAQ

关于此文档暂时还没有FAQ
有用(0) 我要提问
返回
顶部
阿里巴巴集团 | 淘宝网 | 天猫 | 聚划算 | 全球速卖通 | 阿里巴巴国际交易市场 | 1688 | 阿里妈妈 | 阿里旅行·去啊 | 阿里云计算 | YunOS | 阿里通信 | 万网 | 高德 | 优视 | 友盟 | 酷盘 | 虾米 | 天天动听 | 来往 | 钉钉 | 11Main | 支付宝
关于淘宝 合作伙伴 营销中心 联系客服 开放平台 诚征英才 联系我们 网站地图 法律声明 © 2016 Taobao.com 版权所有
网络文化经营许可证：文网文[2010]040号 | 增值电信业务经营许可证：浙B2-20080224-1 | 信息网络传播视听节目许可证：1109364号