HTTP数据请求

场景介绍

应用通过HTTP发起一个数据请求，支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。当前提供了2种HTTP请求方式，若请求发送或接收的数据量较少，可使用HttpRequest.request，若是大文件的上传或者下载，且关注数据发送和接收进度，可使用HTTP请求流式传输HttpRequest.requestInstream。

当前HTTP请求支持的场景如下，以下功能对应的选项可以在HTTP请求的HttpResponseOptions中进行设置：

发起HTTP数据请求

说明：

在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，请参见获取UIAbility的上下文信息。

1. 导入HTTP一般数据请求所需模块

   import { http } from '@kit.NetworkKit';
   import { BusinessError } from '@kit.BasicServicesKit';
   import { common } from '@kit.AbilityKit';
   

2. 创建HttpRequest对象

   调用createHttp()方法，创建HttpRequest对象。

   let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
   // 每一个httpRequest对应一个HTTP请求任务，不可复用。
   let httpRequest = http.createHttp();
   

3. 订阅HTTP响应头事件

   调用该对象的on()方法，订阅HTTP响应头事件，此接口会比request请求先返回。可以根据业务需要订阅此消息。

   // 用于订阅HTTP响应头，此接口会比request请求先返回。可以根据业务需要订阅此消息。
   // 从API 8开始，使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。
   httpRequest.on('headersReceive', (header) => {
     console.info('header: ' + JSON.stringify(header));
   });
   

