网络 - 移动开发平台 mPaaS

my.request

小程序网络请求。

my.request 目前支持 GET/POST/PUT/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/PUT/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)...。
若方法为 POST 且 headers['content-type'] 为 application/json ，会对数据进行 JSON 序列化。
若方法为 POST 且 headers['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 调用返回 无权调用该接口，则需要在 开放平台小程序管理 > 服务器域名白名单 中配置域名白名单。

whitelist

代码示例

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

   
    my.request({
      url: 'https://httpbin.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://httpbin.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 错误。

入参

Obejct 类型，属性如下：

参数	类型	必填	说明
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	如果此字段值为 `true`，`data` 字段表示接收到的经过了 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 关闭。

入参

Obejct 类型，属性如下：

参数	类型	必填	描述
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);
     
```