http - HTTP网络请求

老猫2022/10/22大约 10 分钟

Stability: 2 - Stable

http模块提供一些进行http请求的函数。

http.get(url[, options, callback])

url {string} 请求的URL地址，需要以"http://"或"https://"开头。如果url没有以"http://"开头，则默认为"http://"。
options {Object} 请求选项。参见[http.request()][]。
callback {Function} 回调函数，可选，其参数是一个[Response][]对象。如果不加回调函数，则该请求将阻塞、同步地执行。

对地址url进行一次HTTP GET 请求。如果没有回调函数，则在请求完成或失败时返回此次请求的响应(参见[Response][])。

最简单GET请求如下:

console.show();
var r = http.get("www.baidu.com");
log("code = " + r.statusCode);
log("html = " + r.body.string());

采用回调形式的GET请求如下：

console.show();
http.get("www.baidu.com", {}, function (res, err) {
  if (err) {
    console.error(err);
    return;
  }
  log("code = " + res.statusCode);
  log("html = " + res.body.string());
});

如果要增加HTTP头部信息，则在options参数中添加，例如：

console.show();
var r = http.get("www.baidu.com", {
  headers: {
    "Accept-Language": "zh-cn,zh;q=0.5",
    "User-Agent":
      "Mozilla/5.0(Macintosh;IntelMacOSX10_7_0)AppleWebKit/535.11(KHTML,likeGecko)Chrome/17.0.963.56Safari/535.11",
  },
});
log("code = " + r.statusCode);
log("html = " + r.body.string());

一个请求天气并解析返回的天气JSON结果的例子如下：

var city = "广州";
var res = http.get(
  "http://www.sojson.com/open/api/weather/json.shtml?city=" + city,
);
if (res.statusCode != 200) {
  toast("请求失败: " + res.statusCode + " " + res.statusMessage);
} else {
  var weather = res.body.json();
  log(weather);
  toast(
    util.format(
      "温度: %s 湿度: %s 空气质量: %s",
      weather.data.wendu,
      weather.data.shidu,
      weather.quality,
    ),
  );
}

http.post(url, data[, options, callback])

url {string} 请求的URL地址，需要以"http://"或"https://"开头。如果url没有以"http://"开头，则默认为"http://"。
data {string} | {Object} POST数据。
options {Object} 请求选项。
callback {Function} 回调，其参数是一个[Response][]对象。如果不加回调参数，则该请求将阻塞、同步地执行。

对地址url进行一次HTTP POST 请求。如果没有回调函数，则在请求完成或失败时返回此次请求的响应(参见[Response][])。

其中POST数据可以是字符串或键值对。具体含义取决于options.contentType的值。默认为"application/x-www-form-urlencoded"(表单提交), 这种方式是JQuery的ajax函数的默认方式。

一个模拟表单提交登录淘宝的例子如下:

var url = "https://login.taobao.com/member/login.jhtml";
var username = "你的用户名";
var password = "你的密码";
var res = http.post(url, {
  TPL_username: username,
  TPL_password: password,
});
var html = res.body.string();
if (html.contains("页面跳转中")) {
  toast("登录成功");
} else {
  toast("登录失败");
}

http.postJson(url[, data, options, callback])

url {string} 请求的URL地址，需要以"http://"或"https://"开头。如果url没有以"http://"开头，则默认为"http://"。
data {Object} POST数据。
options {Object} 请求选项。
callback {Function} 回调，其参数是一个[Response][]对象。如果不加回调参数，则该请求将阻塞、同步地执行。

以JSON格式向目标Url发起POST请求。如果没有回调函数，则在请求完成或失败时返回此次请求的响应(参见[Response][])。

JSON格式指的是，将会调用JSON.stringify()把data对象转换为JSON字符串，并在HTTP头部信息中把"Content-Type"属性置为"application/json"。这种方式是AngularJS的ajax函数的默认方式。

一个调用图灵机器人接口的例子如下：

var url = "http://www.tuling123.com/openapi/api";
r = http.postJson(url, {
  key: "65458a5df537443b89b31f1c03202a80",
  info: "你好啊",
  userid: "1",
});
toastLog(r.body.string());

http.postMultipart(url, files[, options, callback])

