my.request

小程序网络请求。

  • my.request 目前支持 GET/POST/DELETE

  • my.request 目前只支持 HTTPS 协议的请求。

说明
  • 基础库 1.11.0 及以上版本支持该接口可以使用 my.canIUse('request') 做兼容性处理。详见 小程序基础库说明

  • mPaaS 10.1.60 及以上版本支持该接口。

  • 接口 my.httpRequest 将被废弃,请使用 my.request 来代替。

  • my.request 的请求头默认值为 {'content-type': 'application/json'},而不是 {'content-type': 'application/x-www-form-urlencoded'}。此外,请求头对象里面的 key 和 value 必须是 String 类型。

更多问题请参见 my.request 常见问题

使用说明

  • 需预先在 小程序发布 > 开放平台小程序管理 中打开 小程序权限控制开关,并在 服务器域名白名单 中配置域名白名单。小程序在以下 API 调用时只能与白名单中的域名进行通讯:HTTP 请求(my.request)、上传文件(my.uploadFile)。

  • 添加服务器域名白名单后,需要重新打包上传生成体验版,服务器域名才会生效。

  • 在 IDE 上进行调试时,请使用真机预览调试。

入参

名称

类型

必填

描述

url

String

目标服务器 url

headers

Object

设置请求的 HTTP 头,默认为 {'content-type': 'application/json'},该对象中的 key 和 value 必须是 String 类型。

method

String

默认为 GET,目前支持 GET/POST/DELETE。

data

Object / ArrayBuffer

参考下文 data 参数说明。

timeout

Number

超时时间,单位为 ms,默认为 30000

dataType

String

期望返回的数据格式,默认为 json,支持 json、text、base64 和 arraybuffer。

success

Function

调用成功的回调函数

fail

Function

调用失败的回调函数

complete

Function

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

data 参数说明

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

  • 若方法为GET,会将数据转换成 query string: encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...

  • 若方法为 POSTheaders['content-type']application/json ,会对数据进行 JSON 序列化。

  • 若方法为 POSTheaders['content-type']application/x-www-form-urlencoded ,会将数据转换成 query string: encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...

referer 说明

  • 网络请求的 referer Header 不可设置。

  • 其格式固定为 https://urlhost/{appid}/{version}/page-frame.html,其中 {appid} 为小程序的 APPID,{version} 为小程序的版本号。

success 返回值

名称

类型

描述

data

String

响应数据,格式取决于请求时的 dataType 参数

status

Number

响应码

headers

Object

响应头

错误码

错误码

描述

解决方案

1

请求没有结束,就跳转到了另一个页面

建议请求完成后再进行页面跳转

2

参数错误。

  • 可能是链接过长导致,建议参数放在 data 中处理。

  • 建议检查请求时传递的数据是否正常,格式是否正确,可以在请求前打印下入参数据日志。

11

无权跨域

检查请求域名是否添加了域名白名单,开发版测试可以点击 IDE 右上角 > 详情,勾选 忽略 httpRequest 域名合法性检查注意:新版本上架,一定要添加 服务器域名白名单,否则会出现异常。

12

网络出错

建议检查网络环境是否正常,服务器是否稳定。

13

超时

建议检查网络环境是否正常,服务器是否正常响应,若请求需要时间长,可适当设置超时时间 timeout。

14

解码失败

建议检查前后端请求和响应数据格式是否一致。如返回数据格式 text 与入参 dataType 值 JSON 不一致而导致接口报错,请修改后台返回数据格式为 JSON。

15

传参失败。

小程序页面传参如果做 urlencode 需要把整体参数进行编码。

19

HTTP 错误

  • 请确认请求 URL 地址在外网是否能正常请求 HTTPS 协议,小程序真机中均为线上环境的正式请求,不能使用局域网本地请求。

  • 如遇见 HTTP 404、500、504 等异常错误,建议打开 IDE 调试器 > Network 以查看具体的错误信息,然后根据对应 HTTP 错误码对症处理。

  • SSL 证书不正确导致,建议更换网站 SSL 证书。

20

请求已被停止/服务端限流

请确认请求服务器是否能正常请求和响应。

23

代理请求失败。

建议检查代理配置是否正确。

说明

当入参 dataType 值为 json 时,小程序框架会先对返回结果做 JSON.prase 操作,如果解析失败,则会返回 error 为 14 的错误。当入参 dataType 值为 text 时,如果返回的内容格式不符,也会返回 error 为 14 的错误。遇到此错误时,请先检查 dataType 的设置是否正确。

my.request 调用返回 无权调用该接口,则需要在 开放平台小程序管理 > 服务器域名白名单 中配置域名白名单。

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