4. 发起HTTP请求，解析服务器响应事件

   调用该对象的request()方法，传入HTTP请求的url地址和可选参数，发起网络请求，按照实际业务需要，解析返回结果。

   httpRequest.request(
     // 填写HTTP请求的URL地址，可以带参数或不带参数。URL地址由开发者自定义。请求的参数可以在extraData中指定。
     "EXAMPLE_URL",
     {
       method: http.RequestMethod.POST, // 可选，默认为http.RequestMethod.GET，用于从服务器获取数据，而POST方法用于向服务器上传数据。
       // 开发者根据自身业务需要添加header字段。
       header: {
         'Content-Type': 'application/json'
       },
       // 当使用POST请求时此字段用于传递请求体内容，具体格式与服务端协商确定。
       extraData: "data to send",
       expectDataType: http.HttpDataType.STRING, // 可选，指定返回数据的类型。
       usingCache: true, // 可选，默认为true。
       priority: 1, // 可选，默认为1。
       connectTimeout: 60000, // 可选，默认为60000ms。
       readTimeout: 60000, // 可选，默认为60000ms。
       usingProtocol: http.HttpProtocol.HTTP1_1, // 可选，协议类型默认值由系统自动指定。
       usingProxy: false, // 可选，默认不使用网络代理，自API 10开始支持该属性。
       caPath:'/path/to/cacert.pem', // 可选，默认使用系统预制证书，自API 10开始支持该属性。
       clientCert: { // 可选，默认不使用客户端证书，自API 11开始支持该属性。
         certPath: '/path/to/client.pem', // 默认不使用客户端证书，自API 11开始支持该属性。
         keyPath: '/path/to/client.key', // 若证书包含Key信息，传入空字符串，自API 11开始支持该属性。
         certType: http.CertType.PEM, // 可选，默认使用PEM，自API 11开始支持该属性。
         keyPassword: "passwordToKey" // 可选，输入key文件的密码，自API 11开始支持该属性。
       },
       multiFormDataList: [ // 可选，仅当Header中，'content-Type'为'multipart/form-data'时生效，自API 11开始支持该属性，该属性用于支持向服务器上传二进制数据，根据上传的具体数据类型进行选择。
         {
           name: "Part1", // 数据名，自API 11开始支持该属性。
           contentType: 'text/plain', // 数据类型，自API 11开始支持该属性，上传的数据类型为普通文本文件。
           data: 'Example data', // 可选，数据内容，自API 11开始支持该属性。
           remoteFileName: 'example.txt' // 可选，自API 11开始支持该属性。
         }, {
           name: "Part2", // 数据名，自API 11开始支持该属性。
           contentType: 'text/plain', // 数据类型，自API 11开始支持该属性，上传的数据类型为普通文本文件。
           // data/app/el2/100/base/com.example.myapplication/haps/entry/files/fileName.txt。
           filePath: `${context.filesDir}/fileName.txt`, // 可选，传入文件路径，自API 11开始支持该属性。
           remoteFileName: 'fileName.txt' // 可选，自API 11开始支持该属性。
         }, {
           name: "Part3", // 数据名，自API 11开始支持该属性。
           contentType: 'image/png', // 数据类型，自API 11开始支持该属性，上传的数据类型为png格式的图片。
           // data/app/el2/100/base/com.example.myapplication/haps/entry/files/fileName.png。
           filePath: `${context.filesDir}/fileName.png`, // 可选，传入文件路径，自API 11开始支持该属性。
           remoteFileName: 'fileName.png' // 可选，自API 11开始支持该属性。
         }, {
           name: "Part4", // 数据名，自API 11开始支持该属性。
           contentType: 'audio/mpeg', // 数据类型，自API 11开始支持该属性，上传的数据类型为mpeg格式的音频。
           // data/app/el2/100/base/com.example.myapplication/haps/entry/files/fileName.mpeg。
           filePath: `${context.filesDir}/fileName.mpeg`, // 可选，传入文件路径，自API 11开始支持该属性。
           remoteFileName: 'fileName.mpeg' // 可选，自API 11开始支持该属性。
         }, {
           name: "Part5", // 数据名，自API 11开始支持该属性。
           contentType: 'video/mp4', // 数据类型，自API 11开始支持该属性，上传的数据类型为mp4格式的视频。
           // data/app/el2/100/base/com.example.myapplication/haps/entry/files/fileName.mp4。
           filePath: `${context.filesDir}/fileName.mp4`, // 可选，传入文件路径，自API 11开始支持该属性。
           remoteFileName: 'fileName.mp4' // 可选，自API 11开始支持该属性。
         }
       ]
     }, (err: BusinessError, data: http.HttpResponse) => {
       if (!err) {
         // data.result为HTTP响应内容，可根据业务需要进行解析。
         console.info('Result:' + JSON.stringify(data.result));
         console.info('code:' + JSON.stringify(data.responseCode));
         // data.header为HTTP响应头，可根据业务需要进行解析。
         console.info('header:' + JSON.stringify(data.header));
         console.info('cookies:' + JSON.stringify(data.cookies)); // 8+
         // 当该请求使用完毕时，调用destroy方法主动销毁。
         httpRequest.destroy();
       } else {
         console.error('error:' + JSON.stringify(err));
         // 取消订阅HTTP响应头事件。
         httpRequest.off('headersReceive');
         // 当该请求使用完毕时，调用destroy方法主动销毁。
         httpRequest.destroy();
       }
     }
   );
   

5. 取消订阅HTTP响应头事件

   调用该对象的off()方法，取消订阅HTTP响应头事件。

   // 在不需要该回调信息时，需要取消订阅HTTP响应头事件，该方法调用的时机，可以参考步骤4中的示例代码。
   httpRequest.off('headersReceive');
   

6. 调用destroy()方法销毁

   当该请求使用完毕时，调用destroy()方法销毁。

   // 当该请求使用完毕时，调用destroy方法主动销毁，该方法调用的时机，可以参考步骤4中的示例代码。
   httpRequest.destroy();
   

发起HTTP流式传输请求

HTTP流式传输是指在处理HTTP响应时，可以一次只处理响应内容的一小部分，而不是一次性将整个响应加载到内存，这对于处理大文件、实时数据流等场景非常有用。

1. 导入HTTP流式传输所需模块

   import { http } from '@kit.NetworkKit';
   import { BusinessError } from '@kit.BasicServicesKit';
   import { common } from '@kit.AbilityKit';
   

2. 创建HTTP流式传输HttpRequest对象

   调用createHttp()方法，创建HttpRequest对象。

   let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
   // 每一个httpRequest对应一个HTTP请求任务，不可复用。
   let httpRequest = http.createHttp();
   

