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

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

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

阿里云客户端已不再维护 my.httpRequest,建议使用 my.request。另外,钉钉客户端尚不支持 my.request。若在钉钉客户端开发小程序,则需要使用 my.httpRequest。

扫码体验

image.png

重要:

  • 小程序开发过程中,可在开发工具内

    详情 > 域名信息 > 忽略 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',
  },
  headers:{
    'content-type':'application/json'  //默认值
  },
  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);
  },
});undefined

入参

Object 类型,属性如下:

属性

类型

必填

描述

url

String

目标服务器 URL。

headers

Object

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

method

String

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

data

Object

详见

data 参数说明

timeout

Number

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

dataType

String

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

success

Function

调用成功的回调函数。

fail

Function

调用失败的回调函数。

complete

Function

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

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 类型,属性如下:

属性

类型

描述

data

String

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

status

Number

响应码。

headers

Object

响应头。

错误码

错误码

描述

error: 1

{error: 1, message: "not implemented!"} 请求没有结束,就跳转到了另一个页面。

error: 2

参数错误。

error: 11

无权跨域。

error: 12

网络出错。

error: 13

超时。

error: 14

解码失败。

error: 15

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

error: 19

HTTP错误。

error: 20

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

error: 23

代理请求失败。

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

入参 dataType 值

返回 error 14 的原因

JSON

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

text

返回的内容格式不符。

base64

转换失败。

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

image

返回值 RequestTask

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

RequestTask.abort()

中断请求任务。

示例代码

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

 task  myurl 
task

常见问题

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

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

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

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

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

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

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

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

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

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

image

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

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

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

不会的,这个无影响。

在 IDE 预览模式中测试 my.request 为何没有反应?

在 IDE 中测试 my.requet,需在 IDE 真机模式下,且 my.request 请求地址必须要使用 HTTPS 地址。

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

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

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是否保持一致。

使用 my.request 传参,为何参数出现乱码?

您可以选择以下两种方法中的一种进行解决:

  • 使用 POST 请求。

  • 在前端使用 encodeURIComponent("你好呀") ,后端使用URLDecoder.decode(aa, "UTF-8") 解析。

是否可以本地测试小程序请求服务端呢?

不可以本地测试小程序请求服务端。

my.request 可以同步执行吗?

my.request 是异步执行的,无法同步执行。

小程序网络请求支持设置 HTTP REFERER 吗?

小程序会自带 HTTP Referer,暂时不支持自定义设置 HTTP Referer。

my.request 与 my.httpRequest 的区别是什么呢?

  1. my.request 是 my.httpRequest 的升级优化,都是小程序端与服务器端交互发起网络请求,体验上没有大的区别。

  2. 阿里云客户端已不再维护 my.httpRequest,建议使用 my.request。另外,钉钉客户端尚不支持 my.request。若在钉钉客户端开发小程序,则需要使用 my.httpRequest。

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

  4. 版本要求:基础库 1.11.0 或更高版本;阿里云客户端 10.1.32 或更高版本。

my.request 是否支持 IP 地址请求?是否支持 IPv6 域名?

  1. my.request 暂不支持 IP 地址请求,不支持 http 请求,请使用 https 请求。

  2. my.request 暂不支持 IPv6 域名。

  3. my.request 不建议使用关于 127.0.0.1 的测试请求。

my.request 为何显示请求失败,提示 error:2 入参有误?

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