url {string} 请求的URL地址，需要以"http://"或"https://"开头。如果url没有以"http://"开头，则默认为"http://"。
files {Object} POST数据。
options {Object} 请求选项。
callback {Function} 回调，其参数是一个Response对象。如果不加回调参数，则该请求将阻塞、同步地执行。

向目标地址发起类型为multipart/form-data的请求（通常用于文件上传等), 其中files参数是{name1: value1, name2: value2, ...}的键值对，value的格式可以是以下几种情况：

string
文件类型，即open()返回的类型
[fileName, filePath]
[fileName, mimeType, filePath]

其中1属于非文件参数，2、3、4为文件参数。举个例子，最简单的文件上传的请求为：

var res = http.postMultipart(url, {
  file: open("/sdcard/1.txt"),
});
log(res.body.string());

如果使用格式2，则代码为

var res = http.postMultipart(url, {
  file: ["1.txt", "/sdcard/1.txt"],
});
log(res.body.string());

如果使用格式3，则代码为

var res = http.postMultipart(url, {
  file: ["1.txt", "text/plain", "/sdcard/1.txt"],
});
log(res.body.string());

如果使用格式2的同时要附带非文件参数"appId=test"，则为:

var res = http.postMultipart(url, {
  appId: "test",
  file: open("/sdcard/1.txt"),
});
log(res.body.string());

http.request(url[, options, callback])

url {string} 请求的URL地址，需要以"http://"或"https://"开头。如果url没有以"http://"开头，则默认为"http://"。
options {Object} 请求选项。参见[http.buildRequest()][]。
callback {Function} 回调，其参数是一个[Response][]对象。如果不加回调参数，则该请求将阻塞、同步地执行。

对目标地址url发起一次HTTP请求。如果没有回调函数，则在请求完成或失败时返回此次请求的响应(参见[Response][])。

选项options可以包含以下属性：

headers {Object} 键值对形式的HTTP头部信息。有关HTTP头部信息，参见菜鸟教程：HTTP响应头信息。
method {string} HTTP请求方法。包括"GET", "POST", "PUT", "DELETE", "PATCH"。
contentType {string} HTTP头部信息中的"Content-Type", 表示HTTP请求的内容类型。例如"text/plain", "application/json"。更多信息参见菜鸟教程：HTTP contentType。
body {string} | {Array} | {Function} HTTP请求的内容。可以是一个字符串，也可以是一个字节数组；或者是一个以BufferedSink为参数的函数。

该函数是get, post, postJson等函数的基础函数。因此除非是PUT, DELETE等请求，或者需要更高定制的HTTP请求，否则直接使用get, post, postJson等函数会更加方便。

http.buildRequest(url, options)

url {string} 请求的URL地址。
options {Object} 请求选项对象。建议显式传入，至少传入空对象 \{\}。
返回 {Request}

构建一个底层 Request 对象，通常配合 http.client() 或 http.__okhttp__ 的底层调用链使用。

// 推荐：至少传入空 options，避免部分版本下读取 options.headers 报错
let req1 = http.buildRequest("https://example.com", {});
log(req1);

let req2 = http.buildRequest("https://example.com", {
  method: "GET",
  headers: {
    "User-Agent": "AutoJsPro",
  },
});
log(req2);

http.client()

返回 {okhttp3.OkHttpClient}

返回当前 http 模块使用的底层 OkHttpClient 实例。

let client = http.client();
let request = http.buildRequest("https://pro.autojs.run", { method: "GET" });
let response = client.newCall(request).execute();
log(response);

http.okhttp

{com.stardust.autojs.core.http.MutableOkHttp}

http 模块的底层可变 OkHttp 封装对象，用于高级网络配置（如超时、重试次数等）。

提示：这是高级接口，普通脚本优先使用 http.get/post/postJson/postMultipart/request。

http.okhttp.getTimeout()

返回 {long}

获取当前超时设置（毫秒）。

log(http.__okhttp__.getTimeout());

http.okhttp.setTimeout(timeout)

timeout {long} 超时时间（毫秒）

设置当前超时配置。

let oldTimeout = http.__okhttp__.getTimeout();
http.__okhttp__.setTimeout(30000);
log(http.__okhttp__.getTimeout());
http.__okhttp__.setTimeout(oldTimeout); // 建议恢复

http.okhttp.getMaxRetries()

返回 {int}

获取当前最大重试次数。

log(http.__okhttp__.getMaxRetries());

http.okhttp.setMaxRetries(count)

