小程序中网络请求相关的api总结

简介:

小程序中网络相关的API

网络API列表:

API 说明
wx.request 发起网络请求
wx.uploadFile 上传文件
wx.downloadFile 下载文件
wx.connectSocket 创建 WebSocket 连接
wx.onSocketOpen 监听 WebSocket 打开
wx.onSocketError 监听 WebSocket 错误
wx.sendSocketMessage 发送 WebSocket 消息
wx.onSocketMessage 接受 WebSocket 消息
wx.closeSocket 关闭 WebSocket 连接
wx.onSocketClose 监听 WebSocket 关闭

在小程序中使用网络相关的 API 时,需要注意下列问题,请开发者提前了解

服务器域名配置

每个微信小程序需要事先设置一个通讯域名,小程序可以跟指定的域名进行网络通信。包括普通 HTTPS 请求(request)、上传文件(uploadFile)、下载文件(downloadFile) 和 WebSocket 通信(connectSocket)

配置流程

服务器域名请在"小程序后台-设置-开发设置-服务器域名" 中进行配置,配置时需要注意:

1.域名只支持 https (request、uploadFile、downloadFile) 和 wss (connectSocket) 协议;

2.域名不能使用 IP 地址或 localhost

3.域名必须经过 ICP 备案;

4.出于安全考虑,api.weixin.qq.com 不能被配置为服务器域名,相关API也不能在小程序内调用。开发者应将 appsecret 保存到后台服务器中,通过服务器使用 appsecret 获取 accesstoken,并调用相关 API。

5.对于每个接口,分别可以配置最多 20 个域名

HTTPS 证书

小程序必须使用HTTPS请求。小程序内会对服务器域名使用的HTTPS证书进行校验,如果校验失败,则请求不能成功发起。由于系统限制,不同平台对于证书要求的严格程度不同。为了保证小程序的兼容性,建议开发者按照最高标准进行证书配置,并使用相关工具检查现有证书是否符合要求

对证书要求如下:

1.HTTPS 证书必须有效。证书必须被系统信任,部署SSL证书的网站域名必须与证书颁发的域名一致,证书必须在有效期内;

2.iOS 不支持自签名证书;

3.iOS 下证书必须满足苹果 App Transport Security (ATS) 的要求;

4.TLS 必须支持 1.2 及以上版本。部分旧 Android 机型还未支持 TLS 1.2,请确保 HTTPS 服务器的 TLS 版本支持1.2及以下版本;

5.部分 CA 可能不被操作系统信任,请开发者在选择证书时注意小程序和各系统的相关通告。

6.Chrome 56/57 内核对 WoSign、StartCom 证书限制周知:Android X5内核计划将于8月份开始升级到Chrome 57内核(目前 Chrome 53),升级到 Chrome 57 内核后,会对 WoSign CA Free SSL/StartCom 证书进行部分限制。对于小程序来说,如果储存图片资源的服务器使用了上述证书,将会影响图片的正常加载。预计 Chrome 以后版本会再加大对 WoSign CA Free SSL/StartCom 证书限制,我们建议开发者提前更换其它可信证书。

Chrome 56/57 版本对 WoSign CA Free SSL/StartCom 证书限制措施如下:

1).Chrome 56 开始停止信任 2016 年 10 月 21 日后签发的 WoSign CA Free SSL/StartCom 证书;

2).Chrome 57 进一步扩大限制范围,Alexa 排名一百万外的网站都不能使用 WoSign CA Free SSL/StartCom 证书,无论证书何时签发。

附:如何检测网站是否使用了 WoSign/StartCom

1).使用最新版本的 Chrome 打开图片链接,右键 -> 检查,切换到「Security」页卡,点击「View certificate」;

2).检查证书的签发机构是否在限制范围内。

跳过域名校验

在微信开发者工具中,可以临时开启 开发环境不校验请求域名、TLS版本及HTTPS证书 选项,跳过服务器域名的校验。此时,在微信开发者工具中及手机开启调试模式时,不会进行服务器域名的校验

