Mobile Platform as a Service：網路

my.request

小程式網路請求。

• my.request 目前支援 GET/POST/DELETE。

• my.request 目前只支援 HTTPS 協議的請求。

更多問題請參見 my.request 常見問題。

使用說明：

• 需預先在 小程式發布 > 開放平台小程式管理 中開啟 小程式許可權控制開關，並在 伺服器網域名稱白名單 中佈建網域名白名單。小程式在以下 API 呼叫時只能與白名單中的網域名稱進行通訊：HTTP 要求（my.request）、上傳檔案（my.uploadFile）。

• 添加伺服器網域名稱白名單後，需要重新打包上傳產生體驗版，伺服器網域名稱才會生效。

• 在 IDE 上進行調試時，請使用真機預覽調試。

入參

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 傳回值

錯誤碼

若 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

上傳本地資源到開發人員伺服器。

使用說明：

• 需預先在 開放平台小程式管理 > 伺服器網域名稱白名單 中佈建網域名白名單。小程式在以下 API 呼叫時只能與白名單中的網域名稱進行通訊：HTTP 要求（my.request）、上傳檔案（my.uploadFile）。

入參

success 傳回值

錯誤碼

程式碼範例

案例僅供參考，建議使用您自己的地址進行測試。

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

UploadTask

監聽上傳進度變化，取消上傳任務的對象。

方法

程式碼範例

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

下載檔案資源到本地。

入參

success 傳回值

錯誤碼

程式碼範例

案例僅供參考，建議使用您自己的地址進行測試。

// 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

建立一個 WebSocket 的串連。

一個小程式同時只能保留一個 WebSocket 串連，如果當前已存在 WebSocket 串連，會自動關閉該串連，並重新建立一個新的 WebSocket 串連。

入參

錯誤碼

程式碼範例

案例僅供參考，建議使用您自己的地址進行測試。

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

my.onSocketOpen

監聽 WebSocket 串連開啟事件。

入參

Object 類型，屬性如下：

程式碼範例

案例僅供參考，建議使用您自己的地址進行測試。

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

my.onSocketOpen(function(res) {
  console.log('WebSocket 串連已開啟！');
});

my.offSocketOpen

取消監聽 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

監聽 WebSocket 錯誤。

入參

Object 類型，屬性如下：

程式碼範例

案例僅供參考，建議使用您自己的地址進行測試。

my.connectSocket({
  url: '開發人員的伺服器位址'
});

my.onSocketOpen(function(res){
  console.log('WebSocket 串連已開啟！');
});

my.onSocketError(function(res){
  console.log('WebSocket 串連開啟失敗，請檢查！');
});

my.offSocketError

取消監聽 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

通過 WebSocket 串連發送資料，需要先使用 my.connectSocket 發起建連，並在 my.onSocketOpen 回調之後再發送資料。

入參

程式碼範例

案例僅供參考，建議使用您自己的地址進行測試。

my.sendSocketMessage({
    data: this.data.toSendMessage, // 需要發送的內容
    success: (res) => {
        my.alert({content: '資料發送！' + this.data.toSendMessage});
    },
});

my.onSocketMessage

監聽 WebSocket 接受到伺服器的訊息事件。

回調傳回值

程式碼範例

案例僅供參考，建議使用您自己的地址進行測試。

my.connectSocket({
  url: '伺服器位址'
})

my.onSocketMessage(function(res) {
  console.log('收到伺服器內容：' + res.data)
})

my.offSocketMessage

取消監聽 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

關閉 WebSocket 串連。

入參

程式碼範例

案例僅供參考，建議使用您自己的地址進行測試。

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

my.onSocketClose(function(res) {
  console.log('WebSocket 已關閉！')
})

my.onSocketClose

監聽 WebSocket 關閉。

入參

Object 類型，屬性如下：

程式碼範例

案例僅供參考，建議使用您自己的地址進行測試。

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

取消監聽 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);

my.rpc({
      operationType: 'com.xx.xx',
      requestData: [{
        "param1":"",
        "param2":0
      }],
      success: res => {
      },
      fail: res => {
      }
});