3. 订阅HTTP流式响应头事件

   调用该对象的on()方法，订阅HTTP响应头事件，此接口会比request请求先返回。可以根据业务需要订阅此消息。

   // 用于订阅HTTP响应头，此接口会比request请求先返回。可以根据业务需要订阅此消息。
   // 从API 8开始，使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。
   httpRequest.on('headersReceive', (header) => {
     console.info('header: ' + JSON.stringify(header));
   });
   

4. 发起HTTP流式请求，解析服务器响应事件

   // 用于订阅HTTP流式响应数据接收事件。
   let res = new ArrayBuffer(0);
   httpRequest.on('dataReceive', (data: ArrayBuffer) => {
      const newRes = new ArrayBuffer(res.byteLength + data.byteLength);
      const resView = new Uint8Array(newRes);
      resView.set(new Uint8Array(res));
      resView.set(new Uint8Array(data), res.byteLength);
      res = newRes;
      console.info('res length: ' + res.byteLength);
   });
   // 用于订阅HTTP流式响应数据接收完毕事件。
   httpRequest.on('dataEnd', () => {
     console.info('No more data in response, data receive end');
   });
   // 订阅HTTP流式响应数据接收进度事件，下载服务器的数据时，可以通过该回调获取数据下载进度。
   httpRequest.on('dataReceiveProgress', (data: http.DataReceiveProgressInfo) => {
     console.log("dataReceiveProgress receiveSize:" + data.receiveSize + ", totalSize:" + data.totalSize);
   });
   
   
   // 订阅HTTP流式响应数据发送进度事件，向服务器上传数据时，可以通过该回调获取数据上传进度。
   httpRequest.on('dataSendProgress', (data: http.DataSendProgressInfo) => {
     console.log("dataSendProgress receiveSize:" + data.sendSize + ", totalSize:" + data.totalSize);
   });
   
   
   let streamInfo: http.HttpRequestOptions = {
     method: http.RequestMethod.POST,  // 可选，默认为http.RequestMethod.GET，用于向服务器获取数据，而POST方法用于向服务器上传数据。
     // 开发者根据自身业务需要添加header字段。
     header: {
       'Content-Type': 'application/json'
     },
     // 当使用POST请求时此字段用于传递请求体内容，具体格式与服务端协商确定。
     extraData: "data to send",
     expectDataType:  http.HttpDataType.STRING,// 可选，指定返回数据的类型。
     usingCache: true, // 可选，默认为true。
     priority: 1, // 可选，默认为1。
     connectTimeout: 60000, // 可选，默认为60000ms。
     readTimeout: 60000, // 可选，默认为60000ms。若传输的数据较大，需要较长的时间，建议增大该参数以保证数据传输正常终止。
     usingProtocol: http.HttpProtocol.HTTP1_1, // 可选，协议类型默认值由系统自动指定。
     multiFormDataList: [ // 可选，仅当Header中，'content-Type'为'multipart/form-data'时生效，自API 11开始支持该属性，该属性用于支持向服务器上传二进制数据，根据上传的具体数据类型进行选择。
       {
         name: "Part1", // 数据名，自API 11开始支持该属性。
         contentType: 'text/plain', // 数据类型，自API 11开始支持该属性，上传的数据类型为普通文本文件。
         data: 'Example data', // 可选，数据内容，自API 11开始支持该属性。
         remoteFileName: 'example.txt' // 可选，自API 11开始支持该属性。
       }, {
         name: "Part2", // 数据名，自API 11开始支持该属性。
         contentType: 'text/plain', // 数据类型，自API 11开始支持该属性，上传的数据类型为普通文本文件。
         // data/app/el2/100/base/com.example.myapplication/haps/entry/files/fileName.txt。
         filePath: `${context.filesDir}/fileName.txt`, // 可选，传入文件路径，自API 11开始支持该属性。
         remoteFileName: 'fileName.txt' // 可选，自API 11开始支持该属性。
       }, {
         name: "Part3", // 数据名，自API 11开始支持该属性。
         contentType: 'image/png', // 数据类型，自API 11开始支持该属性，上传的数据类型为png格式的图片。
         // data/app/el2/100/base/com.example.myapplication/haps/entry/files/fileName.png。
         filePath: `${context.filesDir}/fileName.png`, // 可选，传入文件路径，自API 11开始支持该属性。
         remoteFileName: 'fileName.png' // 可选，自API 11开始支持该属性。
       }, {
         name: "Part4", // 数据名，自API 11开始支持该属性。
         contentType: 'audio/mpeg', // 数据类型，自API 11开始支持该属性，上传的数据类型为mpeg格式的音频。
         // data/app/el2/100/base/com.example.myapplication/haps/entry/files/fileName.mpeg。
         filePath: `${context.filesDir}/fileName.mpeg`, // 可选，传入文件路径，自API 11开始支持该属性。
         remoteFileName: 'fileName.mpeg' // 可选，自API 11开始支持该属性。
       }, {
         name: "Part5", // 数据名，自API 11开始支持该属性。
         contentType: 'video/mp4', // 数据类型，自API 11开始支持该属性，上传的数据类型为mp4格式的视频。
         // data/app/el2/100/base/com.example.myapplication/haps/entry/files/fileName.mp4。
         filePath: `${context.filesDir}/fileName.mp4`, // 可选，传入文件路径，自API 11开始支持该属性。
         remoteFileName: 'fileName.mp4' // 可选，自API 11开始支持该属性。
       }
     ]
   }
   
   
   // 填写HTTP请求的URL地址，可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定。
   httpRequest.requestInStream("EXAMPLE_URL", streamInfo).then((data: number) => {
     console.info("requestInStream OK!");
     console.info('ResponseCode :' + JSON.stringify(data));
     // 取消订阅HTTP响应头事件。
     httpRequest.off('headersReceive');
     // 取消订阅HTTP流式响应数据接收事件。
     httpRequest.off('dataReceive');
     // 取消订阅HTTP流式响应数据接收进度事件。
     httpRequest.off('dataReceiveProgress');
     // 取消订阅HTTP流式响应数据接收完毕事件。
     httpRequest.off('dataEnd');
     // 当该请求使用完毕时，调用destroy方法主动销毁。
     httpRequest.destroy();
   }).catch((err: Error) => {
     console.error("requestInStream ERROR : err = " + JSON.stringify(err));
   });
   