my.request({
  url: 'https://example.org/post',
  method: 'POST',
  data: {
    from: '支付宝',
    production: 'AlipayJSAPI',
  },
  dataType: 'json',
  success: function(res) {
    my.alert({content: 'success'});
  },
  fail: function(res) {
    my.alert({content: 'fail'});
  },
  complete: function(res) {
    my.hideLoading();
    my.alert({content: 'complete'});
  }
});

// 返回RequestTask,可以调用abort方法取消请求
const task = my.request({url: 'https://example.org/post'})
task.abort()

返回值

RequestTask

网络请求任务对象。

方法

RequestTask.abort()

my.uploadFile

说明

mPaaS 10.1.32 及以上版本支持该接口。

上传本地资源到开发者服务器。

使用说明

  • 需预先在 开放平台小程序管理 > 服务器域名白名单 中配置域名白名单。小程序在以下 API 调用时只能与白名单中的域名进行通讯:HTTP 请求(my.request)、上传文件(my.uploadFile)。

入参

名称

类型

必填

描述

url

String

开发者服务器地址

filePath

String

要上传文件资源的本地定位符

fileName

String

文件名,即对应的 key, 开发者在服务器端通过这个 key 可以获取到文件二进制内容

fileType

String

文件类型,image/video/audio

hideLoading

Bool

是否隐藏 loading 图(默认值为 false)

header

Object

HTTP 请求 Header

formData

Object

HTTP 请求中其他额外的 form 数据

success

Function

调用成功的回调函数

fail

Function

调用失败的回调函数

complete

Function

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

success 返回值

名称

类型

描述

data

String

服务器返回的数据

statusCode

String

HTTP 状态码

header

Object

服务器返回的 Header

错误码

error

描述

解决方案

11

文件不存在

检查本地文件是否存在

12

上传文件失败

检查网络和服务器

13

没有权限

检查权限设置

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

my.uploadFile({
  url: '请使用自己服务器地址',
  fileType: 'image',
  fileName: 'file',
  filePath: '...',
  success: (res) => {
    my.alert({
      content: '上传成功'
    });
  },
});

UploadTask

监听上传进度变化,取消上传任务的对象。

方法

方法

描述

UploadTask.abort()

中断上传任务

UploadTask.onProgressUpdate(function callback)

监听上传进度变化事件

代码示例

const task = my.uploadFile({
  url: '请使用自己服务器地址',
  fileType: 'image',
  fileName: 'file',
  filePath: '...',
});
task.onProgressUpdate(({progress, totalBytesWritten, totalBytesExpectedToWrite}) => {
})
task.abort()

常见问题

  • Q:小程序上传图片可以自动转成 Base64(基于 64 个可打印字符来表示二进制数据的方法)吗?

    A:小程序暂不支持图片转成 Base64。

  • Q:my.uploadFile 如何获取服务器返回的错误信息?

    A:

    • 可以通过 success 回调中的 data 参数获取。

    • 可以在服务端增加一个日志获取接口。如果上传失败,就请求到日志获取接口获取详细的失败日志。

  • Q:my.uploadFile 默认超时时间是多长?是否可以设置默认延长时间?

    A:my.uploadFile 默认超时时间是 30s,目前无法设置默认延长时间。

  • Q:使用 my.uploadFile 上传文件,为何报错 error:12

    A:上传失败导致报错 error:12,造成上传失败的可能原因有:

    • 文件过大。

    • 上传时间超过 30s。

    • 没有权限。

  • Q:使用 my.uploadFile 上传图片至后台,接收的是二进制图片,再从后台发送小程序前台对应的二进制图片,小程序前台是如何解析的?

    A:上传图片是后端通过二进制流接受图片,之后后端只需提供对应的图片在服务器上的位置地址即可。

  • Q:调用 my.uploadfile,为何报错 error: 4,无权限调用此接口?

    A:请求的 URL 没有配置白名单,建议添加 URL 的域名为白名单。

  • Q:小程序是否支持上传 Excel 文件?

    A:目前 my.uploadFile 上传文件类型支持图片、视频、音频( image / video / audio),暂不支持其他类型的文件。

  • Q:my.uploadFile 是否支持多张图片同时上传?

    A:my.uploadFile 暂不支持多张图片同时上传,一次只能上传一张图片。

my.downloadFile

说明

mPaaS 10.1.32 及以上版本支持该接口。

下载文件资源到本地。

入参

名称

类型

必填

描述

url

String

下载文件地址

header

Object

HTTP 请求 Header

success

Function

调用成功的回调函数

fail

Function

调用失败的回调函数

complete

Function

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

success 返回值

名称

类型

描述

apFilePath

String

文件临时存放的位置

错误码

error

描述

解决方案

12

下载失败

建议检查网络和服务器

13

没有权限

建议检查权限

20

请求的 URL 不支持 HTTP

建议将请求的 URL 改成 HTTPS

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