count {int} 最大重试次数

设置最大重试次数。

let oldRetries = http.__okhttp__.getMaxRetries();
http.__okhttp__.setMaxRetries(3);
log(http.__okhttp__.getMaxRetries());
http.__okhttp__.setMaxRetries(oldRetries); // 建议恢复

http.okhttp.client()

返回 {okhttp3.OkHttpClient}

返回底层 OkHttpClient 实例。

let c = http.__okhttp__.client();
log(c);

http.okhttp.connectTimeoutMillis()

返回 {int}

返回连接超时时间（毫秒）。

log(http.__okhttp__.connectTimeoutMillis());

http.okhttp.readTimeoutMillis()

返回 {int}

返回读取超时时间（毫秒）。

log(http.__okhttp__.readTimeoutMillis());

http.okhttp.writeTimeoutMillis()

返回 {int}

返回写入超时时间（毫秒）。

log(http.__okhttp__.writeTimeoutMillis());

http.okhttp.pingIntervalMillis()

返回 {int}

返回 Ping 间隔时间（毫秒）。

log(http.__okhttp__.pingIntervalMillis());

http.okhttp.followRedirects()

返回 {boolean}

返回是否跟随重定向。

log(http.__okhttp__.followRedirects());

http.okhttp.followSslRedirects()

返回 {boolean}

返回是否跟随 HTTPS 重定向。

log(http.__okhttp__.followSslRedirects());

http.okhttp.retryOnConnectionFailure()

返回 {boolean}

返回是否启用连接失败重试。

log(http.__okhttp__.retryOnConnectionFailure());

http.okhttp.newBuilder()

返回 {okhttp3.OkHttpClient.Builder}

返回一个可继续配置的 OkHttp Builder。

let builder = http.__okhttp__.newBuilder();
log(builder);

http.okhttp.newCall(request)

request {okhttp3.Request} 请求对象
返回 {okhttp3.Call}

基于底层客户端创建一个可执行请求调用对象。

let req = http.buildRequest("https://example.com", { method: "GET" });
let call = http.__okhttp__.newCall(req);
log(call);

http.okhttp.newWebSocket(request, listener)

request {okhttp3.Request} WebSocket 请求对象
listener {okhttp3.WebSocketListener} WebSocket 监听器
返回 {okhttp3.WebSocket}

创建 WebSocket 连接对象。

// 仅示意签名，listener 需传入 WebSocketListener 实例
// let ws = http.__okhttp__.newWebSocket(request, listener);

http.okhttp.newClient(builder)

builder {okhttp3.OkHttpClient.Builder} 客户端构建器
返回 {okhttp3.OkHttpClient}

由指定 Builder 创建新的 OkHttpClient 实例。

let builder = http.__okhttp__.newBuilder();
let newClient = http.__okhttp__.newClient(builder);
log(newClient);

http.okhttp.muteClient()

返回 {void}

静默应用当前底层配置到客户端。

http.__okhttp__.muteClient();

http.okhttp.muteClient(builder)

builder {okhttp3.OkHttpClient.Builder}
返回 {void}

将当前底层配置写入指定 Builder。

let builder = http.__okhttp__.newBuilder();
http.__okhttp__.muteClient(builder);

http.okhttp.interceptors()

返回 {java.util.List}

返回拦截器列表。

log(http.__okhttp__.interceptors());

http.okhttp.networkInterceptors()

返回 {java.util.List}

返回网络拦截器列表。

log(http.__okhttp__.networkInterceptors());

http.okhttp.protocols()

返回 {java.util.List}

返回当前启用的协议列表。

log(http.__okhttp__.protocols());

http.okhttp.dispatcher()

返回 {okhttp3.Dispatcher}

返回底层请求调度器对象。

log(http.__okhttp__.dispatcher());

http.okhttp.connectionPool()

返回 {okhttp3.ConnectionPool}

返回连接池对象。

log(http.__okhttp__.connectionPool());

http.okhttp.proxy()

返回 {java.net.Proxy}

返回当前代理配置。

log(http.__okhttp__.proxy());

http.okhttp.proxySelector()

返回 {java.net.ProxySelector}

返回代理选择器。

log(http.__okhttp__.proxySelector());

http.okhttp.proxyAuthenticator()

返回 {okhttp3.Authenticator}

返回代理认证器。

log(http.__okhttp__.proxyAuthenticator());

