1# 数据请求 2 3> **说明：** 4> 5>本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 6> 7 8## 导入模块 9 10``` 11import http from '@ohos.net.http'; 12``` 13 14## 完整示例 15 16``` 17import http from '@ohos.net.http'; 18 19// 每一个httpRequest对应一个http请求任务，不可复用 20let httpRequest = http.createHttp(); 21// 用于订阅http响应头，此接口会比request请求先返回。可以根据业务需要订阅此消息 22// 从API 8开始，使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ 23httpRequest.on('headersReceive', (header) => { 24 console.info('header: ' + JSON.stringify(header)); 25}); 26httpRequest.request( 27 // 填写http请求的url地址，可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 28 "EXAMPLE_URL", 29 { 30 method: http.RequestMethod.POST, // 可选，默认为http.RequestMethod.GET 31 // 开发者根据自身业务需要添加header字段 32 header: { 33 'Content-Type': 'application/json' 34 }, 35 // 当使用POST请求时此字段用于传递内容 36 extraData: { 37 "data": "data to send", 38 }, 39 connectTimeout: 60000, // 可选，默认为60s 40 readTimeout: 60000, // 可选，默认为60s 41 }, (err, data) => { 42 if (!err) { 43 // data.result为http响应内容，可根据业务需要进行解析 44 console.info('Result:' + data.result); 45 console.info('code:' + data.responseCode); 46 // data.header为http响应头，可根据业务需要进行解析 47 console.info('header:' + JSON.stringify(data.header)); 48 console.info('cookies:' + data.cookies); // 8+ 49 } else { 50 console.info('error:' + JSON.stringify(err)); 51 // 当该请求使用完毕时，调用destroy方法主动销毁。 52 httpRequest.destroy(); 53 } 54 } 55); 56``` 57 58## http.createHttp 59 60createHttp\(\): HttpRequest 61 62创建一个http，里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header 事件。每一个HttpRequest对象对应一个Http请求。如需发起多个Http请求，须为每个Http请求创建对应HttpRequest对象。 63 64**系统能力**：SystemCapability.Communication.NetStack 65 66**返回值：** 67 68| 类型 | 说明 | 69| :---------- | :----------------------------------------------------------- | 70| HttpRequest | 返回一个HttpRequest对象，里面包括request、destroy、on和off方法。 | 71 72**示例：** 73 74``` 75import http from '@ohos.net.http'; 76let httpRequest = http.createHttp(); 77``` 78 79 80## HttpRequest 81 82http请求任务。在调用HttpRequest的方法前，需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 83 84### request 85 86request\(url: string, callback: AsyncCallback\<HttpResponse\>\):void 87 88根据URL地址，发起HTTP网络请求，使用callback方式作为异步方法。 89 90**需要权限**：ohos.permission.INTERNET 91 92**系统能力**：SystemCapability.Communication.NetStack 93 94**参数：** 95 96| 参数名 | 类型 | 必填 | 说明 | 97| -------- | ------------------------------------------------------- | ---- | ----------------------- | 98| url | string | 是 | 发起网络请求的URL地址。 | 99| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | 100 101**示例：** 102 103``` 104httpRequest.request("EXAMPLE_URL", (err, data) => { 105 if (!err) { 106 console.info('Result:' + data.result); 107 console.info('code:' + data.responseCode); 108 console.info('header:' + JSON.stringify(data.header)); 109 console.info('cookies:' + data.cookies); // 8+ 110 } else { 111 console.info('error:' + JSON.stringify(err)); 112 } 113}); 114``` 115 116### request 117 118request\(url: string, options: HttpRequestOptions, callback: AsyncCallback<HttpResponse\>\):void 119 120根据URL地址和相关配置项，发起HTTP网络请求，使用callback方式作为异步方法。 121 122**需要权限**：ohos.permission.INTERNET 123 124**系统能力**：SystemCapability.Communication.NetStack 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | 130| url | string | 是 | 发起网络请求的URL地址。 | 131| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | 132| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | 133 134**示例：** 135 136``` 137httpRequest.request("EXAMPLE_URL", 138{ 139 method: http.RequestMethod.GET, 140 header: { 141 'Content-Type': 'application/json' 142 }, 143 readTimeout: 60000, 144 connectTimeout: 60000 145}, (err, data) => { 146 if (!err) { 147 console.info('Result:' + data.result); 148 console.info('code:' + data.responseCode); 149 console.info('header:' + JSON.stringify(data.header)); 150 console.info('cookies:' + data.cookies); // 8+ 151 console.info('header.Content-Type:' + data.header['Content-Type']); 152 console.info('header.Status-Line:' + data.header['Status-Line']); 153 } else { 154 console.info('error:' + JSON.stringify(err)); 155 } 156}); 157``` 158 159 160### request 161 162request\(url: string, options? : HttpRequestOptions\): Promise<HttpResponse\> 163 164根据URL地址，发起HTTP网络请求，使用Promise方式作为异步方法。 165 166**需要权限**：ohos.permission.INTERNET 167 168**系统能力**：SystemCapability.Communication.NetStack 169 170**参数：** 171 172| 参数名 | 类型 | 必填 | 说明 | 173| ------- | ------------------ | ---- | -------------------------------------------------- | 174| url | string | 是 | 发起网络请求的URL地址。 | 175| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | 176 177**返回值：** 178 179| 类型 | 说明 | 180| :-------------------- | :-------------------------------- | 181| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | 182 183 184**示例：** 185 186``` 187let promise = httpRequest.request("EXAMPLE_URL", { 188 method: http.RequestMethod.GET, 189 connectTimeout: 60000, 190 readTimeout: 60000, 191 header: { 192 'Content-Type': 'application/json' 193 } 194}); 195promise.then((data) => { 196 console.info('Result:' + data.result); 197 console.info('code:' + data.responseCode); 198 console.info('header:' + JSON.stringify(data.header)); 199 console.info('cookies:' + data.cookies); // 8+ 200 console.info('header.Content-Type:' + data.header['Content-Type']); 201 console.info('header.Status-Line:' + data.header['Status-Line']); 202}).catch((err) => { 203 console.info('error:' + JSON.stringify(err)); 204}); 205``` 206 207### destroy 208 209destroy\(\): void 210 211中断请求任务。 212 213**系统能力**：SystemCapability.Communication.NetStack 214 215**示例：** 216 217``` 218httpRequest.destroy(); 219``` 220 221### on\('headerReceive'\) 222 223on\(type: 'headerReceive', callback: AsyncCallback<Object\>\): void 224 225订阅HTTP Response Header 事件。 226 227> **说明：** 228> 此接口已废弃，建议使用[on\('headersReceive'\)<sup>8+</sup>](#onheadersreceive8)替代。 229 230**系统能力**：SystemCapability.Communication.NetStack 231 232**参数：** 233 234| 参数名 | 类型 | 必填 | 说明 | 235| -------- | ----------------------- | ---- | --------------------------------- | 236| type | string | 是 | 订阅的事件类型，'headerReceive'。 | 237| callback | AsyncCallback\<Object\> | 是 | 回调函数。 | 238 239**示例：** 240 241``` 242httpRequest.on('headerReceive', (err, data) => { 243 if (!err) { 244 console.info('header: ' + JSON.stringify(data)); 245 } else { 246 console.info('error:' + JSON.stringify(err)); 247 } 248}); 249``` 250 251 252### off\('headerReceive'\) 253 254off\(type: 'headerReceive', callback?: AsyncCallback<Object\>\): void 255 256取消订阅HTTP Response Header 事件。 257 258> **说明：** 259> 260>1. 此接口已废弃，建议使用[off\('headersReceive'\)<sup>8+</sup>](#offheadersreceive8)替代。 261> 262>2. 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 263 264**系统能力**：SystemCapability.Communication.NetStack 265 266**参数：** 267 268| 参数名 | 类型 | 必填 | 说明 | 269| -------- | ----------------------- | ---- | ------------------------------------- | 270| type | string | 是 | 取消订阅的事件类型，'headerReceive'。 | 271| callback | AsyncCallback\<Object\> | 否 | 回调函数。 | 272 273**示例：** 274 275``` 276httpRequest.off('headerReceive'); 277``` 278 279### on\('headersReceive'\)<sup>8+</sup> 280 281on\(type: 'headersReceive', callback: Callback<Object\>\): void 282 283订阅HTTP Response Header 事件。 284 285**系统能力**：SystemCapability.Communication.NetStack 286 287**参数：** 288 289| 参数名 | 类型 | 必填 | 说明 | 290| -------- | ------------------ | ---- | ---------------------------------- | 291| type | string | 是 | 订阅的事件类型：'headersReceive'。 | 292| callback | Callback\<Object\> | 是 | 回调函数。 | 293 294**示例：** 295 296``` 297httpRequest.on('headersReceive', (header) => { 298 console.info('header: ' + JSON.stringify(header)); 299}); 300``` 301 302 303### off\('headersReceive'\)<sup>8+</sup> 304 305off\(type: 'headersReceive', callback?: Callback<Object\>\): void 306 307取消订阅HTTP Response Header 事件。 308 309> **说明：** 310>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 311 312**系统能力**：SystemCapability.Communication.NetStack 313 314**参数：** 315 316| 参数名 | 类型 | 必填 | 说明 | 317| -------- | ------------------ | ---- | -------------------------------------- | 318| type | string | 是 | 取消订阅的事件类型：'headersReceive'。 | 319| callback | Callback\<Object\> | 否 | 回调函数。 | 320 321**示例：** 322 323``` 324httpRequest.off('headersReceive'); 325``` 326 327### once\('headersReceive'\)<sup>8+</sup> 328 329once\(type: 'headersReceive', callback: Callback<Object\>\): void 330 331订阅HTTP Response Header 事件，但是只触发一次。一旦触发之后，订阅器就会被移除。使用callback方式作为异步方法。 332 333**系统能力**：SystemCapability.Communication.NetStack 334 335**参数：** 336 337| 参数名 | 类型 | 必填 | 说明 | 338| -------- | ------------------ | ---- | ---------------------------------- | 339| type | string | 是 | 订阅的事件类型：'headersReceive'。 | 340| callback | Callback\<Object\> | 是 | 回调函数。 | 341 342**示例：** 343 344``` 345httpRequest.once('headersReceive', (header) => { 346 console.info('header: ' + JSON.stringify(header)); 347}); 348``` 349 350## HttpRequestOptions 351 352发起请求可选参数的类型和取值范围。 353 354**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 355 356| 参数名 | 类型 | 必填 | 说明 | 357| -------------- | ------------------------------------ | ---- | ---------------------------------------------------------- | 358| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | 359| extraData | string \| Object \| ArrayBuffer<sup>8+</sup> | 否 | 发送请求的额外数据。<br />- 当HTTP请求为POST、PUT等方法时，此字段为HTTP请求的content。<br />- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时，此字段为HTTP请求的参数补充，参数内容会拼接到URL中进行发送。<sup>8+</sup><br />- 开发者传入string对象，开发者需要自行编码，将编码后的string传入。<sup>8+</sup> | 360| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | 361| readTimeout | number | 否 | 读取超时时间。单位为毫秒（ms），默认为60000ms。 | 362| connectTimeout | number | 否 | 连接超时时间。单位为毫秒（ms），默认为60000ms。 | 363 364## RequestMethod 365 366HTTP 请求方法。 367 368**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 369 370| 名称 | 值 | 说明 | 371| :------ | ------- | :------------------ | 372| OPTIONS | OPTIONS | HTTP 请求 OPTIONS。 | 373| GET | GET | HTTP 请求 GET。 | 374| HEAD | HEAD | HTTP 请求 HEAD。 | 375| POST | POST | HTTP 请求 POST。 | 376| PUT | PUT | HTTP 请求 PUT。 | 377| DELETE | DELETE | HTTP 请求 DELETE。 | 378| TRACE | TRACE | HTTP 请求 TRACE。 | 379| CONNECT | CONNECT | HTTP 请求 CONNECT。 | 380 381## ResponseCode 382 383发起请求返回的响应码。 384 385**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 386 387| 名称 | 值 | 说明 | 388| ----------------- | ---- | ------------------------------------------------------------ | 389| OK | 200 | 请求成功。一般用于GET与POST请求。 | 390| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | 391| ACCEPTED | 202 | 已接受。已经接受请求，但未处理完成。 | 392| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | 393| NO_CONTENT | 204 | 无内容。服务器成功处理，但未返回内容。 | 394| RESET | 205 | 重置内容。 | 395| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | 396| MULT_CHOICE | 300 | 多种选择。 | 397| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI，返回信息会包括新的URI，浏览器会自动定向到新URI。 | 398| MOVED_TEMP | 302 | 临时移动。 | 399| SEE_OTHER | 303 | 查看其它地址。 | 400| NOT_MODIFIED | 304 | 未修改。 | 401| USE_PROXY | 305 | 使用代理。 | 402| BAD_REQUEST | 400 | 客户端请求的语法错误，服务器无法理解。 | 403| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | 404| PAYMENT_REQUIRED | 402 | 保留，将来使用。 | 405| FORBIDDEN | 403 | 服务器理解请求客户端的请求，但是拒绝执行此请求。 | 406| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源（网页）。 | 407| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | 408| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | 409| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | 410| CLIENT_TIMEOUT | 408 | 请求时间过长，超时。 | 411| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码，服务器处理请求时发生了冲突。 | 412| GONE | 410 | 客户端请求的资源已经不存在。 | 413| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | 414| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | 415| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大，服务器无法处理，因此拒绝请求。 | 416| REQ_TOO_LONG | 414 | 请求的URI过长（URI通常为网址），服务器无法处理。 | 417| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | 418| INTERNAL_ERROR | 500 | 服务器内部错误，无法完成请求。 | 419| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能，无法完成请求。 | 420| BAD_GATEWAY | 502 | 充当网关或代理的服务器，从远端服务器接收到了一个无效的请求。 | 421| UNAVAILABLE | 503 | 由于超载或系统维护，服务器暂时的无法处理客户端的请求。 | 422| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器，未及时从远端服务器获取请求。 | 423| VERSION | 505 | 服务器请求的HTTP协议的版本。 | 424 425## HttpResponse 426 427request方法回调函数的返回值类型。 428 429**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 430 431| 参数名 | 类型 | 必填 | 说明 | 432| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 433| result | string \| Object \| ArrayBuffer<sup>8+</sup> | 是 | Http请求根据响应头中Content-type类型返回对应的响应格式内容：<br />- application/json：返回JSON格式的字符串，如需Http响应具体内容，需开发者自行解析<br />- application/octet-stream：ArrayBuffer<br />- 其他：string | 434| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时，此字段为[ResponseCode](#responsecode)。若执行失败，错误码将会从AsyncCallback中的err字段返回。错误码如下：<br />- 200：通用错误<br />- 202：参数错误<br />- 300：I/O错误 | 435| header | Object | 是 | 发起http请求返回来的响应头。当前返回的是JSON格式字符串，如需具体字段内容，需开发者自行解析。常见字段及解析方式如下：<br/>- Content-Type：header['Content-Type']；<br />- Status-Line：header['Status-Line']；<br />- Date：header.Date/header['Date']；<br />- Server：header.Server/header['Server']； | 436| cookies<sup>8+</sup> | Array\<string\> | 是 | 服务器返回的 cookies。 | 437 438