在服务器域名配置成功后,建议开发者关闭此选项进行开发,并在各平台下进行测试,以确认服务器域名配置正确。

如果手机上出现 “打开调试模式可以发出请求,关闭调试模式无法发出请求” 的现象,请确认是否跳过了域名校验,并确认服务器域名和证书配置是否正确

关于请求

1.默认超时时间和最大超时时间都是 60s

2.request、uploadFile、downloadFile 的最大并发限制是 10 个

3.网络请求的 referer header 不可设置。其格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中 {appid} 为小程序的 appid,{version} 为小程序的版本号,版本号为 0 表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本。

4.小程序进入后台运行后(非置顶聊天),如果 5s 内网络请求没有结束,会回调错误信息 fail interrupted;在回到前台之前,网络请求接口调用都会无法调用

关于服务器返回

返回值编码

1.建议服务器返回值使用 UTF-8 编码。对于非 UTF-8 编码,小程序会尝试进行转换,但是会有转换失败的可能。

2.小程序会自动对 BOM 头进行过滤。

回调

只要成功接收到服务器返回,无论statusCode是多少,都会进入success回调。请开发者根据业务逻辑对返回值进行判断

wx.request(OBJECT)

发起网络请求

OBJECT参数说明:

参数名 类型 必填 默认值 说明 最低版本
url String 开发者服务器接口地址
data Object/String/ArrayBuffer 请求的参数
header Object 设置请求的 header,header 中不能设置 Referer
method String GET (需大写)有效值:OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT
dataType String json 如果设为json,会尝试对返回的数据做一次 JSON.parse
responseType String text 设置响应的数据类型。合法值:text、arraybuffer 1.7.0
success Function 收到开发者服务成功返回的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明 最低版本
data Object/String/ArrayBuffer 开发者服务器返回的数据
statusCode Number 开发者服务器返回的 HTTP 状态码
header Object 开发者服务器返回的 HTTP Response Header 1.2.0

data 数据说明:

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

1.对于 GET 方法的数据,会将数据转换成 query string(encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...)

2.对于 POST 方法且 header['content-type'] 为 application/json 的数据,会对数据进行 JSON 序列化

3.对于 POST 方法且 header['content-type'] 为 application/x-www-form-urlencoded 的数据,会将数据转换成 query string (encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...)

wx.request({
  url: 'test.php', //仅为示例,并非真实的接口地址
  data: {
     x: '' ,
     y: ''
  },
  header: {
    'content-type': 'application/json' // 默认值
  },
  success: function(res) {
    console.log(res.data)
  }
})

返回值:

返回一个 requestTask 对象,通过 requestTask,可中断请求任务; 基础库 1.4.0 开始支持,低版本需做兼容处理

requestTask 对象的方法列表:

方法 参数 说明 最低版本
abort 中断请求任务 1.4.0
const requestTask = wx.request({
  url: 'test.php', //仅为示例,并非真实的接口地址
  data: {
     x: '' ,
     y: ''
  },
  header: {
    'content-type': 'application/json'
  },
  success: function(res) {
    console.log(res.data)
  }
})
requestTask.abort() // 取消请求任务

Bug & Tip

1.tip: content-type 默认为 'application/json';

2.bug: 开发者工具 0.10.102800 版本,header 的 content-type 设置异常;

上传 下载

wx.uploadFile(OBJECT)

将本地资源上传到开发者服务器,客户端发起一个 HTTPS POST 请求,其中 content-type 为 multipart/form-data 。使用前请先阅读说明。

如页面通过 wx.chooseImage 等接口获取到一个本地资源的临时文件路径后,可通过此接口将本地资源上传到指定服务器

OBJECT参数说明:

参数名 类型 必填 说明
url String 开发者服务器 url
filePath String 要上传文件资源的路径
name String 文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容
header Object HTTP 请求 Header, header 中不能设置 Referer
formData Object HTTP 请求中其他额外的 form data
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数名 类型 说明
data String 开发者服务器返回的数据
statusCode Number 开发者服务器返回的 HTTP 状态码
wx.chooseImage({
  success: function(res) {
    var tempFilePaths = res.tempFilePaths
    wx.uploadFile({
      url: 'https://example.weixin.qq.com/upload', //仅为示例,非真实的接口地址
      filePath: tempFilePaths[0],
      name: 'file',
      formData:{
        'user': 'test'
      },
      success: function(res){
        var data = res.data
        //do something
      }
    })
  }
})