5. 取消订阅HTTP流式响应头事件

   调用该对象的off()方法，取消订阅HTTP响应头事件，该方法调用的时机，可以参考步骤4中的示例代码。

   // 取消订阅HTTP响应头事件。
   httpRequest.off('headersReceive');
   

6. 调用destroy()方法销毁流式HTTP请求

   当该请求使用完毕时，调用destroy()方法销毁。

   // 当该请求使用完毕时，调用destroy方法主动销毁，该方法调用的时机，可以参考步骤4中的示例代码。
   httpRequest.destroy();
   

配置证书校验

当应用使用HTTPS协议时，涉及证书相关配置。面向互联网用户提供服务的应用仅需信任系统预置的CA证书。当前HTTP模块已默认信任系统预置的CA证书，无需特别设置。如果应用需要锁定证书，只信任开发者特别指定的证书，或者需要跳过证书校验，可以参考以下说明进行配置。

证书锁定

可以通过预置应用级证书，或者预置证书公钥哈希值的方式来进行证书锁定，即只有开发者特别指定的证书才能正常建立HTTPS连接。

两种方式都是在配置文件中配置的，配置文件在APP中的路径是：src/main/resources/base/profile/network_config.json。在该配置中，可以为预置的证书与网络服务器建立对应关系。

如果不知道服务器域名的证书，可以通过以下方式访问该域名获取证书，注意把www.example.com改成想要获取域名证书的域名，www.example.com.pem改成想保存的证书文件名：

openssl s_client -servername www.example.com -connect www.example.com:443 \
    < /dev/null|sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem

如果你的环境是Windows系统，需要注意：

• 将/dev/null替换成NUL。
• 和Linux的OpenSSL表现可能不同，OpenSSL可能会等待用户输入才会退出，按Enter键即可。
• 如果没有sed命令，将输出中从-----BEGIN CERTIFICATE-----到-----END CERTIFICATE-----之间的部分复制下来保存即可（复制部分包括这两行）。

预置应用级证书