// API-DEMO page/API/download-file/download-file.json
{
    "defaultTitle": "下载文件"
}
<!-- API-DEMO page/API/download-file/download-file.axml-->
<view class="container">
  <button onTap="download">下载图片并显示</button>
</view>
// API-DEMO page/API/download-file/download-file.js
Page({
  download() {
    my.downloadFile({
      url: 'https://img.alicdn.com/tfs/TB1x669SXXXXXbdaFXXXXXXXXXX-520-280.jpg',
      success({ apFilePath }) {
        my.previewImage({
          urls: [apFilePath],
        });
      },
      fail(res) {
        my.alert({
          content: res.errorMessage || res.error,
        });
      },
    });
  },
})

my.connectSocket

说明

mPaaS 10.1.60 及以上版本支持该接口。

创建一个 WebSocket 的连接。

一个小程序同时只能保留一个 WebSocket 连接,如果当前已存在 WebSocket 连接,会自动关闭该连接,并重新创建一个新的 WebSocket 连接。

入参

名称

类型

必填

描述

url

String

目标服务器 URL。注意:部分新发布的小程序只支持 wss 协议。

data

Object

请求的参数

header

Object

设置请求的头部

success

Function

调用成功的回调函数

fail

Function

调用失败的回调函数

complete

Function

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

错误码

error

描述

解决方案

1

未知错误

-

2

网络连接已经存在

一个小程序在一段时间内只能保留一个 WebSocket 连接。如果当前已存在 WebSocket 连接,那么会自动关闭该连接,并重新创建一个新的 WebSocket 连接。

3

URL 参数为空

替换 URL 链接。

4

无法识别的 URL 格式

替换 URL 链接。

5

URL 必须以 ws 或者 wss 开头

替换 URL 链接。

6

连接服务器超时

稍后重试。

7

服务器返回的 HTTPS 证书无效

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

8

服务端返回协议头无效

从 2019 年 5 月开始新创建的小程序,默认强制使用 HTTPS 和 WSS 协议,不再支持 HTTP 和 WS 协议。

9

WebSocket 请求没有指定 Sec-WebSocket-Protocol 请求头

请指定 Sec-WebSocket-Protocol 请求头。

10

网络连接没有打开,无法发送消息

请正常连接服务器后再调用 my.sendSocketMessage 发送数据消息,可通过 my.onSocketOpen 监听事件来判断与服务器建立正确连接。注意:通过 WebSocket 连接发送数据,需要先使用 my.connectSocket 发起连接,在 my.onSocketOpen 回调之后再调用 my.sendSocketMessage 发送数据。

11

消息发送失败

稍后重试。

12

无法申请更多内存来读取网络数据

请检查内存。

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

my.connectSocket({
  url: 'test.php',
  data: {},
  header:{
    'content-type': 'application/json'
  },
});

my.onSocketOpen

说明

mPaaS 10.1.60 及以上版本支持该接口。

监听 WebSocket 连接打开事件。

入参

Object 类型,属性如下:

属性

类型

必填

说明

callback

Function

WebSocket 连接打开事件的回调函数。

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

my.connectSocket({
  url: 'test.php',
});

my.onSocketOpen(function(res) {
  console.log('WebSocket 连接已打开!');
});

my.offSocketOpen

说明

mPaaS 10.1.60 及以上版本支持该接口。

取消监听 WebSocket 连接打开事件。

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

Page({
  onLoad() {
    this.callback = this.callback.bind(this);
    my.onSocketOpen(this.callback);
  },
  onUnload() {
    my.offSocketOpen(this.callback);
  },
  callback(res) {
  },
})

是否需要传 callback 值

  • 不传递 callback 值,则会移除监听所有的事件回调。代码示例如下:

    my.offSocketOpen();
  • 传递 callback 值,只移除对应的 callback 事件。代码示例如下:

    my.offSocketOpen(this.callback);

my.onSocketError

说明

mPaaS 10.1.60 及以上版本支持该接口。

监听 WebSocket 错误。

入参

Object 类型,属性如下:

参数

类型

必填

说明

callback

Function

WebSocket 错误事件的回调函数。

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

my.connectSocket({
  url: '开发者的服务器地址'
});

my.onSocketOpen(function(res){
  console.log('WebSocket 连接已打开!');
});

my.onSocketError(function(res){
  console.log('WebSocket 连接打开失败,请检查!');
});

my.offSocketError

说明

mPaaS 10.1.60 及以上版本支持该接口。

取消监听 WebSocket 错误。

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

Page({
  onLoad() {
    this.callback = this.callback.bind(this);
    my.onSocketError(this.callback);
  },
  onUnload() {
    my.offSocketError(this.callback);
  },
  callback(res) {
  },
})

是否需要传 callback 值

  • 不传递 callback 值,则会移除监听所有的事件回调。代码示例如下:

    my.offSocketError();
  • 传递 callback 值,只移除对应的 callback 事件。代码示例如下:

    my.offSocketError(this.callback);

