- JS API 列表
- 基础
- 网络
- 媒体
- 地图
- 文件
- 开放接口
- 数据缓存
- 地理位置
- 设备
- 画布
- 界面
- 页面导航
- 侧边栏能力
- 行业开放
- AI/AR能力
- 第三方平台
- TTML
- 转发和挂载
- 其它
- 直播能力
tt.request
收藏我的收藏
基础库 1.0.0 开始支持本方法,这是一个异步方法。
发起 HTTPS 网络请求。网络相关的 API 在使用前需要配置域名白名单。请参考网络请求。
前提条件 | 无 |
业务背景 | 无 |
使用限制 | 线上版本只支持 HTTPS 协议的请求,测试版同时支持 HTTP 和 HTTPS 协议,请注意提审版本中的协议配置; |
注意事项 |
|
支持沙盒 | 否 |
相关教程 | 无 |
语法
tt.request(options)
参数说明
options 为 object 类型,属性如下:
属性名 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
---|---|---|---|---|---|
header | object | 否 | HTTP 请求的 header,详情见 header 说明 | 1.0.0 | |
data | object | arraybuffer | array | 否 | 请求的参数,详情见 data 说明 | 1.0.0 | |
method | string | GET | 否 | 网络请求方法,详情见 method 的合法值 | 1.0.0 |
url | string | 是 | 请求地址 | 1.0.0 | |
timeout | number | 否 | 超时时间,单位为毫秒(最大值 60000ms) | 2.31.0 | |
enableCache | boolean | false | 否 | 开启 cache | 2.31.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 |
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。
data 参数说明
传给服务器的数据最终会是 String 类型,如果 data 不是 String 类型,会被转换成 String。转换规则如下:
- 如果数据类型是 string 或者是 arraybuffer,则直接返回该数据;
- 如果 header['content-type'] 是 application/x-www-form-urlencoded,会将数据转换成 query string: encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...,然后返回该数据;
- 如果 header['content-type'] 是 application/json,则会对数据进行 JSON 序列化,然后返回该数据;
- 如果数据类型是 object,则会对数据进行 JSON 序列化,然后返回该数据;
- 如果是其他情况,则直接调用数据的 toString(), 然后返回该数据。
method 参数说明
值 | 说明 | 最低支持版本 |
OPTIONS | HTTP 请求 OPTIONS | 1.0.0 |
GET | HTTP 请求 GET | 1.0.0 |
HEAD | HTTP 请求 HEAD | 1.0.0 |
POST | HTTP 请求 POST | 1.0.0 |
PUT | HTTP 请求 PUT | 1.0.0 |
DELETE | HTTP 请求 DELETE | 1.0.0 |
TRACE | HTTP 请求 TRACE | 1.0.0 |
CONNECT | HTTP 请求 CONNECT | 1.0.0 |
PATCH | HTTP 请求 PATCH | 2.42.0 |
回调成功
object 类型,属性如下:
属性名 | 类型 | 说明 | 最低支持版本 |
---|---|---|---|
errMsg | string | "request:ok" | 1.0.0 |
statusCode | number | 返回的 HTTP 状态码 | 1.0.0 |
profile | object | 网络请求过程中一些调试信息,详情见 Profile 类型说明 | 2.31.0 |
data | string | object | arraybuffer | 返回的数据,类型取决于 dataType 和 responseType 参数 | 1.0.0 |
profile 类型说明
object 类型,属性如下:
属性名 | 类型 | 说明 | 最低支持版本 |
---|---|---|---|
domainLookupStart | number | DNS 域名查询开始的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 requestStart 值相等 | 2.31.0 |
domainLookupEnd | number | DNS 域名查询完成的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 requestStart 值相等 | 2.31.0 |
connectStart | number | HTTP(TCP) 开始建立连接的时间,如果是持久连接,则与 requestStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接开始的时间 | 2.31.0 |
connectEnd | number | HTTP(TCP) 完成建立连接的时间(完成握手),如果是持久连接,则与 requestStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接完成的时间。注意这里握手结束,包括安全连接建立完成、SOCKS 授权通过 | 2.31.0 |
sslConnectionStart | number | SSL 建立连接的时间,如果不是安全连接,则值为 0 | 2.31.0 |
sslConnectionEnd | number | SSL 建立完成的时间,如果不是安全连接,则值为 0 | 2.31.0 |
requestStart | number | HTTP 请求读取真实文档开始的时间(完成建立连接),包括从本地读取缓存。连接错误重连时,这里显示的也是新建立连接的时间 | 2.31.0 |
requestEnd | number | HTTP 请求读取真实文档结束的时间 | 2.31.0 |
rtt | number | 当次请求连接过程中实时 rtt | 2.31.0 |
estimateNetType | string | 评估的网络状态 unknown, offline, slow 2g, 2g, 3g, 4g, last/0, 1, 2, 3, 4, 5, 6 | 2.31.0 |
throughputKbps | number | 当前网络的实际下载 kbps | 2.31.0 |
port | number | 当前请求的端口 | 2.31.0 |
socketReused | boolean | 是否复用连接 | 2.31.0 |
sentBytesCount | number | 发送的字节数 | 2.31.0 |
receivedBytesCount | number | 收到的字节数 | 2.31.0 |
回调失败
object 类型,属性如下:
属性名 | 类型 | 说明 | 最低支持版本 |
---|---|---|---|
errMsg | string | "request:fail" + 详细错误信息 | 1.0.0 |
返回值
类型 | 说明 | 最低支持版本 |
---|---|---|
object | 1.0.0 |