1# HTTP数据请求 2 3## 场景介绍 4 5应用通过HTTP发起一个数据请求，支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 6 7## 接口说明 8 9HTTP数据请求功能主要由http模块提供。 10 11使用该功能需要申请ohos.permission.INTERNET权限。 12 13权限申请请参考[声明权限](../security/AccessToken/declare-permissions.md)。 14 15涉及的接口如下表，具体的接口说明请参考[API文档](../reference/apis-network-kit/js-apis-http.md)。 16 17| 接口名 | 描述 | 18| ----------------------------------------- | ----------------------------------- | 19| createHttp() | 创建一个http请求。 | 20| request() | 根据URL地址，发起HTTP网络请求。 | 21| requestInStream()<sup>10+</sup> | 根据URL地址，发起HTTP网络请求并返回流式响应。 | 22| destroy() | 中断请求任务。 | 23| on(type: 'headersReceive') | 订阅HTTP Response Header 事件。 | 24| off(type: 'headersReceive') | 取消订阅HTTP Response Header 事件。 | 25| once\('headersReceive'\)<sup>8+</sup> | 订阅HTTP Response Header 事件，但是只触发一次。| 26| on\('dataReceive'\)<sup>10+</sup> | 订阅HTTP流式响应数据接收事件。 | 27| off\('dataReceive'\)<sup>10+</sup> | 取消订阅HTTP流式响应数据接收事件。 | 28| on\('dataEnd'\)<sup>10+</sup> | 订阅HTTP流式响应数据接收完毕事件。 | 29| off\('dataEnd'\)<sup>10+</sup> | 取消订阅HTTP流式响应数据接收完毕事件。 | 30| on\('dataReceiveProgress'\)<sup>10+</sup> | 订阅HTTP流式响应数据接收进度事件。 | 31| off\('dataReceiveProgress'\)<sup>10+</sup> | 取消订阅HTTP流式响应数据接收进度事件。 | 32| on\('dataSendProgress'\)<sup>11+</sup> | 订阅HTTP网络请求数据发送进度事件。 | 33| off\('dataSendProgress'\)<sup>11+</sup> | 取消订阅HTTP网络请求数据发送进度事件。 | 34 35## request接口开发步骤 36 371. 从@kit.NetworkKit中导入http命名空间。 382. 调用createHttp()方法，创建一个HttpRequest对象。 393. 调用该对象的on()方法，订阅http响应头事件，此接口会比request请求先返回。可以根据业务需要订阅此消息。 404. 调用该对象的request()方法，传入http请求的url地址和可选参数，发起网络请求。 415. 按照实际业务需要，解析返回结果。 426. 调用该对象的off()方法，取消订阅http响应头事件。 437. 当该请求使用完毕时，调用destroy()方法主动销毁。 44 45**注意：** 关于示例代码中this的说明：在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，[请参见获取UIAbility的上下文消息](http://gitee.com/openharmony/docs/blob/222f8d93e6f0056409aac096e041df3fdd8ae5ec/zh-cn/application-dev/application-models/uiability-usage.md)。 46 47```ts 48// 引入包名 49import { http } from '@kit.NetworkKit'; 50import { BusinessError } from '@kit.BasicServicesKit'; 51import { common } from '@kit.AbilityKit'; 52 53let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 54// 每一个httpRequest对应一个HTTP请求任务，不可复用 55let httpRequest = http.createHttp(); 56// 用于订阅HTTP响应头，此接口会比request请求先返回。可以根据业务需要订阅此消息 57// 从API 8开始，使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ 58httpRequest.on('headersReceive', (header) => { 59 console.info('header: ' + JSON.stringify(header)); 60}); 61httpRequest.request( 62 // 填写HTTP请求的URL地址，可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 63 "EXAMPLE_URL", 64 { 65 method: http.RequestMethod.POST, // 可选，默认为http.RequestMethod.GET 66 // 开发者根据自身业务需要添加header字段 67 header: { 68 'Content-Type': 'application/json' 69 }, 70 // 当使用POST请求时此字段用于传递请求体内容，具体格式与服务端协商确定 71 extraData: "data to send", 72 expectDataType: http.HttpDataType.STRING, // 可选，指定返回数据的类型 73 usingCache: true, // 可选，默认为true 74 priority: 1, // 可选，默认为1 75 connectTimeout: 60000, // 可选，默认为60000ms 76 readTimeout: 60000, // 可选，默认为60000ms 77 usingProtocol: http.HttpProtocol.HTTP1_1, // 可选，协议类型默认值由系统自动指定 78 usingProxy: false, // 可选，默认不使用网络代理，自API 10开始支持该属性 79 caPath:'/path/to/cacert.pem', // 可选，默认使用系统预制证书，自API 10开始支持该属性 80 clientCert: { // 可选，默认不使用客户端证书，自API 11开始支持该属性 81 certPath: '/path/to/client.pem', // 默认不使用客户端证书，自API 11开始支持该属性 82 keyPath: '/path/to/client.key', // 若证书包含Key信息，传入空字符串，自API 11开始支持该属性 83 certType: http.CertType.PEM, // 可选，默认使用PEM，自API 11开始支持该属性 84 keyPassword: "passwordToKey" // 可选，输入key文件的密码，自API 11开始支持该属性 85 }, 86 multiFormDataList: [ // 可选，仅当Header中，'content-Type'为'multipart/form-data'时生效，自API 11开始支持该属性 87 { 88 name: "Part1", // 数据名，自API 11开始支持该属性 89 contentType: 'text/plain', // 数据类型，自API 11开始支持该属性 90 data: 'Example data', // 可选，数据内容，自API 11开始支持该属性 91 remoteFileName: 'example.txt' // 可选，自API 11开始支持该属性 92 }, { 93 name: "Part2", // 数据名，自API 11开始支持该属性 94 contentType: 'text/plain', // 数据类型，自API 11开始支持该属性 95 // data/app/el2/100/base/com.example.myapplication/haps/entry/files/fileName.txt 96 filePath: `${context.filesDir}/fileName.txt`, // 可选，传入文件路径，自API 11开始支持该属性 97 remoteFileName: 'fileName.txt' // 可选，自API 11开始支持该属性 98 } 99 ] 100 }, (err: BusinessError, data: http.HttpResponse) => { 101 if (!err) { 102 // data.result为HTTP响应内容，可根据业务需要进行解析 103 console.info('Result:' + JSON.stringify(data.result)); 104 console.info('code:' + JSON.stringify(data.responseCode)); 105 // data.header为HTTP响应头，可根据业务需要进行解析 106 console.info('header:' + JSON.stringify(data.header)); 107 console.info('cookies:' + JSON.stringify(data.cookies)); // 8+ 108 // 当该请求使用完毕时，调用destroy方法主动销毁 109 httpRequest.destroy(); 110 } else { 111 console.error('error:' + JSON.stringify(err)); 112 // 取消订阅HTTP响应头事件 113 httpRequest.off('headersReceive'); 114 // 当该请求使用完毕时，调用destroy方法主动销毁 115 httpRequest.destroy(); 116 } 117 } 118); 119``` 120 121## requestInStream接口开发步骤 122 1231. 从@kit.NetworkKit中导入http命名空间。 1242. 调用createHttp()方法，创建一个HttpRequest对象。 1253. 调用该对象的on()方法，可以根据业务需要订阅HTTP响应头事件、HTTP流式响应数据接收事件、HTTP流式响应数据接收进度事件和HTTP流式响应数据接收完毕事件。 1264. 调用该对象的requestInStream()方法，传入http请求的url地址和可选参数，发起网络请求。 1275. 按照实际业务需要，可以解析返回的响应码。 1286. 调用该对象的off()方法，取消订阅响应事件。 1297. 当该请求使用完毕时，调用destroy()方法主动销毁。 130 131```ts 132// 引入包名 133import { http } from '@kit.NetworkKit'; 134import { BusinessError } from '@kit.BasicServicesKit'; 135 136// 每一个httpRequest对应一个HTTP请求任务，不可复用 137let httpRequest = http.createHttp(); 138// 用于订阅HTTP响应头事件 139httpRequest.on('headersReceive', (header: Object) => { 140 console.info('header: ' + JSON.stringify(header)); 141}); 142// 用于订阅HTTP流式响应数据接收事件 143let res = new ArrayBuffer(0); 144httpRequest.on('dataReceive', (data: ArrayBuffer) => { 145 const newRes = new ArrayBuffer(res.byteLength + data.byteLength); 146 const resView = new Uint8Array(newRes); 147 resView.set(new Uint8Array(res)); 148 resView.set(new Uint8Array(data), res.byteLength); 149 res = newRes; 150 console.info('res length: ' + res.byteLength); 151}); 152// 用于订阅HTTP流式响应数据接收完毕事件 153httpRequest.on('dataEnd', () => { 154 console.info('No more data in response, data receive end'); 155}); 156// 用于订阅HTTP流式响应数据接收进度事件 157class Data { 158 receiveSize: number = 0; 159 totalSize: number = 0; 160} 161httpRequest.on('dataReceiveProgress', (data: Data) => { 162 console.log("dataReceiveProgress receiveSize:" + data.receiveSize + ", totalSize:" + data.totalSize); 163}); 164 165let streamInfo: http.HttpRequestOptions = { 166 method: http.RequestMethod.POST, // 可选，默认为http.RequestMethod.GET 167 // 开发者根据自身业务需要添加header字段 168 header: { 169 'Content-Type': 'application/json' 170 }, 171 // 当使用POST请求时此字段用于传递请求体内容，具体格式与服务端协商确定 172 extraData: "data to send", 173 expectDataType: http.HttpDataType.STRING,// 可选，指定返回数据的类型 174 usingCache: true, // 可选，默认为true 175 priority: 1, // 可选，默认为1 176 connectTimeout: 60000, // 可选，默认为60000ms 177 readTimeout: 60000, // 可选，默认为60000ms。若传输的数据较大，需要较长的时间，建议增大该参数以保证数据传输正常终止 178 usingProtocol: http.HttpProtocol.HTTP1_1 // 可选，协议类型默认值由系统自动指定 179} 180 181// 填写HTTP请求的URL地址，可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 182httpRequest.requestInStream("EXAMPLE_URL", streamInfo).then((data: number) => { 183 console.info("requestInStream OK!"); 184 console.info('ResponseCode :' + JSON.stringify(data)); 185 // 取消订阅HTTP响应头事件 186 httpRequest.off('headersReceive'); 187 // 取消订阅HTTP流式响应数据接收事件 188 httpRequest.off('dataReceive'); 189 // 取消订阅HTTP流式响应数据接收进度事件 190 httpRequest.off('dataReceiveProgress'); 191 // 取消订阅HTTP流式响应数据接收完毕事件 192 httpRequest.off('dataEnd'); 193 // 当该请求使用完毕时，调用destroy方法主动销毁 194 httpRequest.destroy(); 195}).catch((err: Error) => { 196 console.info("requestInStream ERROR : err = " + JSON.stringify(err)); 197}); 198``` 199 200## 证书锁定 201 202可以通过预置应用级证书，或者预置证书公钥哈希值的方式来进行证书锁定，即只有开发者特别指定的证书才能正常建立https连接。 203 204两种方式都是在配置文件中配置的，配置文件在APP中的路径是：`src/main/resources/base/profile/network_config.json`。在该配置中，可以为预置的证书与网络服务器建立对应关系。 205 206如果不知道服务器域名的证书，可以通过以下方式访问该域名获取证书，注意把`www.example.com`改成想要获取域名证书的域名，`www.example.com.pem`改成想保存的证书文件名： 207 208``` 209openssl s_client -servername www.example.com -connect www.example.com:443 \ 210 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem 211``` 212 213如果你的环境是Windows系统，需要注意： 214 215* 将`/dev/null`替换成`NUL`。 216* 和Linux的OpenSSL表现可能不同，OpenSSL可能会等待用户输入才会退出，按Enter键即可。 217* 如果没有sed命令，将输出中从`-----BEGIN CERTIFICATE-----`到`-----END CERTIFICATE-----`之间的部分复制下来保存即可（复制部分包括这两行）。 218 219### 预置应用级证书 220 221直接把证书原文件预置在APP中。目前支持crt和pem格式的证书文件。 222 223> **注意：** 224> 225> 当前ohos.net.http和Image组件的证书锁定，会匹配证书链上所有证书的哈希值，如果服务器更新了任意一本证书，都会导致校验失败。如果服务器出现了更新证书的情况，APP版本应当随之更新并推荐消费者尽快升级APP版本，否则可能导致联网失败。 226 227### 预置证书公钥哈希值 228 229通过在配置中指定域名证书公钥的哈希值来只允许使用公钥哈希值匹配的域名证书访问此域名。 230 231域名证书的公钥哈希值可以用如下的命令计算，这里假设域名证书是通过上面的OpenSSL命令获得的，并保存在`www.example.com.pem`文件。#开头的行是注释，可以不用输入： 232 233``` 234# 从证书中提取出公钥 235openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem 236# 将pem格式的公钥转换成der格式 237openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem -out www.example.com.pubkey.der 238# 计算公钥的SHA256并转换成base64编码 239openssl dgst -sha256 -binary www.example.com.pubkey.der | openssl base64 240``` 241 242### JSON配置文件示例 243 244预置应用级证书的配置例子如下： 245 246```json 247{ 248 "network-security-config": { 249 "base-config": { 250 "trust-anchors": [ 251 { 252 "certificates": "/etc/security/certificates" 253 } 254 ] 255 }, 256 "domain-config": [ 257 { 258 "domains": [ 259 { 260 "include-subdomains": true, 261 "name": "example.com" 262 } 263 ], 264 "trust-anchors": [ 265 { 266 "certificates": "/data/storage/el1/bundle/entry/resources/resfile" 267 } 268 ] 269 } 270 ] 271 } 272} 273``` 274 275预置证书公钥哈希值的配置例子如下： 276``` 277{ 278 "network-security-config": { 279 "domain-config": [ 280 { 281 "domains": [ 282 { 283 "include-subdomains": true, 284 "name": "server.com" 285 } 286 ], 287 "pin-set": { 288 "expiration": "2024-11-08", 289 "pin": [ 290 { 291 "digest-algorithm": "sha256", 292 "digest": "FEDCBA987654321" 293 } 294 ] 295 } 296 } 297 ] 298 } 299} 300``` 301 302**各个字段含义:** 303 304| 字段 | 类型 | 说明 | 305| --------------------------| --------------- | -------------------------------------- | 306|network-security-config | object |网络安全配置。可包含0或者1个base-config，必须包含1个domain-config。| 307|base-config | object |指示应用程序范围的安全配置。必须包含1个trust-anchors。 | 308|domain-config | array |指示每个域的安全配置。可以包含任意个item。item必须包含1个domains，可以包含0或者1个trust-anchors，可以包含0个或者1个pin-set。| 309|trust-anchors | array |受信任的CA。可以包含任意个item。item必须包含1个certificates。| 310|certificates | string |CA证书路径。 | 311|domains | array |域。可以包含任意个item。item必须包含1个name(string：指示域名)，可以包含0或者1个include-subdomains。| 312|include-subdomains | boolean |指示规则是否适用于子域。 | 313|pin-set | object |证书公钥哈希设置。必须包含1个pin，可以包含0或者1个expiration。| 314|expiration | string |指示证书公钥哈希的过期时间。 | 315|pin | array |证书公钥哈希。可以包含任意个item。item必须包含1个digest-algorithm，item必须包含1个digest。| 316|digest-algorithm | string |指示用于生成哈希的摘要算法。目前只支持`sha256`。 | 317|digest | string |指示公钥哈希。 | 318 319 320## 相关实例 321 322针对HTTP数据请求，有以下相关实例可供参考： 323 324- [上传和下载（ArkTS）(API10)](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Connectivity/UploadAndDownLoad) 325 326- [Http（ArkTS）（API10）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Connectivity/Http) 327