my.sendSocketMessage

说明

mPaaS 10.1.60 及以上版本支持该接口。

通过 WebSocket 连接发送数据,需要先使用 my.connectSocket 发起建连,并在 my.onSocketOpen 回调之后再发送数据。

入参

名称

类型

必填

描述

data

String

需要发送的内容:普通的文本内容 String 或者经 base64 编码后的 String。

isBuffer

Boolean

如果需要发送二进制数据,需要将入参数据经 base64 编码成 String 后,赋值 data,同时将此字段设置为 true,否则,若为普通的文本内容 String,则不需要设置此字段。

success

Function

回调函数。

fail

Function

调用失败的回调函数。

complete

Function

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

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

my.sendSocketMessage({
    data: this.data.toSendMessage, // 需要发送的内容
    success: (res) => {
        my.alert({content: '数据发送!' + this.data.toSendMessage});
    },
});

my.onSocketMessage

说明

mPaaS 10.1.60 及以上版本支持该接口。

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

回调返回值

名称

类型

描述

data

String/ArrayBuffer

服务器返回的消息:普通的文本 String 或者经 base64 编码后的 String。

isBuffer

Boolean

如果此字段值为 truedata 字段表示接收到的经过了 base64 编码后的 String,否则,data 字段表示接收到的普通 String 文本。

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

my.connectSocket({
  url: '服务器地址'
})

my.onSocketMessage(function(res) {
  console.log('收到服务器内容:' + res.data)
})

my.offSocketMessage

说明

mPaaS 10.1.60 及以上版本支持该接口。

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

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

my.connectSocket({
  url: '服务器地址'
})
my.onSocketMessage(function(res) {
  console.log('收到服务器内容:' + res.data)
})
my.offSocketMessage();

是否需要传 callback 值

  • 不传递 callback 值,则会移除监听所有的事件回调。代码示例如下:

    my.offSocketMessage();
  • 传递 callback 值,只移除对应的 callback 事件。代码示例如下:

    my.offSocketMessage(this.callback);

my.closeSocket

说明

mPaaS 10.1.60 及以上版本支持该接口。

关闭 WebSocket 连接。

入参

名称

类型

必填

描述

success

Function

回调函数

fail

Function

调用失败的回调函数

complete

Function

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

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

my.onSocketOpen(function() {
  my.closeSocket()
})

my.onSocketClose(function(res) {
  console.log('WebSocket 已关闭!')
})

my.onSocketClose

说明

mPaaS 10.1.60 及以上版本支持该接口。

监听 WebSocket 关闭。

入参

Object 类型,属性如下:

参数

类型

必填

描述

callback

Function

WebSocket 连接关闭事件的回调函数。

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

onLoad() {
    // 注意: 回调方法的注册在整个小程序启动阶段只要做一次,调多次会有多次回调
    my.onSocketClose((res) => {
      my.alert({content: '连接已关闭!'});
      this.setData({
        sendMessageAbility: false,
        closeLinkAbility: false,
      });
    });
    // 注意: 回调方法的注册在整个小程序启动阶段只要做一次,调多次会有多次回调
    my.onSocketOpen((res) => {
      my.alert({content: '连接已打开!'});
      this.setData({
        sendMessageAbility: true,
        closeLinkAbility: true,
      });
    });

    my.onSocketError(function(res){
      my.alert('WebSocket 连接打开失败,请检查!' + res);
    });

    // 注意: 回调方法的注册在整个小程序启动阶段只要做一次,调多次会有多次回调
    my.onSocketMessage((res) => {
      my.alert({content: '收到数据!' + JSON.stringify(res)});
    });
  }

connect_start() {
    my.connectSocket({
      url: '服务器地址', // 开发者服务器接口地址,必须是 wss 协议,且域名必须是后台配置的合法域名
      success: (res) => {
        my.showToast({
          content: 'success', // 文字内容
        });
      },
      fail:()=>{
        my.showToast({
          content: 'fail', // 文字内容
        });
      }
    });
  },

my.offSocketClose

说明

mPaaS 10.1.60 及以上版本支持该接口。

取消监听 WebSocket 关闭。

代码示例

案例仅供参考,建议使用您自己的地址进行测试。

Page({
  onLoad() {
  my.onSocketClose(this.callback);
  },
  onUnload() {
    my.offSocketClose(this.callback);
    //    my.offSocketClose();
  },
  callback(res) {
  my.alert({content: '连接已关闭!'});
      this.setData({
        sendMessageAbility: false,
        closeLinkAbility: false,
      });
  },
})

是否需要传 callback 值

  • 不传递 callback 值,则会移除监听所有的事件回调。示例代码如下:

    my.offSocketClose();
  • 传递 callback 值,只移除对应的 callback 事件。示例代码如下:

    my.offSocketClose(this.callback);