返回值:

返回一个 uploadTask 对象,通过 uploadTask,可监听上传进度变化事件,以及取消上传任务; 基础库 1.4.0 开始支持,低版本需做兼容处理

uploadTask

uploadTask 对象的方法列表:

方法 参数 说明 最低版本
onProgressUpdate callback 监听上传进度变化 1.4.0
abort 中断上传任务 1.4.0

onProgressUpdate 返回参数说明:

参数名 类型 说明
progress Number 上传进度百分比
totalBytesSent Number 已经上传的数据长度,单位 Bytes
totalBytesExpectedToSend Number 预期需要上传的数据总长度,单位 Bytes
const uploadTask = wx.uploadFile({
    url: 'http://example.weixin.qq.com/upload', //仅为示例,非真实的接口地址
    filePath: tempFilePaths[0],
    name: 'file',
    formData:{
        'user': 'test'
    },
    success: function(res){
        var data = res.data
        //do something
    }
})
uploadTask.onProgressUpdate((res) => {
    console.log('上传进度', res.progress)
    console.log('已经上传的数据长度', res.totalBytesSent)
    console.log('预期需要上传的数据总长度', res.totalBytesExpectedToSend)
})
uploadTask.abort() // 取消上传任务

wx.downloadFile(OBJECT)

下载文件资源到本地,客户端直接发起一个 HTTP GET 请求,返回文件的本地临时路径

OBJECT参数说明:

参数名 类型 必填 说明
url String 下载资源的 url
header Object HTTP 请求 Header, header 中不能设置 Referer
success Function 下载成功后以 tempFilePath 的形式传给页面,res = {tempFilePath: '文件的临时路径'}
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

注:文件的临时路径,在小程序本次启动期间可以正常使用,如需持久保存,需在主动调用 wx.saveFile,才能在小程序下次启动时访问得到。 注:请在 header 中指定合理的 Content-Type 字段,以保证客户端正确处理文件类型

success返回参数说明:

参数名 类型 说明
tempFilePath String 临时文件路径,下载后的文件会存储到一个临时文件
statusCode Number 开发者服务器返回的 HTTP 状态码
wx.downloadFile({
  url: 'https://example.com/audio/123', //仅为示例,并非真实的资源
  success: function(res) {
    // 只要服务器有响应数据,就会把响应内容写入文件并进入 success 回调,业务需要自行判断是否下载到了想要的内容
    if (res.statusCode === 200) {
        wx.playVoice({
          filePath: res.tempFilePath
        })
    }
  }
})

返回值:返回一个 downloadTask 对象,通过 downloadTask,可监听下载进度变化事件,以及取消下载任务

基础库 1.4.0 开始支持,低版本需做兼容处理

downloadTask

downloadTask 对象的方法列表:

方法 参数 说明 最低版本
onProgressUpdate callback 监听下载进度变化 1.4.0
abort 中断下载任务 1.4.0

onProgressUpdate 返回参数说明:

参数名 类型 说明
progress Number 下载进度百分比
totalBytesWritten Number 已经下载的数据长度,单位 Bytes
totalBytesExpectedToWrite Number 预期需要下载的数据总长度,单位 Bytes
const downloadTask = wx.downloadFile({
    url: 'http://example.com/audio/123', //仅为示例,并非真实的资源
    success: function(res) {
        wx.playVoice({
            filePath: res.tempFilePath
        })
    }
})
downloadTask.onProgressUpdate((res) => {
    console.log('下载进度', res.progress)
    console.log('已经下载的数据长度', res.totalBytesWritten)
    console.log('预期需要下载的数据总长度', res.totalBytesExpectedToWrite)
})
downloadTask.abort() // 取消下载任务

