• 下载
  • 社区

my.request

版本要求:基础库 1.11.0 或更高版本;支付宝客户端 10.1.32 或更高版本,若版本较低,建议做 兼容处理


发起网络请求:

  • my.request 目前支持 GET/POST/PUT/DELETE(其中PUT、DELETE请求在支付宝客户端10.1.82或更高版本支持)。
  • my.request 目前只支持 https 协议的请求。

更多问题请参见 常见问题


使用说明:

  • 请预先在 支付宝小程序管理中心 > 小程序详情 > 设置 > 开发设置 > 服务器域名白名单 中配置域名白名单。小程序在以下 API 调用时只能与白名单中的域名进行通讯:HTTP请求(my.request)、上传文件(my.uploadFile)、下载文件(my.downloadFile和 WebSocket(my.connectSocket)。

image.png


  • 添加服务器域名白名单后,需要重新打包上传生成体验版,服务器域名才会生效。
  • 在 IDE 上进行调试时,请使用真机预览调试。
  • 支付宝客户端已不再维护 my.httpRequest,建议使用 my.request。另外,钉钉客户端尚不支持 my.request。若在钉钉客户端开发小程序,则需要使用 my.httpRequest。


扫码体验

request.jpeg

重要:

  • 小程序开发过程中,可在开发工具内 详情 > 域名信息 > 忽略 httpRequest 域名合法性检查 中选择是否忽略域名合法性检查,如果选择忽略,则在模拟器、预览以及真机调试场景不会校验域名合法性,但小程序上线前必须确保通讯域名在白名单内,否则在正式版本无法调用。
  • my.request 的请求头默认值为 {'content-type': 'application/json'},不是{'content-type': 'application/x-www-form-urlencoded'}。此外,请求头对象里面的 key 和 value 必须是 String 类型。


示例代码

// dataType 为 json 示例
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'});
  }
});

// dataType 为 base64 示例
my.request({
  url: 'https://gw.alipayobjects.com/mdn/miniapp_de/afts/img/A*G1kWSJbe2zEAAAAAAAAAAABjARQnAQ',
  method: 'GET',
  dataType: 'base64',
  success: (resp) => {
    console.log('resp data length', resp.data.length);
    console.log('resp data', resp.data); // 返回格式类似于:data:image/png;base64,iVBORw0KG...
  },
  fail: (err) => {
    console.log('error', err);
  },
});


入参

Object 类型,属性如下:

属性类型必填描述
urlString目标服务器 URL。
headersObject设置请求的 HTTP 头对象,默认 {'content-type': 'application/json'},该对象里面的 key 和 value 必须是 String 类型。
methodString默认 GET,目前支持 GET/POST/PUT/DELETE。
dataObject详见 data 参数说明
timeoutNumber超时时间,单位 ms,默认 30000。
dataTypeString

期望返回的数据格式,默认 JSON,支持 JSON、text、base64、arraybuffer(10.1.70版本开始支持)

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


data 参数说明


传给服务器的数据最终会是 String 类型,如果 data 不是 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)...


success 回调函数

入参为 Object 类型,属性如下:

属性类型描述
dataString响应数据,格式取决于请求时的 dataType 参数,

如果 dataType 值为 base64 时,返回的是符合 data URI scheme  规范的内容字符串。

statusNumber响应码。
headersObject响应头。


错误码

错误码描述

2

参数错误。

11无权跨域。
12网络出错。
13超时。
14解码失败。
19HTTP错误。
20请求已被停止/服务端限流。

23

代理请求失败。


以下几种情况,会返回 error 为 14 的错误(遇到此错误时,请先检查 dataType 的设置是否正确):


入参 dataType 值

返回 error 14 的原因

JSON

小程序框架对返回结果做 JSON.prase 操作时解析失败。

text

返回的内容格式不符。

base64

转换失败。



若 request 调用返回 无权调用该接口,则需要在 支付宝小程序管理中心 > 设置 > 开发设置 > 服务器域名白名单 中配置域名白名单。


14.png



返回值 RequestTask


网络请求任务对象。调用 my.request 后返回的请求对象。


RequestTask.abort()


中断请求任务。


示例代码

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


常见问题

小程序只支持 https 域名配置吗?

小程序只支持 https 域名配置。

相比于 http,https 可以提供更加优质保密的信息,保证了用户数据的安全性,此外 https 同时也一定程度上保护了服务端,使用恶意攻击和伪装数据的成本大大提高。 

因此小程序强制使用 https,还在使用 http 协议的开发者需要尽快对服务器进行升级。 

为了方便开发者尽快进行 https 的配置,我们提供了免费的 SSL 证书,点此申请


my.request 请求报错“[API 调用] 请配置安全域名”,如何处理?

此报错是未添加服务器域名白名单所致,请检查并确保已添加服务器域名白名单。


my.request 请求报错“无权跨域调用”,如何处理?

步骤一:在小程序管理中心配置服务器域名白名单。

步骤二:若在 IDE 中进行测试,请设置 忽略 httpRequest 域名合法性检查

8627A7BF-B20F-4e13-BC2E-33C979CA02AE.png


my.request 请求报错 error: 19,如何处理?

这是 SSL 证书不正确导致的,建议更换网站 SSL 证书,点此申请


my.request 是否支持 PUT 请求?

目前 my.request 只支持 GET 和 POST 请求,不支持其他请求方式。


同时发送多个 https 请求会造成页面卡顿,每秒传输帧数(FPS)低吗?

不会的,这个无影响。


添加服务器域名白名单,为什么不生效呢?

添加服务器白名单后需要重新打包上传生成体验版。


RequestTask.abort() 方法是在小程序前端进行请求打断还是直接中止了服务端请求?

RequestTask.abort() 方法只是强制断掉了和后端的链接,并不是阻止请求。


my.request 请求报错 {data: "请求超时异常", error: 14, headers: {…}, status: 13, errorMessage: "JSON parse data error"} ,如何处理?

因返回数据格式 text 与入参 dataType 值 JSON 不一致而导致接口报错,请修改后台返回数据格式为 JSON。


小程序后端可以从请求头部,获取到小程序 appId 吗?

小程序后端无法从请求头部获取到小程序 appId。可以通过 my.getAppIdSync 同步获取 appId。


小程序通过 my.request 访问后台,为什么后台获取不到前端 data 中携带参数的值?

建议排查后台获取参数值时,与前端携带参数的key是否保持一致。