http.okhttp.authenticator()

返回 {okhttp3.Authenticator}

返回认证器。

log(http.__okhttp__.authenticator());

http.okhttp.dns()

返回 {okhttp3.Dns}

返回 DNS 配置对象。

log(http.__okhttp__.dns());

http.okhttp.cookieJar()

返回 {okhttp3.CookieJar}

返回 Cookie 管理对象。

log(http.__okhttp__.cookieJar());

http.okhttp.cache()

返回 {okhttp3.Cache}

返回缓存对象。

log(http.__okhttp__.cache());

http.okhttp.internalCache()

返回 {okhttp3.internal.cache.InternalCache}

返回内部缓存对象。

log(http.__okhttp__.internalCache());

http.okhttp.hostnameVerifier()

返回 {javax.net.ssl.HostnameVerifier}

返回主机名校验器。

log(http.__okhttp__.hostnameVerifier());

http.okhttp.sslSocketFactory()

返回 {javax.net.ssl.SSLSocketFactory}

返回 SSL Socket 工厂。

log(http.__okhttp__.sslSocketFactory());

http.okhttp.socketFactory()

返回 {javax.net.SocketFactory}

返回 Socket 工厂。

log(http.__okhttp__.socketFactory());

http.okhttp.certificatePinner()

返回 {okhttp3.CertificatePinner}

返回证书固定器配置。

log(http.__okhttp__.certificatePinner());

http.okhttp.eventListenerFactory()

返回 {okhttp3.EventListener.Factory}

返回事件监听器工厂。

log(http.__okhttp__.eventListenerFactory());

http.okhttp.connectionSpecs()

返回 {java.util.List}

返回连接规格列表。

log(http.__okhttp__.connectionSpecs());

http.okhttp 常用属性

http.__okhttp__.timeout {number} 当前超时毫秒值（快捷属性）
http.__okhttp__.maxRetries {number} 当前最大重试次数（快捷属性）
http.__okhttp__.connectTimeout {number} 连接超时毫秒值（快捷属性）
http.__okhttp__.readTimeout {number} 读取超时毫秒值（快捷属性）
http.__okhttp__.writeTimeout {number} 写入超时毫秒值（快捷属性）
http.__okhttp__.pingInterval {number} Ping 间隔毫秒值（快捷属性）
http.__okhttp__.certificateChainCleaner {Object} 证书链清理器对象
http.__okhttp__.class {Object} 当前 Java 类对象

log(http.__okhttp__.timeout, http.__okhttp__.maxRetries);
log(http.__okhttp__.certificateChainCleaner, http.__okhttp__.class);

Response

HTTP请求的响应。

Response.statusCode

{number}

当前响应的HTTP状态码。例如200(OK), 404(Not Found)等。

有关HTTP状态码的信息，参见菜鸟教程：HTTP状态码。

Response.statusMessage

{string}

当前响应的HTTP状态信息。例如"OK", "Bad Request", "Forbidden"。

有关HTTP状态码的信息，参见菜鸟教程：HTTP状态码。

例子：

var res = http.get("www.baidu.com");
if (res.statusCode >= 200 && res.statusCode < 300) {
  toast("页面获取成功!");
} else if (res.statusCode == 404) {
  toast("页面没找到哦...");
} else {
  toast("错误: " + res.statusCode + " " + res.statusMessage);
}

Response.headers

{Object}

当前响应的HTTP头部信息。该对象的键是响应头名称，值是各自的响应头值。所有响应头名称都是小写的(吗)。

有关HTTP头部信息，参见菜鸟教程：HTTP响应头信息。

例子:

console.show();
var res = http.get("www.qq.com");
console.log("HTTP Headers:");
for (var headerName in res.headers) {
  console.log("%s: %s", headerName, res.headers[headerName]);
}

Response.body

{Object}

当前响应的内容。他有以下属性和函数：

bytes() {Array} 以字节数组形式返回响应内容
string() {string} 以字符串形式返回响应内容
json() {Object} 把响应内容作为JSON格式的数据并调用JSON.parse，返回解析后的对象
contentType {string} 当前响应的内容类型

Response.request

{Request} 当前响应所对应的请求。参见[Request][]。

Response.url

{number} 当前响应所对应的请求URL。

Response.method

{string} 当前响应所对应的HTTP请求的方法。例如"GET", "POST", "PUT"等。