直接把证书原文件预置在APP中。目前支持crt和pem格式的证书文件。

注意：

当前ohos.net.http和Image组件的证书锁定，会匹配证书链上所有证书的哈希值，如果服务器更新了任意一本证书，都会导致校验失败。如果服务器出现了更新证书的情况，APP版本应当随之更新并推荐消费者尽快升级APP版本，否则可能导致联网失败。

预置证书公钥哈希值

通过在配置中指定域名证书公钥的哈希值，只允许使用公钥哈希值匹配的域名证书访问此域名。

域名证书的公钥哈希值可以用如下的命令计算。假设域名证书是通过上面的OpenSSL命令获得的，并保存在www.example.com.pem文件。#开头的行是注释，可以不用输入：

# 从证书中提取出公钥
openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem
# 将pem格式的公钥转换成der格式
openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem -out www.example.com.pubkey.der
# 计算公钥的SHA256并转换成base64编码
openssl dgst -sha256 -binary www.example.com.pubkey.der|openssl base64

JSON配置文件示例

预置应用级证书的配置例子如下（具体配置路径可参考网络连接安全配置）：

{
  "network-security-config": {
    "base-config": {
      "trust-anchors": [
        {
          "certificates": "/etc/security/certificates"
        }
      ]
    },
    "domain-config": [
      {
        "domains": [
          {
            "include-subdomains": true,
            "name": "example.com"
          }
        ],
        "trust-anchors": [
          {
            "certificates": "/data/storage/el1/bundle/entry/resources/resfile"
          }
        ]
      }
    ]
  }
}

预置证书公钥哈希值的配置例子如下：

{
  "network-security-config": {
    "domain-config": [
      {
        "domains": [
          {
            "include-subdomains": true,
            "name": "server.com"
          }
        ],
        "pin-set": {
          "expiration": "2024-11-08",
          "pin": [
            {
              "digest-algorithm": "sha256",
              "digest": "FEDCBA987654321"
            }
          ]
        }
      }
    ]
  }
}

整体或者按域名的明文HTTP是否允许的配置示例如下：

{
  "network-security-config": {
    "base-config": {
      "cleartextTrafficPermitted": true
    },
    "domain-config": [
      {
        "domains": [
          {
            "include-subdomains": true,
            "name": "example.com"
          }
        ],
        "cleartextTrafficPermitted": false
      }
    ]
  }
}

证书锁定的配置例子如下:

{
  "network-security-config": {
    "domain-config": [
      {
        "domains": [
          {
            "include-subdomains": true,
            "name": "server.com"
          }
        ],
        "pin-set": {
          "expiration": "2024-11-08",
          "pin": [
            {
              "digest-algorithm": "sha256",
              "digest": "FEDCBA987654321"
            }
          ]
        }
      }
    ]
  },
  "trust-global-user-ca": false,
  "trust-current-user-ca": false,
}

各个字段含义:

配置不信任用户安装的CA证书

系统默认信任系统预置的CA证书和用户安装的CA证书，可配置不信任用户安装的CA证书提升安全性。配置不信任用安装的CA证书可以在src/main/resources/base/profile/network_config.json进行配置，更多网络连接安全相关的配置可以参考网络连接安全配置。

{
  "network-security-config": {
    ... ...
  },
  "trust-global-user-ca": false, // 配置是否信任企业MDM系统或设备管理员用户手动安装的CA证书，默认为true
  "trust-current-user-ca" : false // 配置是否信任当前用户安装的CA证书，默认为true
}

相关实例

针对HTTP数据请求，有以下相关实例可供参考：

• 上传和下载（ArkTS）(API10)

• Http（ArkTS）（API10）

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Network Kit（网络服务）

harmony 鸿蒙NetConnection开发指导

harmony 鸿蒙WebSocket连接(C/C++)

harmony 鸿蒙网络连接管理

harmony 鸿蒙以太网连接（仅对系统应用开放）

harmony 鸿蒙MDNS管理

harmony 鸿蒙Network Kit简介

harmony 鸿蒙网络防火墙

harmony 鸿蒙网络共享（仅对系统应用开放）

harmony 鸿蒙流量管理