tip: 6.5.3 以及之前版本的 iOS 微信客户端 header 设置无效

WebSocket

wx.connectSocket(OBJECT)

创建一个 WebSocket 连接。基础库 1.7.0 之前,一个微信小程序同时只能有一个 WebSocket 连接,如果当前已存在一个 WebSocket 连接,会自动关闭该连接,并重新创建一个 WebSocket 连接。基础库版本 1.7.0 及以后,支持存在多个 WebSokcet 连接,每次成功调用 wx.connectSocket 会返回一个新的 SocketTask

OBJECT参数说明:

参数名 类型 必填 说明 最低版本
url String 开发者服务器接口地址,必须是 wss 协议,且域名必须是后台配置的合法域名
header Object HTTP 请求 Header, header 中不能设置 Referer
protocols StringArray 子协议数组 1.4.0
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)
wx.connectSocket({
  url: 'wss://example.qq.com',
  data:{
    x: '',
    y: ''
  },
  header:{ 
    'content-type': 'application/json'
  },
  protocols: ['protocol1'],
  method:"GET"
})

wx.onSocketOpen(CALLBACK)

监听WebSocket连接打开事件

callback 回调函数

res

属性 类型 说明 最低版本
header object 连接成功的 HTTP 响应 Header 2.0.0
wx.connectSocket({
  url: 'test.php'
})
wx.onSocketOpen(function(res) {
  console.log('WebSocket连接已打开!')
})

wx.onSocketError(CALLBACK)

监听WebSocket错误

wx.connectSocket({
  url: 'test.php'
})
wx.onSocketOpen(function(res){
  console.log('WebSocket连接已打开!')
})
wx.onSocketError(function(res){
  console.log('WebSocket连接打开失败,请检查!')
})

wx.sendSocketMessage(OBJECT)

通过 WebSocket 连接发送数据,需要先 wx.connectSocket,并在 wx.onSocketOpen 回调之后才能发送

OBJECT参数说明:

参数名 类型 必填 说明
data String/ArrayBuffer 需要发送的内容
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)
var socketOpen = false
var socketMsgQueue = []
wx.connectSocket({
  url: 'test.php'
})
wx.onSocketOpen(function(res) {
  socketOpen = true
  for (var i = 0; i < socketMsgQueue.length; i++){
     sendSocketMessage(socketMsgQueue[i])
  }
  socketMsgQueue = []
})
function sendSocketMessage(msg) {
  if (socketOpen) {
    wx.sendSocketMessage({
      data:msg
    })
  } else {
     socketMsgQueue.push(msg)
  }
}

wx.onSocketMessage(CALLBACK)

监听WebSocket接受到服务器的消息事件

callback 回调参数

参数 类型 说明
data String/ArrayBuffer 服务器返回的消息
wx.connectSocket({
  url: 'test.php'
})
wx.onSocketMessage(function(res) {
  console.log('收到服务器内容:' + res.data)
})

wx.closeSocket(OBJECT)

关闭 WebSocket 连接

OBJECT参数说明:

参数名 类型 必填 说明 最低版本
code Number 一个数字值表示关闭连接的状态号,表示连接被关闭的原因。如果这个参数没有被指定,默认的取值是1000 (表示正常连接关闭) 1.4.0
reason String 一个可读的字符串,表示连接被关闭的原因。这个字符串必须是不长于123字节的UTF-8 文本(不是字符) 1.4.0
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

wx.onSocketClose(CALLBACK)

监听WebSocket关闭

wx.connectSocket({
  url: 'test.php'
})
//注意这里有时序问题,如果 wx.connectSocket 还没回调 wx.onSocketOpen,而先调用 wx.closeSocket,那么就做不到关闭 WebSocket 的目的。必须在 WebSocket 打开期间调用 wx.closeSocket 才能关闭。
wx.onSocketOpen(function() {
  wx.closeSocket()
})
wx.onSocketClose(function(res) {
  console.log('WebSocket 已关闭!')
})

返回值:

返回一个 SocketTask;基础库 1.7.0 开始支持,低版本需做兼容处理

