开发
API

tt.request

基础库 1.0.0 开始支持本方法,这是一个异步方法。

发起 HTTPS 网络请求。网络相关的 API 在使用前需要配置域名白名单。请参考网络请求

语法

tt.request(options)

参数说明

options 为 object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
urlstring请求地址1.0.0
headerobjectHTTP 请求的 header,详情见 header 说明1.0.0
methodstringGET网络请求方法,详情见 method 的合法值1.0.0
dataobject | array | arraybuffer请求的参数,详情见 data 说明1.0.0
dataTypestringjson期望返回的数据格式,支持 json、string1.0.0
timeoutnumber超时时间,单位为毫秒(最大值 60000ms)2.31.0
enableCachebooleanfalse开启 cache2.31.0
responseTypestringtext期望响应的数据类型,支持 text 或 arraybuffer1.0.0
successfunction接口调用成功后的回调函数1.0.0
failfunction接口调用失败后的回调函数1.0.0
completefunction接口调用结束后的回调函数(调用成功、失败都会执行)1.0.0

header 说明

  • 网络请求 header 中的 referer 不可设置。 其固定格式为:https://tmaservice.developer.toutiao.com?appid={appid}&version={appVersion},其中 appid为小程序的 APPID,appVersion为小程序的版本号。
  • 网络请求 header 中的 user-agent 不可设置。 其固定格式分为:

    • IOS 系统:[系统user-agent] [宿主标识]/[宿主app版本] ToutiaoMicroApp/[基础库版本] webview/[插件版本]
    • Android 系统:[系统user-agent] [宿主标识]/[宿主app版本] ToutiaoMicroApp/[基础库版本] PluginVersion/[插件版本]
  • content-type 默认为 application/json

method 的合法值

说明最低支持版本
OPTIONSHTTP 请求 OPTIONS1.0.0
GETHTTP 请求 GET1.0.0
HEADHTTP 请求 HEAD1.0.0
POSTHTTP 请求 POST1.0.0
PUTHTTP 请求 PUT1.0.0
DELETEHTTP 请求 DELETE1.0.0
TRACEHTTP 请求 TRACE1.0.0
CONNECTHTTP 请求 CONNECT1.0.0
PATCHHTTP 请求 PATCH2.42.0

data 说明

传给服务器的数据最终会是 String 类型,如果 data 不是 String 类型,会被转换成 String。转换规则如下:

  1. 如果数据类型是 string 或者是 arraybuffer,则直接返回该数据;
  2. 如果 header['content-type']application/x-www-form-urlencoded,会将数据转换成 query string: encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...,然后返回该数据;
  3. 如果 header['content-type']application/json,则会对数据进行 JSON 序列化,然后返回该数据;
  4. 如果数据类型是 object,则会对数据进行 JSON 序列化,然后返回该数据;
  5. 如果是其他情况,则直接调用数据的 toString(), 然后返回该数据。

返回值

RequestTask

回调成功

object 类型,属性如下:

属性名类型说明最低支持版本
statusCodenumber返回的 HTTP 状态码1.0.0
headerobject返回的 HTTP Response Header1.0.0
dataobject | string | arraybuffer返回的数据,类型取决于 dataType 和 responseType 参数1.0.0
profileProfile网络请求过程中一些调试信息,详情见 Profile 类型说明2.31.0

Profile 类型说明

object 类型,属性如下:

属性名类型说明最低支持版本
domainLookupStartnumberDNS 域名查询开始的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等2.31.0
domainLookupEndnumberDNS 域名查询完成的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等2.31.0
connectStartnumberHTTP(TCP) 开始建立连接的时间,如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接开始的时间2.31.0
connectEndnumberHTTP(TCP) 完成建立连接的时间(完成握手),如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接完成的时间。注意这里握手结束,包括安全连接建立完成、SOCKS 授权通过2.31.0
sslConnectionStartnumberSSL 建立连接的时间,如果不是安全连接,则值为 02.31.0
sslConnectionEndnumberSSL 建立完成的时间,如果不是安全连接,则值为 02.31.0
requestStartnumberHTTP 请求读取真实文档开始的时间(完成建立连接),包括从本地读取缓存。连接错误重连时,这里显示的也是新建立连接的时间2.31.0
requestEndnumberHTTP 请求读取真实文档结束的时间2.31.0
rttnumber当次请求连接过程中实时 rtt2.31.0
estimateNetTypestring评估的网络状态 unknown, offline, slow 2g, 2g, 3g, 4g, last/0, 1, 2, 3, 4, 5, 62.31.0
throughputKbpsnumber当前网络的实际下载 kbps2.31.0
portnumber当前请求的端口2.31.0
socketReusedboolean是否复用连接2.31.0
sentBytesCountnumber发送的字节数2.31.0
receivedBytesCountnumber收到的字节数2.31.0

回调失败

object 类型,属性如下:

属性名类型说明最低支持版本
errMsgstring错误信息1.0.0
errNostring错误码1.0.0
profileProfile网络请求过程中一些调试信息(失败时可能不存在)2.31.0

扫码体验

请使用字节宿主APP扫码

代码示例

开发者工具中预览

【示例 1】:post 请求返回 dataType 为 json 类型的数据,并且可能会中断请求。

let task = tt.request({
  url:
    "https://microapp.bytedance.com/miniprogram-demo/invoke/tma_demo_request/",
  data: {
    name: "bytedance",
  },
  header: {
    "content-type": "application/json",
  },
  method: "POST",
  dataType: "json", // 指定返回数据的类型为 json
  responseType: "text",
  success(res) {
    console.log("调用成功", res.data);
  },
  fail(res) {
    console.log("调用失败", res.errMsg);
  },
});

// 当调用 abort() 时会主动中断请求
task.abort();

【示例 2】:post 请求返回 dataTypestring 类型的数据。

tt.request({
  url:
    "https://microapp.bytedance.com/miniprogram-demo/invoke/tma_demo_request/",
  data: {
    name: "bytedance",
  },
  header: {
    "content-type": "application/json",
  },
  method: "POST",
  dataType: "string", // 指定返回数据的类型为 string
  responseType: "text",
  success(res) {
    console.log("调用成功", res.data);
  },
  fail(res) {
    console.log("调用失败", res.errMsg);
  },
});

【示例 3】:post 请求返回 responseTypearraybuffer 类型的数据。

tt.request({
  url:
    "https://microapp.bytedance.com/miniprogram-demo/invoke/tma_demo_request/",
  data: {
    name: "bytedance",
  },
  header: {
    "content-type": "application/json",
  },
  method: "POST",
  dataType: "string", // 在 responseType 为arraybuffer的情况下,不起作用
  responseType: "arraybuffer", // 指定返回数据的类型为 arraybuffer
  success(res) {
    // 此处返回的res.data类型为 arraybuffer
    console.log("调用成功", res.data);
  },
  fail(res) {
    console.log("调用失败", res.errMsg);
  },
});

【示例 4】:post 请求 header['content-type']application/x-www-form-urlencoded

tt.request({
  url:
    "https://microapp.bytedance.com/miniprogram-demo/invoke/tma_demo_request/",
  data: {
    name: "bytedance",
  },
  header: {
    "content-type": "application/x-www-form-urlencoded", // 此处指定content-type类型,请确保传入的data 中的 key 和 value 都必须是string。
  },
  method: "POST",
  dataType: "json",
  responseType: "text",
  success(res) {
    console.log("调用成功", res.data);
  },
  fail(res) {
    console.log("调用失败", res.errMsg);
  },
});

【示例 5】:post 请求携带 cookie。

const id = "test";
tt.request({
  url:
    "https://microapp.bytedance.com/miniprogram-demo/invoke/tma_demo_request/",
  data: {
    name: "bytedance",
  },
  header: {
    "content-type": "application/json",
    cookie: "BYTEDANCEID" + id, // 此处添加cookie
  },
  method: "POST",
  dataType: "json",
  responseType: "text",
  success(res) {
    console.log("调用成功", res.data);
  },
  fail(res) {
    console.log("调用失败", res.errMsg);
  },
});

【示例 6】:put 请求。

tt.request({
  url:
    "https://microapp.bytedance.com/miniprogram-demo/invoke/tma_demo_request/",
  data: {
    name: "bytedance",
  },
  header: {
    "content-type": "application/json",
  },
  method: "PUT", // 此处修改请求方法
  dataType: "json",
  responseType: "text",
  success(res) {
    console.log("调用成功", res.data);
  },
  fail(res) {
    console.log("调用失败", res.errMsg);
  },
});

【示例 7】:timeout 使用。

tt.request({
  url:
    "https://microapp.bytedance.com/miniprogram-demo/invoke/tma_demo_request/",
  data: {
    name: "bytedance",
  },
  header: {
    "content-type": "application/json",
  },
  timeout: 2000, // 设置超时时间为2s
  method: "get",
  dataType: "json",
  responseType: "text",
  success(res) {
    console.log("调用成功", res.data);
  },
  fail(res) {
    console.log("调用失败", res.errMsg);
  },
});

Bug & Tip

  • Tip:网络请求超时最大时长为 60s;
  • Tip:IDE 暂不支持 profile 字段;
  • Tip:header 不支持设置 refereruser-agent 字段;
  • Tip:线上版本只支持 HTTPS 协议的请求,测试版同时支持 HTTP 和 HTTPS 协议,请注意提审版本中的协议配置;
  • Tip:在 header['content-type']application/x-www-form-urlencoded的情况下,请确保传入的 data 中,key 和 value 都是 string,否则容易出现解析不出来数据的问题。
点击纠错
该文档是否对你的开发有所帮助?
有帮助
没帮助
该文档是否对你的开发有所帮助?
有帮助
没帮助