普通小游戏开发
开放能力(必读)
社交转发裂变
数据分析
视频拍摄器
API
多端支持
自2022年9月6日起,本文档站不再更新内容,相关文档已迁移至全新“抖音开放平台”前往

tt.request

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

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

语法

tt.request(options);

参数说明

options 为 Object 类型,属性如下:

属性名

类型

默认值

必填

说明

最低支持版本

url

string

--

请求地址

1.0.0

header

object

{"content-type": "application/json"}

请求 Header

1.0.0

method

string

GET

网络请求方法,支持 GET/POST/OPTIONS/PUT/HEAD/DELETE

1.0.0

data

object/array/arraybuffer

--

请求的参数

1.0.0

dataType

string

json

期望返回的数据类型,支持 json、string

1.0.0

responseType

string

text

期望响应的数据类型,支持 text 或 arraybuffer

1.0.0

success

function

--

接口调用成功后的回调函数

1.0.0

fail

function

--

接口调用失败后的回调函数

1.0.0

complete

function

--

接口调用结束后的回调函数(调用成功、失败都会执行)

1.0.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(), 然后返回该数据。

referer 说明

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

user-agent 说明

网络请求 header 中的 user-agent 不可设置。 其固定格式分为:

  • IOS 系统:[系统user-agent] [宿主标识]/[宿主app版本] ToutiaoMicroApp/[基础库版本] webview/[插件版本]
  • Android 系统:[系统user-agent] [宿主标识]/[宿主app版本] ToutiaoMicroApp/[基础库版本] PluginVersion/[插件版本]

回调成功

参数为 Object 类型,属性如下:

参数

参数类型

说明

最低支持版本

statusCode

number

返回的 HTTP 状态码

1.0.0

header

object

返回的 HTTP Response Header

1.0.0

data

object/string/arraybuffer

返回的数据,类型取决于 dataType 和 responseType 参数

1.0.0

回调失败

参数为 Object 类型,属性如下:

参数

参数类型

说明

最低支持版本

errMsg

string

错误信息

1.0.0

返回值

RequestTask(网络请求任务对象),调用 tt.request 后返回的请求对象。

扫码体验

请使用字节宿主APP扫码

代码示例

开发者工具中预览

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

let task = tt.request({
  url: "someurl",
  data: {
    user_name: "hello",
  },
  header: {
    "content-type": "application/json",
  },
  method: "POST",
  dataType: "JSON", // 指定返回数据的类型为 json
  responseType: "text",
  success(res) {
    console.log("调用成功", res.data);
  },
  fail(res) {
    console.log("调用失败", res.errMsg);
  },
});

// 某些条件下中断请求
if (someReason) {
  task.abort();
}

【代码示例 2】:post 请求返回 dataType 为 string 类型的数据。

tt.request({
  url: "someurl",
  data: {
    user_name: "hello",
  },
  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 请求返回 responseType 为 arraybuffer 类型的数据。

tt.request({
  url: "someurl",
  data: {
    user_name: "hello",
  },
  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: "someurl",
  data: {
    user_name: "hello",
  },
  header: {
    "content-type": "application/x-www-form-urlencoded", // 此处指定content-type类型
  },
  method: "POST",
  dataType: "json",
  responseType: "text",
  success(res) {
    console.log("调用成功", res.data);
  },
  fail(res) {
    console.log("调用失败", res.errMsg);
  },
});

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

const id = "";
tt.request({
  url: "someurl",
  data: {
    user_name: "hello",
  },
  header: {
    "content-type": "application/json",
    cookie: "TOUTIAOID" + 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: "someurl",
  data: {
    user_name: "hello",
  },
  header: {
    "content-type": "application/json",
  },
  method: "PUT", // 此处修改请求方法
  dataType: "json",
  responseType: "text",
  success(res) {
    console.log("调用成功", res.data);
  },
  fail(res) {
    console.log("调用失败", res.errMsg);
  },
});

Bug & Tip

  • Tip:header 不支持设置 refereruser-agent 字段。
  • Tip:tt.request 目前只支持 HTTPS 协议的请求 。
点击纠错
该文档是否对你的开发有所帮助?
有帮助
没帮助
该文档是否对你的开发有所帮助?
有帮助
没帮助