tip: 基础库 1.7.0 开始,支持同时存在 2 条 WebSocket 连接

目录
相关文章
|
2月前
|
存储 网络协议 API
Cpp网络编程Winsock API
本文详细介绍了使用Winsock API进行C++网络编程的过程,通过具体实例实现了一个基于TCP协议的C/S架构通信demo。文章从服务端与客户端两方面展开,涵盖网络库初始化、套接字创建、绑定IP与端口、监听与连接、数据收发到关闭连接等关键步骤。重点解析了`WSAStartup`、`socket`、`bind`、`listen`、`accept`、`connect`、`send`和`recv`等函数的使用方法及注意事项,并对比了标准库与Winsock库在链接时的区别。适合初学者了解Winsock网络编程基础。
150 35
|
2月前
|
人工智能 运维 安全
网络安全公司推荐:F5荣膺IDC全球Web应用与API防护领导者
网络安全公司推荐:F5荣膺IDC全球Web应用与API防护领导者
70 4
|
4月前
|
缓存 小程序 API
微信小程序网络请求与API调用:实现数据交互
本文深入探讨了微信小程序的网络请求与API调用,涵盖`wx.request`的基本用法、常见场景(如获取数据、提交表单、上传和下载文件)及注意事项(如域名配置、HTTPS协议、超时设置和并发限制)。通过一个简单案例,演示了如何实现小程序与服务器的数据交互。掌握这些技能将帮助你构建功能更丰富的应用。
|
6月前
|
Kubernetes 安全 Devops
有效抵御网络应用及API威胁,聊聊F5 BIG-IP Next Web应用防火墙
有效抵御网络应用及API威胁,聊聊F5 BIG-IP Next Web应用防火墙
190 10
有效抵御网络应用及API威胁,聊聊F5 BIG-IP Next Web应用防火墙
|
7月前
|
存储 数据可视化 API
重磅干货,免费三方网络验证[用户系统+CDK]全套API接口分享教程。
本套网络验证系统提供全面的API接口,支持用户注册、登录、数据查询与修改、留言板管理等功能,适用于不想自建用户系统的APP开发者。系统还包含CDK管理功能,如生成、使用、查询和删除CDK等。支持高自定义性,包括20个自定义字段,满足不同需求。详细接口参数及示例请参考官方文档。
|
7月前
|
监控 小程序 安全
小程序的 API 做了什么处理,能够做到全局变量的隐藏
【10月更文挑战第23天】小程序的 API 通过运行环境隔离、作用域限制、数据绑定机制、事件机制、状态管理、代码封装和模块化、安全策略和权限控制以及运行时监控和检测等多种手段来实现全局变量的隐藏。这些措施共同作用,确保了小程序的安全、稳定和可靠运行,同时也提高了开发效率和代码质量。
107 10
|
8月前
|
存储 搜索推荐 生物认证
信息搜集:网络空间搜索引擎语法及API的应用(一)
信息搜集:网络空间搜索引擎语法及API的应用(一)
147 0
|
8月前
|
JSON 搜索推荐 IDE
信息搜集:网络空间搜索引擎语法及API的应用(二)
信息搜集:网络空间搜索引擎语法及API的应用(二)
107 0
|
6月前
|
SQL 安全 网络安全
网络安全与信息安全:知识分享####
【10月更文挑战第21天】 随着数字化时代的快速发展,网络安全和信息安全已成为个人和企业不可忽视的关键问题。本文将探讨网络安全漏洞、加密技术以及安全意识的重要性,并提供一些实用的建议,帮助读者提高自身的网络安全防护能力。 ####
164 17
|
6月前
|
SQL 安全 网络安全
网络安全与信息安全:关于网络安全漏洞、加密技术、安全意识等方面的知识分享
随着互联网的普及,网络安全问题日益突出。本文将从网络安全漏洞、加密技术和安全意识三个方面进行探讨,旨在提高读者对网络安全的认识和防范能力。通过分析常见的网络安全漏洞,介绍加密技术的基本原理和应用,以及强调安全意识的重要性,帮助读者更好地保护自己的网络信息安全。
124 10