From ddf32b8b2046a6cc60d2c3c422b37edabebac934 Mon Sep 17 00:00:00 2001 From: Yangys Date: Wed, 8 Feb 2023 20:50:13 +0800 Subject: [PATCH] Update ErrorCode Signed-off-by: Yangys --- .../apis/js-apis-http_20230208193051.md | 906 ++++++++++++++ .../apis/js-apis-http_20230208200756.md | 906 ++++++++++++++ .../apis/js-apis-http_20230208202129.md | 913 ++++++++++++++ .../apis/js-apis-http_20230208202435.md | 928 ++++++++++++++ .../apis/js-apis-http_20230208202829.md | 933 +++++++++++++++ .../apis/js-apis-http_20230208202830.md | 933 +++++++++++++++ .../apis/js-apis-http_20230208202845.md | 932 ++++++++++++++ .../apis/js-apis-http_20230208203329.md | 987 +++++++++++++++ .../apis/js-apis-http_20230208203943.md | 1066 +++++++++++++++++ .../apis/js-apis-http_20230208204504.md | 926 ++++++++++++++ .../apis/js-apis-http_20230208204945.md | 771 ++++++++++++ .../apis/js-apis-http_20230208204946.md | 771 ++++++++++++ .../reference/apis/js-apis-http.md | 373 ++---- 13 files changed, 11091 insertions(+), 254 deletions(-) create mode 100755 .history/zh-cn/application-dev/reference/apis/js-apis-http_20230208193051.md create mode 100755 .history/zh-cn/application-dev/reference/apis/js-apis-http_20230208200756.md create mode 100755 .history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202129.md create mode 100755 .history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202435.md create mode 100755 .history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202829.md create mode 100755 .history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202830.md create mode 100755 .history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202845.md create mode 100755 .history/zh-cn/application-dev/reference/apis/js-apis-http_20230208203329.md create mode 100755 .history/zh-cn/application-dev/reference/apis/js-apis-http_20230208203943.md create mode 100755 .history/zh-cn/application-dev/reference/apis/js-apis-http_20230208204504.md create mode 100755 .history/zh-cn/application-dev/reference/apis/js-apis-http_20230208204945.md create mode 100755 .history/zh-cn/application-dev/reference/apis/js-apis-http_20230208204946.md diff --git a/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208193051.md b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208193051.md new file mode 100755 index 0000000000..dd8a5784ef --- /dev/null +++ b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208193051.md @@ -0,0 +1,906 @@ +# @ohos.net.http (数据请求) + +本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 + +>**说明:** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> + +## 导入模块 + +```js +import http from '@ohos.net.http'; +``` + +## 完整示例 + +```js +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个HTTP请求任务,不可复用 +let httpRequest = http.createHttp(); +// 用于订阅HTTP响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +httpRequest.request( + // 填写HTTP请求的URL地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + extraData: { + "data": "data to send", + }, + expectDataType: http.HttpDataType.STRING, // 可选,指定返回数据的类型 + usingCache: true, // 可选,默认为true + priority: 1, // 可选,默认为1 + connectTimeout: 60000, // 可选,默认为60000ms + readTimeout: 60000, // 可选,默认为60000ms + usingProtocol: http.HttpProtocol.HTTP1_1, // 可选,协议类型默认值由系统自动指定 + }, (err, data) => { + if (!err) { + // data.result为HTTP响应内容,可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为HTTP响应头,可根据业务需要进行解析 + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + // 当该请求使用完毕时,调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个HTTP请求,里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header事件。每一个HttpRequest对象对应一个HTTP请求。如需发起多个HTTP请求,须为每个HTTP请求创建对应HttpRequest对象。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| HttpRequest | 返回一个HttpRequest对象,里面包括request、destroy、on和off方法。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2100002 | System internal error. | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpRequest = http.createHttp(); +``` + +## HttpRequest + +HTTP请求任务。在调用HttpRequest的方法前,需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", +{ + method: http.RequestMethod.GET, + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 +}, (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址,发起HTTP网络请求,使用Promise方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------ | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 否 | 参考[HttpRequestOptions](#httprequestoptions)。 | + +**返回值:** + +| 类型 | 说明 | +| :------------------------------------- | :-------------------------------- | +| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +let promise = httpRequest.request("EXAMPLE_URL", { + method: http.RequestMethod.GET, + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } +}); +promise.then((data) => { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); +}).catch((err) => { + console.info('error:' + JSON.stringify(err)); +}); +``` + +### destroy + +destroy\(\): void + +中断请求任务。 + +**系统能力**:SystemCapability.Communication.NetStack + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.destroy(); +``` + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\): void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>此接口已废弃,建议使用[on\('headersReceive'\)8+](#onheadersreceive8)替代。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | --------------------------------- | +| type | string | 是 | 订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + JSON.stringify(data)); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +> +>1. 此接口已废弃,建议使用[off\('headersReceive'\)8+](#offheadersreceive8)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------- | +| type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headerReceive'); +``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | -------------------------------------- | +| type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headersReceive'); +``` + +### once\('headersReceive'\)8+ + +once\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件,但是只触发一次。一旦触发之后,订阅器就会被移除。使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.once('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer6+ | 否 | 发送请求的额外数据。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。6+
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。6+ | +| expectDataType9+ | [HttpDataType](#httpdatatype9) | 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 | +| usingCache9+ | boolean | 否 | 是否使用缓存,默认为true。 | +| priority9+ | number | 否 | 优先级,范围\[1,1000],默认是1。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 | +| usingProtocol9+ | [HttpProtocol](#httpprotocol9) | 否 | 使用协议。默认值由系统自动指定。 | + +## RequestMethod + +HTTP 请求方法。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| :------ | ------- | :------------------ | +| OPTIONS | "OPTIONS" | HTTP 请求 OPTIONS。 | +| GET | "GET" | HTTP 请求 GET。 | +| HEAD | "HEAD" | HTTP 请求 HEAD。 | +| POST | "POST" | HTTP 请求 POST。 | +| PUT | "PUT" | HTTP 请求 PUT。 | +| DELETE | "DELETE" | HTTP 请求 DELETE。 | +| TRACE | "TRACE" | HTTP 请求 TRACE。 | +| CONNECT | "CONNECT" | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求,但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理,但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误,服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留,将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求,但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源(网页)。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长,超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大,服务器无法处理,因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长(URI通常为网址),服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误,无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能,无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护,服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器,未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer6+ | 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string | +| resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | +| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时,此字段为[ResponseCode](#responsecode)。若执行失败,错误码将会从AsyncCallback中的err字段返回。 | +| header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server']; | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +## http.createHttpResponseCache9+ + +createHttpResponseCache(cacheSize?: number): HttpResponseCache + +创建一个默认的对象来存储HTTP访问请求的响应。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| cacheSize | number | 否 | 缓存大小最大为10\*1024\*1024(10MB),默认最大。 | + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| [HttpResponseCache](#httpresponsecache9) | 返回一个存储HTTP访问请求响应的对象。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpResponseCache = http.createHttpResponseCache(); +``` + +## HttpResponseCache9+ + +存储HTTP访问请求响应的对象。 + +### flush9+ + +flush(callback: AsyncCallback\): void + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush(err => { + if (err) { + console.log('flush fail'); + return; + } + console.log('flush success'); +}); +``` + +### flush9+ + +flush(): Promise\ + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\> | 以Promise形式返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush().then(() => { + console.log('flush success'); +}).catch(err => { + console.log('flush fail'); +}); +``` + +### delete9+ + +delete(callback: AsyncCallback\): void + +禁用缓存并删除其中的数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回删除结果。| + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete(err => { + if (err) { + console.log('delete fail'); + return; + } + console.log('delete success'); +}); +``` +### delete9+ + +delete(): Promise\ + +禁用缓存并删除其中的数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回删除结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete().then(() => { + console.log('delete success'); +}).catch(err => { + console.log('delete fail'); +}); +``` + +## HttpDataType9+ + +http的数据类型。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 值 | 说明 | +| ------------------ | -- | ----------- | +| STRING | 0 | 字符串类型。 | +| OBJECT | 1 | 对象类型。 | +| ARRAY_BUFFER | 2 | 二进制数组类型。| + +## HttpProtocol9+ + +http协议版本。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 说明 | +| :-------- | :----------- | +| HTTP1_1 | 协议http1.1 | +| HTTP2 | 协议http2 | diff --git a/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208200756.md b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208200756.md new file mode 100755 index 0000000000..ea5e06ae3b --- /dev/null +++ b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208200756.md @@ -0,0 +1,906 @@ +# @ohos.net.http (数据请求) + +本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 + +>**说明:** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> + +## 导入模块 + +```js +import http from '@ohos.net.http'; +``` + +## 完整示例 + +```js +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个HTTP请求任务,不可复用 +let httpRequest = http.createHttp(); +// 用于订阅HTTP响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +httpRequest.request( + // 填写HTTP请求的URL地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + extraData: { + "data": "data to send", + }, + expectDataType: http.HttpDataType.STRING, // 可选,指定返回数据的类型 + usingCache: true, // 可选,默认为true + priority: 1, // 可选,默认为1 + connectTimeout: 60000, // 可选,默认为60000ms + readTimeout: 60000, // 可选,默认为60000ms + usingProtocol: http.HttpProtocol.HTTP1_1, // 可选,协议类型默认值由系统自动指定 + }, (err, data) => { + if (!err) { + // data.result为HTTP响应内容,可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为HTTP响应头,可根据业务需要进行解析 + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + // 当该请求使用完毕时,调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个HTTP请求,里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header事件。每一个HttpRequest对象对应一个HTTP请求。如需发起多个HTTP请求,须为每个HTTP请求创建对应HttpRequest对象。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| HttpRequest | 返回一个HttpRequest对象,里面包括request、destroy、on和off方法。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2100002 | System internal error. | +| 2300999 | Unknown Other Error。 | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpRequest = http.createHttp(); +``` + +## HttpRequest + +HTTP请求任务。在调用HttpRequest的方法前,需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", +{ + method: http.RequestMethod.GET, + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 +}, (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址,发起HTTP网络请求,使用Promise方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------ | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 否 | 参考[HttpRequestOptions](#httprequestoptions)。 | + +**返回值:** + +| 类型 | 说明 | +| :------------------------------------- | :-------------------------------- | +| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +let promise = httpRequest.request("EXAMPLE_URL", { + method: http.RequestMethod.GET, + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } +}); +promise.then((data) => { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); +}).catch((err) => { + console.info('error:' + JSON.stringify(err)); +}); +``` + +### destroy + +destroy\(\): void + +中断请求任务。 + +**系统能力**:SystemCapability.Communication.NetStack + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.destroy(); +``` + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\): void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>此接口已废弃,建议使用[on\('headersReceive'\)8+](#onheadersreceive8)替代。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | --------------------------------- | +| type | string | 是 | 订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + JSON.stringify(data)); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +> +>1. 此接口已废弃,建议使用[off\('headersReceive'\)8+](#offheadersreceive8)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------- | +| type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headerReceive'); +``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | -------------------------------------- | +| type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headersReceive'); +``` + +### once\('headersReceive'\)8+ + +once\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件,但是只触发一次。一旦触发之后,订阅器就会被移除。使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.once('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer6+ | 否 | 发送请求的额外数据。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。6+
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。6+ | +| expectDataType9+ | [HttpDataType](#httpdatatype9) | 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 | +| usingCache9+ | boolean | 否 | 是否使用缓存,默认为true。 | +| priority9+ | number | 否 | 优先级,范围\[1,1000],默认是1。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 | +| usingProtocol9+ | [HttpProtocol](#httpprotocol9) | 否 | 使用协议。默认值由系统自动指定。 | + +## RequestMethod + +HTTP 请求方法。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| :------ | ------- | :------------------ | +| OPTIONS | "OPTIONS" | HTTP 请求 OPTIONS。 | +| GET | "GET" | HTTP 请求 GET。 | +| HEAD | "HEAD" | HTTP 请求 HEAD。 | +| POST | "POST" | HTTP 请求 POST。 | +| PUT | "PUT" | HTTP 请求 PUT。 | +| DELETE | "DELETE" | HTTP 请求 DELETE。 | +| TRACE | "TRACE" | HTTP 请求 TRACE。 | +| CONNECT | "CONNECT" | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求,但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理,但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误,服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留,将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求,但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源(网页)。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长,超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大,服务器无法处理,因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长(URI通常为网址),服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误,无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能,无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护,服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器,未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer6+ | 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string | +| resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | +| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时,此字段为[ResponseCode](#responsecode)。若执行失败,错误码将会从AsyncCallback中的err字段返回。 | +| header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server']; | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +## http.createHttpResponseCache9+ + +createHttpResponseCache(cacheSize?: number): HttpResponseCache + +创建一个默认的对象来存储HTTP访问请求的响应。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| cacheSize | number | 否 | 缓存大小最大为10\*1024\*1024(10MB),默认最大。 | + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| [HttpResponseCache](#httpresponsecache9) | 返回一个存储HTTP访问请求响应的对象。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpResponseCache = http.createHttpResponseCache(); +``` + +## HttpResponseCache9+ + +存储HTTP访问请求响应的对象。 + +### flush9+ + +flush(callback: AsyncCallback\): void + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush(err => { + if (err) { + console.log('flush fail'); + return; + } + console.log('flush success'); +}); +``` + +### flush9+ + +flush(): Promise\ + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\> | 以Promise形式返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush().then(() => { + console.log('flush success'); +}).catch(err => { + console.log('flush fail'); +}); +``` + +### delete9+ + +delete(callback: AsyncCallback\): void + +禁用缓存并删除其中的数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回删除结果。| + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete(err => { + if (err) { + console.log('delete fail'); + return; + } + console.log('delete success'); +}); +``` +### delete9+ + +delete(): Promise\ + +禁用缓存并删除其中的数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回删除结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete().then(() => { + console.log('delete success'); +}).catch(err => { + console.log('delete fail'); +}); +``` + +## HttpDataType9+ + +http的数据类型。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 值 | 说明 | +| ------------------ | -- | ----------- | +| STRING | 0 | 字符串类型。 | +| OBJECT | 1 | 对象类型。 | +| ARRAY_BUFFER | 2 | 二进制数组类型。| + +## HttpProtocol9+ + +http协议版本。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 说明 | +| :-------- | :----------- | +| HTTP1_1 | 协议http1.1 | +| HTTP2 | 协议http2 | diff --git a/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202129.md b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202129.md new file mode 100755 index 0000000000..082032a82d --- /dev/null +++ b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202129.md @@ -0,0 +1,913 @@ +# @ohos.net.http (数据请求) + +本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 + +>**说明:** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> + +## 导入模块 + +```js +import http from '@ohos.net.http'; +``` + +## 完整示例 + +```js +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个HTTP请求任务,不可复用 +let httpRequest = http.createHttp(); +// 用于订阅HTTP响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +httpRequest.request( + // 填写HTTP请求的URL地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + extraData: { + "data": "data to send", + }, + expectDataType: http.HttpDataType.STRING, // 可选,指定返回数据的类型 + usingCache: true, // 可选,默认为true + priority: 1, // 可选,默认为1 + connectTimeout: 60000, // 可选,默认为60000ms + readTimeout: 60000, // 可选,默认为60000ms + usingProtocol: http.HttpProtocol.HTTP1_1, // 可选,协议类型默认值由系统自动指定 + }, (err, data) => { + if (!err) { + // data.result为HTTP响应内容,可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为HTTP响应头,可根据业务需要进行解析 + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + // 当该请求使用完毕时,调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个HTTP请求,里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header事件。每一个HttpRequest对象对应一个HTTP请求。如需发起多个HTTP请求,须为每个HTTP请求创建对应HttpRequest对象。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| HttpRequest | 返回一个HttpRequest对象,里面包括request、destroy、on和off方法。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpRequest = http.createHttp(); +``` + +## HttpRequest + +HTTP请求任务。在调用HttpRequest的方法前,需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300999 | Unknown Other Error. | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", +{ + method: http.RequestMethod.GET, + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 +}, (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址,发起HTTP网络请求,使用Promise方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------ | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 否 | 参考[HttpRequestOptions](#httprequestoptions)。 | + +**返回值:** + +| 类型 | 说明 | +| :------------------------------------- | :-------------------------------- | +| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300009 | Access denied to remote resource | +| 2300025 | Upload failed | +| 2300028 | Timeout was reached | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +let promise = httpRequest.request("EXAMPLE_URL", { + method: http.RequestMethod.GET, + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } +}); +promise.then((data) => { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); +}).catch((err) => { + console.info('error:' + JSON.stringify(err)); +}); +``` + +### destroy + +destroy\(\): void + +中断请求任务。 + +**系统能力**:SystemCapability.Communication.NetStack + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.destroy(); +``` + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\): void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>此接口已废弃,建议使用[on\('headersReceive'\)8+](#onheadersreceive8)替代。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | --------------------------------- | +| type | string | 是 | 订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + JSON.stringify(data)); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +> +>1. 此接口已废弃,建议使用[off\('headersReceive'\)8+](#offheadersreceive8)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------- | +| type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headerReceive'); +``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | -------------------------------------- | +| type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headersReceive'); +``` + +### once\('headersReceive'\)8+ + +once\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件,但是只触发一次。一旦触发之后,订阅器就会被移除。使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.once('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer6+ | 否 | 发送请求的额外数据。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。6+
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。6+ | +| expectDataType9+ | [HttpDataType](#httpdatatype9) | 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 | +| usingCache9+ | boolean | 否 | 是否使用缓存,默认为true。 | +| priority9+ | number | 否 | 优先级,范围\[1,1000],默认是1。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 | +| usingProtocol9+ | [HttpProtocol](#httpprotocol9) | 否 | 使用协议。默认值由系统自动指定。 | + +## RequestMethod + +HTTP 请求方法。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| :------ | ------- | :------------------ | +| OPTIONS | "OPTIONS" | HTTP 请求 OPTIONS。 | +| GET | "GET" | HTTP 请求 GET。 | +| HEAD | "HEAD" | HTTP 请求 HEAD。 | +| POST | "POST" | HTTP 请求 POST。 | +| PUT | "PUT" | HTTP 请求 PUT。 | +| DELETE | "DELETE" | HTTP 请求 DELETE。 | +| TRACE | "TRACE" | HTTP 请求 TRACE。 | +| CONNECT | "CONNECT" | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求,但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理,但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误,服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留,将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求,但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源(网页)。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长,超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大,服务器无法处理,因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长(URI通常为网址),服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误,无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能,无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护,服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器,未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer6+ | 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string | +| resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | +| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时,此字段为[ResponseCode](#responsecode)。若执行失败,错误码将会从AsyncCallback中的err字段返回。 | +| header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server']; | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +## http.createHttpResponseCache9+ + +createHttpResponseCache(cacheSize?: number): HttpResponseCache + +创建一个默认的对象来存储HTTP访问请求的响应。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| cacheSize | number | 否 | 缓存大小最大为10\*1024\*1024(10MB),默认最大。 | + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| [HttpResponseCache](#httpresponsecache9) | 返回一个存储HTTP访问请求响应的对象。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpResponseCache = http.createHttpResponseCache(); +``` + +## HttpResponseCache9+ + +存储HTTP访问请求响应的对象。 + +### flush9+ + +flush(callback: AsyncCallback\): void + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush(err => { + if (err) { + console.log('flush fail'); + return; + } + console.log('flush success'); +}); +``` + +### flush9+ + +flush(): Promise\ + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\> | 以Promise形式返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush().then(() => { + console.log('flush success'); +}).catch(err => { + console.log('flush fail'); +}); +``` + +### delete9+ + +delete(callback: AsyncCallback\): void + +禁用缓存并删除其中的数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回删除结果。| + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete(err => { + if (err) { + console.log('delete fail'); + return; + } + console.log('delete success'); +}); +``` +### delete9+ + +delete(): Promise\ + +禁用缓存并删除其中的数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回删除结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete().then(() => { + console.log('delete success'); +}).catch(err => { + console.log('delete fail'); +}); +``` + +## HttpDataType9+ + +http的数据类型。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 值 | 说明 | +| ------------------ | -- | ----------- | +| STRING | 0 | 字符串类型。 | +| OBJECT | 1 | 对象类型。 | +| ARRAY_BUFFER | 2 | 二进制数组类型。| + +## HttpProtocol9+ + +http协议版本。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 说明 | +| :-------- | :----------- | +| HTTP1_1 | 协议http1.1 | +| HTTP2 | 协议http2 | diff --git a/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202435.md b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202435.md new file mode 100755 index 0000000000..a8ae8e90d6 --- /dev/null +++ b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202435.md @@ -0,0 +1,928 @@ +# @ohos.net.http (数据请求) + +本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 + +>**说明:** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> + +## 导入模块 + +```js +import http from '@ohos.net.http'; +``` + +## 完整示例 + +```js +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个HTTP请求任务,不可复用 +let httpRequest = http.createHttp(); +// 用于订阅HTTP响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +httpRequest.request( + // 填写HTTP请求的URL地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + extraData: { + "data": "data to send", + }, + expectDataType: http.HttpDataType.STRING, // 可选,指定返回数据的类型 + usingCache: true, // 可选,默认为true + priority: 1, // 可选,默认为1 + connectTimeout: 60000, // 可选,默认为60000ms + readTimeout: 60000, // 可选,默认为60000ms + usingProtocol: http.HttpProtocol.HTTP1_1, // 可选,协议类型默认值由系统自动指定 + }, (err, data) => { + if (!err) { + // data.result为HTTP响应内容,可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为HTTP响应头,可根据业务需要进行解析 + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + // 当该请求使用完毕时,调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个HTTP请求,里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header事件。每一个HttpRequest对象对应一个HTTP请求。如需发起多个HTTP请求,须为每个HTTP请求创建对应HttpRequest对象。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| HttpRequest | 返回一个HttpRequest对象,里面包括request、destroy、on和off方法。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpRequest = http.createHttp(); +``` + +## HttpRequest + +HTTP请求任务。在调用HttpRequest的方法前,需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", +{ + method: http.RequestMethod.GET, + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 +}, (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址,发起HTTP网络请求,使用Promise方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------ | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 否 | 参考[HttpRequestOptions](#httprequestoptions)。 | + +**返回值:** + +| 类型 | 说明 | +| :------------------------------------- | :-------------------------------- | +| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300009 | Access denied to remote resource | +| 2300025 | Upload failed | +| 2300028 | Timeout was reached | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +let promise = httpRequest.request("EXAMPLE_URL", { + method: http.RequestMethod.GET, + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } +}); +promise.then((data) => { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); +}).catch((err) => { + console.info('error:' + JSON.stringify(err)); +}); +``` + +### destroy + +destroy\(\): void + +中断请求任务。 + +**系统能力**:SystemCapability.Communication.NetStack + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.destroy(); +``` + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\): void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>此接口已废弃,建议使用[on\('headersReceive'\)8+](#onheadersreceive8)替代。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | --------------------------------- | +| type | string | 是 | 订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + JSON.stringify(data)); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +> +>1. 此接口已废弃,建议使用[off\('headersReceive'\)8+](#offheadersreceive8)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------- | +| type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headerReceive'); +``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | -------------------------------------- | +| type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headersReceive'); +``` + +### once\('headersReceive'\)8+ + +once\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件,但是只触发一次。一旦触发之后,订阅器就会被移除。使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.once('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer6+ | 否 | 发送请求的额外数据。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。6+
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。6+ | +| expectDataType9+ | [HttpDataType](#httpdatatype9) | 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 | +| usingCache9+ | boolean | 否 | 是否使用缓存,默认为true。 | +| priority9+ | number | 否 | 优先级,范围\[1,1000],默认是1。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 | +| usingProtocol9+ | [HttpProtocol](#httpprotocol9) | 否 | 使用协议。默认值由系统自动指定。 | + +## RequestMethod + +HTTP 请求方法。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| :------ | ------- | :------------------ | +| OPTIONS | "OPTIONS" | HTTP 请求 OPTIONS。 | +| GET | "GET" | HTTP 请求 GET。 | +| HEAD | "HEAD" | HTTP 请求 HEAD。 | +| POST | "POST" | HTTP 请求 POST。 | +| PUT | "PUT" | HTTP 请求 PUT。 | +| DELETE | "DELETE" | HTTP 请求 DELETE。 | +| TRACE | "TRACE" | HTTP 请求 TRACE。 | +| CONNECT | "CONNECT" | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求,但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理,但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误,服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留,将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求,但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源(网页)。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长,超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大,服务器无法处理,因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长(URI通常为网址),服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误,无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能,无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护,服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器,未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer6+ | 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string | +| resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | +| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时,此字段为[ResponseCode](#responsecode)。若执行失败,错误码将会从AsyncCallback中的err字段返回。 | +| header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server']; | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +## http.createHttpResponseCache9+ + +createHttpResponseCache(cacheSize?: number): HttpResponseCache + +创建一个默认的对象来存储HTTP访问请求的响应。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| cacheSize | number | 否 | 缓存大小最大为10\*1024\*1024(10MB),默认最大。 | + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| [HttpResponseCache](#httpresponsecache9) | 返回一个存储HTTP访问请求响应的对象。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpResponseCache = http.createHttpResponseCache(); +``` + +## HttpResponseCache9+ + +存储HTTP访问请求响应的对象。 + +### flush9+ + +flush(callback: AsyncCallback\): void + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush(err => { + if (err) { + console.log('flush fail'); + return; + } + console.log('flush success'); +}); +``` + +### flush9+ + +flush(): Promise\ + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\> | 以Promise形式返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush().then(() => { + console.log('flush success'); +}).catch(err => { + console.log('flush fail'); +}); +``` + +### delete9+ + +delete(callback: AsyncCallback\): void + +禁用缓存并删除其中的数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回删除结果。| + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete(err => { + if (err) { + console.log('delete fail'); + return; + } + console.log('delete success'); +}); +``` +### delete9+ + +delete(): Promise\ + +禁用缓存并删除其中的数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回删除结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete().then(() => { + console.log('delete success'); +}).catch(err => { + console.log('delete fail'); +}); +``` + +## HttpDataType9+ + +http的数据类型。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 值 | 说明 | +| ------------------ | -- | ----------- | +| STRING | 0 | 字符串类型。 | +| OBJECT | 1 | 对象类型。 | +| ARRAY_BUFFER | 2 | 二进制数组类型。| + +## HttpProtocol9+ + +http协议版本。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 说明 | +| :-------- | :----------- | +| HTTP1_1 | 协议http1.1 | +| HTTP2 | 协议http2 | diff --git a/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202829.md b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202829.md new file mode 100755 index 0000000000..2d0e5ab0cc --- /dev/null +++ b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202829.md @@ -0,0 +1,933 @@ +# @ohos.net.http (数据请求) + +本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 + +>**说明:** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> + +## 导入模块 + +```js +import http from '@ohos.net.http'; +``` + +## 完整示例 + +```js +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个HTTP请求任务,不可复用 +let httpRequest = http.createHttp(); +// 用于订阅HTTP响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +httpRequest.request( + // 填写HTTP请求的URL地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + extraData: { + "data": "data to send", + }, + expectDataType: http.HttpDataType.STRING, // 可选,指定返回数据的类型 + usingCache: true, // 可选,默认为true + priority: 1, // 可选,默认为1 + connectTimeout: 60000, // 可选,默认为60000ms + readTimeout: 60000, // 可选,默认为60000ms + usingProtocol: http.HttpProtocol.HTTP1_1, // 可选,协议类型默认值由系统自动指定 + }, (err, data) => { + if (!err) { + // data.result为HTTP响应内容,可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为HTTP响应头,可根据业务需要进行解析 + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + // 当该请求使用完毕时,调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个HTTP请求,里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header事件。每一个HttpRequest对象对应一个HTTP请求。如需发起多个HTTP请求,须为每个HTTP请求创建对应HttpRequest对象。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| HttpRequest | 返回一个HttpRequest对象,里面包括request、destroy、on和off方法。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpRequest = http.createHttp(); +``` + +## HttpRequest + +HTTP请求任务。在调用HttpRequest的方法前,需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", +{ + method: http.RequestMethod.GET, + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 +}, (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址,发起HTTP网络请求,使用Promise方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------ | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 否 | 参考[HttpRequestOptions](#httprequestoptions)。 | + +**返回值:** + +| 类型 | 说明 | +| :------------------------------------- | :-------------------------------- | +| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300009 | Access denied to remote resource | +| 2300025 | Upload failed | +| 2300028 | Timeout was reached | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +let promise = httpRequest.request("EXAMPLE_URL", { + method: http.RequestMethod.GET, + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } +}); +promise.then((data) => { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); +}).catch((err) => { + console.info('error:' + JSON.stringify(err)); +}); +``` + +### destroy + +destroy\(\): void + +中断请求任务。 + +**系统能力**:SystemCapability.Communication.NetStack + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.destroy(); +``` + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\): void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>此接口已废弃,建议使用[on\('headersReceive'\)8+](#onheadersreceive8)替代。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | --------------------------------- | +| type | string | 是 | 订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + JSON.stringify(data)); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +> +>1. 此接口已废弃,建议使用[off\('headersReceive'\)8+](#offheadersreceive8)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------- | +| type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headerReceive'); +``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | -------------------------------------- | +| type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headersReceive'); +``` + +### once\('headersReceive'\)8+ + +once\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件,但是只触发一次。一旦触发之后,订阅器就会被移除。使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.once('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer6+ | 否 | 发送请求的额外数据。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。6+
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。6+ | +| expectDataType9+ | [HttpDataType](#httpdatatype9) | 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 | +| usingCache9+ | boolean | 否 | 是否使用缓存,默认为true。 | +| priority9+ | number | 否 | 优先级,范围\[1,1000],默认是1。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 | +| usingProtocol9+ | [HttpProtocol](#httpprotocol9) | 否 | 使用协议。默认值由系统自动指定。 | + +## RequestMethod + +HTTP 请求方法。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| :------ | ------- | :------------------ | +| OPTIONS | "OPTIONS" | HTTP 请求 OPTIONS。 | +| GET | "GET" | HTTP 请求 GET。 | +| HEAD | "HEAD" | HTTP 请求 HEAD。 | +| POST | "POST" | HTTP 请求 POST。 | +| PUT | "PUT" | HTTP 请求 PUT。 | +| DELETE | "DELETE" | HTTP 请求 DELETE。 | +| TRACE | "TRACE" | HTTP 请求 TRACE。 | +| CONNECT | "CONNECT" | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求,但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理,但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误,服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留,将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求,但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源(网页)。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长,超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大,服务器无法处理,因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长(URI通常为网址),服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误,无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能,无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护,服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器,未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer6+ | 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string | +| resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | +| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时,此字段为[ResponseCode](#responsecode)。若执行失败,错误码将会从AsyncCallback中的err字段返回。 | +| header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server']; | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +## http.createHttpResponseCache9+ + +createHttpResponseCache(cacheSize?: number): HttpResponseCache + +创建一个默认的对象来存储HTTP访问请求的响应。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| cacheSize | number | 否 | 缓存大小最大为10\*1024\*1024(10MB),默认最大。 | + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| [HttpResponseCache](#httpresponsecache9) | 返回一个存储HTTP访问请求响应的对象。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpResponseCache = http.createHttpResponseCache(); +``` + +## HttpResponseCache9+ + +存储HTTP访问请求响应的对象。 + +### flush9+ + +flush(callback: AsyncCallback\): void + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush(err => { + if (err) { + console.log('flush fail'); + return; + } + console.log('flush success'); +}); +``` + +### flush9+ + +flush(): Promise\ + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\> | 以Promise形式返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush().then(() => { + console.log('flush success'); +}).catch(err => { + console.log('flush fail'); +}); +``` + +### delete9+ + +delete(callback: AsyncCallback\): void + +禁用缓存并删除其中的数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回删除结果。| + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete(err => { + if (err) { + console.log('delete fail'); + return; + } + console.log('delete success'); +}); +``` +### delete9+ + +delete(): Promise\ + +禁用缓存并删除其中的数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回删除结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete().then(() => { + console.log('delete success'); +}).catch(err => { + console.log('delete fail'); +}); +``` + +## HttpDataType9+ + +http的数据类型。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 值 | 说明 | +| ------------------ | -- | ----------- | +| STRING | 0 | 字符串类型。 | +| OBJECT | 1 | 对象类型。 | +| ARRAY_BUFFER | 2 | 二进制数组类型。| + +## HttpProtocol9+ + +http协议版本。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 说明 | +| :-------- | :----------- | +| HTTP1_1 | 协议http1.1 | +| HTTP2 | 协议http2 | diff --git a/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202830.md b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202830.md new file mode 100755 index 0000000000..2d0e5ab0cc --- /dev/null +++ b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202830.md @@ -0,0 +1,933 @@ +# @ohos.net.http (数据请求) + +本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 + +>**说明:** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> + +## 导入模块 + +```js +import http from '@ohos.net.http'; +``` + +## 完整示例 + +```js +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个HTTP请求任务,不可复用 +let httpRequest = http.createHttp(); +// 用于订阅HTTP响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +httpRequest.request( + // 填写HTTP请求的URL地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + extraData: { + "data": "data to send", + }, + expectDataType: http.HttpDataType.STRING, // 可选,指定返回数据的类型 + usingCache: true, // 可选,默认为true + priority: 1, // 可选,默认为1 + connectTimeout: 60000, // 可选,默认为60000ms + readTimeout: 60000, // 可选,默认为60000ms + usingProtocol: http.HttpProtocol.HTTP1_1, // 可选,协议类型默认值由系统自动指定 + }, (err, data) => { + if (!err) { + // data.result为HTTP响应内容,可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为HTTP响应头,可根据业务需要进行解析 + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + // 当该请求使用完毕时,调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个HTTP请求,里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header事件。每一个HttpRequest对象对应一个HTTP请求。如需发起多个HTTP请求,须为每个HTTP请求创建对应HttpRequest对象。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| HttpRequest | 返回一个HttpRequest对象,里面包括request、destroy、on和off方法。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpRequest = http.createHttp(); +``` + +## HttpRequest + +HTTP请求任务。在调用HttpRequest的方法前,需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", +{ + method: http.RequestMethod.GET, + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 +}, (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址,发起HTTP网络请求,使用Promise方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------ | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 否 | 参考[HttpRequestOptions](#httprequestoptions)。 | + +**返回值:** + +| 类型 | 说明 | +| :------------------------------------- | :-------------------------------- | +| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300009 | Access denied to remote resource | +| 2300025 | Upload failed | +| 2300028 | Timeout was reached | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +let promise = httpRequest.request("EXAMPLE_URL", { + method: http.RequestMethod.GET, + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } +}); +promise.then((data) => { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); +}).catch((err) => { + console.info('error:' + JSON.stringify(err)); +}); +``` + +### destroy + +destroy\(\): void + +中断请求任务。 + +**系统能力**:SystemCapability.Communication.NetStack + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.destroy(); +``` + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\): void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>此接口已废弃,建议使用[on\('headersReceive'\)8+](#onheadersreceive8)替代。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | --------------------------------- | +| type | string | 是 | 订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + JSON.stringify(data)); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +> +>1. 此接口已废弃,建议使用[off\('headersReceive'\)8+](#offheadersreceive8)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------- | +| type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headerReceive'); +``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | -------------------------------------- | +| type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headersReceive'); +``` + +### once\('headersReceive'\)8+ + +once\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件,但是只触发一次。一旦触发之后,订阅器就会被移除。使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.once('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer6+ | 否 | 发送请求的额外数据。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。6+
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。6+ | +| expectDataType9+ | [HttpDataType](#httpdatatype9) | 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 | +| usingCache9+ | boolean | 否 | 是否使用缓存,默认为true。 | +| priority9+ | number | 否 | 优先级,范围\[1,1000],默认是1。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 | +| usingProtocol9+ | [HttpProtocol](#httpprotocol9) | 否 | 使用协议。默认值由系统自动指定。 | + +## RequestMethod + +HTTP 请求方法。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| :------ | ------- | :------------------ | +| OPTIONS | "OPTIONS" | HTTP 请求 OPTIONS。 | +| GET | "GET" | HTTP 请求 GET。 | +| HEAD | "HEAD" | HTTP 请求 HEAD。 | +| POST | "POST" | HTTP 请求 POST。 | +| PUT | "PUT" | HTTP 请求 PUT。 | +| DELETE | "DELETE" | HTTP 请求 DELETE。 | +| TRACE | "TRACE" | HTTP 请求 TRACE。 | +| CONNECT | "CONNECT" | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求,但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理,但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误,服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留,将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求,但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源(网页)。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长,超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大,服务器无法处理,因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长(URI通常为网址),服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误,无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能,无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护,服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器,未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer6+ | 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string | +| resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | +| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时,此字段为[ResponseCode](#responsecode)。若执行失败,错误码将会从AsyncCallback中的err字段返回。 | +| header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server']; | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +## http.createHttpResponseCache9+ + +createHttpResponseCache(cacheSize?: number): HttpResponseCache + +创建一个默认的对象来存储HTTP访问请求的响应。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| cacheSize | number | 否 | 缓存大小最大为10\*1024\*1024(10MB),默认最大。 | + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| [HttpResponseCache](#httpresponsecache9) | 返回一个存储HTTP访问请求响应的对象。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpResponseCache = http.createHttpResponseCache(); +``` + +## HttpResponseCache9+ + +存储HTTP访问请求响应的对象。 + +### flush9+ + +flush(callback: AsyncCallback\): void + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush(err => { + if (err) { + console.log('flush fail'); + return; + } + console.log('flush success'); +}); +``` + +### flush9+ + +flush(): Promise\ + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\> | 以Promise形式返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush().then(() => { + console.log('flush success'); +}).catch(err => { + console.log('flush fail'); +}); +``` + +### delete9+ + +delete(callback: AsyncCallback\): void + +禁用缓存并删除其中的数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回删除结果。| + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete(err => { + if (err) { + console.log('delete fail'); + return; + } + console.log('delete success'); +}); +``` +### delete9+ + +delete(): Promise\ + +禁用缓存并删除其中的数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回删除结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete().then(() => { + console.log('delete success'); +}).catch(err => { + console.log('delete fail'); +}); +``` + +## HttpDataType9+ + +http的数据类型。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 值 | 说明 | +| ------------------ | -- | ----------- | +| STRING | 0 | 字符串类型。 | +| OBJECT | 1 | 对象类型。 | +| ARRAY_BUFFER | 2 | 二进制数组类型。| + +## HttpProtocol9+ + +http协议版本。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 说明 | +| :-------- | :----------- | +| HTTP1_1 | 协议http1.1 | +| HTTP2 | 协议http2 | diff --git a/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202845.md b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202845.md new file mode 100755 index 0000000000..fb6eabb71e --- /dev/null +++ b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208202845.md @@ -0,0 +1,932 @@ +# @ohos.net.http (数据请求) + +本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 + +>**说明:** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> + +## 导入模块 + +```js +import http from '@ohos.net.http'; +``` + +## 完整示例 + +```js +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个HTTP请求任务,不可复用 +let httpRequest = http.createHttp(); +// 用于订阅HTTP响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +httpRequest.request( + // 填写HTTP请求的URL地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + extraData: { + "data": "data to send", + }, + expectDataType: http.HttpDataType.STRING, // 可选,指定返回数据的类型 + usingCache: true, // 可选,默认为true + priority: 1, // 可选,默认为1 + connectTimeout: 60000, // 可选,默认为60000ms + readTimeout: 60000, // 可选,默认为60000ms + usingProtocol: http.HttpProtocol.HTTP1_1, // 可选,协议类型默认值由系统自动指定 + }, (err, data) => { + if (!err) { + // data.result为HTTP响应内容,可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为HTTP响应头,可根据业务需要进行解析 + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + // 当该请求使用完毕时,调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个HTTP请求,里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header事件。每一个HttpRequest对象对应一个HTTP请求。如需发起多个HTTP请求,须为每个HTTP请求创建对应HttpRequest对象。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| HttpRequest | 返回一个HttpRequest对象,里面包括request、destroy、on和off方法。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpRequest = http.createHttp(); +``` + +## HttpRequest + +HTTP请求任务。在调用HttpRequest的方法前,需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", +{ + method: http.RequestMethod.GET, + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 +}, (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址,发起HTTP网络请求,使用Promise方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------ | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 否 | 参考[HttpRequestOptions](#httprequestoptions)。 | + +**返回值:** + +| 类型 | 说明 | +| :------------------------------------- | :-------------------------------- | +| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300009 | Access denied to remote resource | +| 2300025 | Upload failed | +| 2300028 | Timeout was reached | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +let promise = httpRequest.request("EXAMPLE_URL", { + method: http.RequestMethod.GET, + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } +}); +promise.then((data) => { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); +}).catch((err) => { + console.info('error:' + JSON.stringify(err)); +}); +``` + +### destroy + +destroy\(\): void + +中断请求任务。 + +**系统能力**:SystemCapability.Communication.NetStack + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.destroy(); +``` + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\): void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>此接口已废弃,建议使用[on\('headersReceive'\)8+](#onheadersreceive8)替代。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | --------------------------------- | +| type | string | 是 | 订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + JSON.stringify(data)); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +> +>1. 此接口已废弃,建议使用[off\('headersReceive'\)8+](#offheadersreceive8)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------- | +| type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headerReceive'); +``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | -------------------------------------- | +| type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headersReceive'); +``` + +### once\('headersReceive'\)8+ + +once\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件,但是只触发一次。一旦触发之后,订阅器就会被移除。使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.once('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer6+ | 否 | 发送请求的额外数据。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。6+
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。6+ | +| expectDataType9+ | [HttpDataType](#httpdatatype9) | 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 | +| usingCache9+ | boolean | 否 | 是否使用缓存,默认为true。 | +| priority9+ | number | 否 | 优先级,范围\[1,1000],默认是1。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 | +| usingProtocol9+ | [HttpProtocol](#httpprotocol9) | 否 | 使用协议。默认值由系统自动指定。 | + +## RequestMethod + +HTTP 请求方法。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| :------ | ------- | :------------------ | +| OPTIONS | "OPTIONS" | HTTP 请求 OPTIONS。 | +| GET | "GET" | HTTP 请求 GET。 | +| HEAD | "HEAD" | HTTP 请求 HEAD。 | +| POST | "POST" | HTTP 请求 POST。 | +| PUT | "PUT" | HTTP 请求 PUT。 | +| DELETE | "DELETE" | HTTP 请求 DELETE。 | +| TRACE | "TRACE" | HTTP 请求 TRACE。 | +| CONNECT | "CONNECT" | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求,但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理,但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误,服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留,将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求,但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源(网页)。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长,超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大,服务器无法处理,因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长(URI通常为网址),服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误,无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能,无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护,服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器,未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer6+ | 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string | +| resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | +| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时,此字段为[ResponseCode](#responsecode)。若执行失败,错误码将会从AsyncCallback中的err字段返回。 | +| header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server']; | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +## http.createHttpResponseCache9+ + +createHttpResponseCache(cacheSize?: number): HttpResponseCache + +创建一个默认的对象来存储HTTP访问请求的响应。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| cacheSize | number | 否 | 缓存大小最大为10\*1024\*1024(10MB),默认最大。 | + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| [HttpResponseCache](#httpresponsecache9) | 返回一个存储HTTP访问请求响应的对象。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpResponseCache = http.createHttpResponseCache(); +``` + +## HttpResponseCache9+ + +存储HTTP访问请求响应的对象。 + +### flush9+ + +flush(callback: AsyncCallback\): void + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush(err => { + if (err) { + console.log('flush fail'); + return; + } + console.log('flush success'); +}); +``` + +### flush9+ + +flush(): Promise\ + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\> | 以Promise形式返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush().then(() => { + console.log('flush success'); +}).catch(err => { + console.log('flush fail'); +}); +``` + +### delete9+ + +delete(callback: AsyncCallback\): void + +禁用缓存并删除其中的数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回删除结果。| + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete(err => { + if (err) { + console.log('delete fail'); + return; + } + console.log('delete success'); +}); +``` +### delete9+ + +delete(): Promise\ + +禁用缓存并删除其中的数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回删除结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete().then(() => { + console.log('delete success'); +}).catch(err => { + console.log('delete fail'); +}); +``` + +## HttpDataType9+ + +http的数据类型。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 值 | 说明 | +| ------------------ | -- | ----------- | +| STRING | 0 | 字符串类型。 | +| OBJECT | 1 | 对象类型。 | +| ARRAY_BUFFER | 2 | 二进制数组类型。| + +## HttpProtocol9+ + +http协议版本。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 说明 | +| :-------- | :----------- | +| HTTP1_1 | 协议http1.1 | +| HTTP2 | 协议http2 | diff --git a/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208203329.md b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208203329.md new file mode 100755 index 0000000000..a23ceb4cff --- /dev/null +++ b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208203329.md @@ -0,0 +1,987 @@ +# @ohos.net.http (数据请求) + +本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 + +>**说明:** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> + +## 导入模块 + +```js +import http from '@ohos.net.http'; +``` + +## 完整示例 + +```js +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个HTTP请求任务,不可复用 +let httpRequest = http.createHttp(); +// 用于订阅HTTP响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +httpRequest.request( + // 填写HTTP请求的URL地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + extraData: { + "data": "data to send", + }, + expectDataType: http.HttpDataType.STRING, // 可选,指定返回数据的类型 + usingCache: true, // 可选,默认为true + priority: 1, // 可选,默认为1 + connectTimeout: 60000, // 可选,默认为60000ms + readTimeout: 60000, // 可选,默认为60000ms + usingProtocol: http.HttpProtocol.HTTP1_1, // 可选,协议类型默认值由系统自动指定 + }, (err, data) => { + if (!err) { + // data.result为HTTP响应内容,可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为HTTP响应头,可根据业务需要进行解析 + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + // 当该请求使用完毕时,调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个HTTP请求,里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header事件。每一个HttpRequest对象对应一个HTTP请求。如需发起多个HTTP请求,须为每个HTTP请求创建对应HttpRequest对象。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| HttpRequest | 返回一个HttpRequest对象,里面包括request、destroy、on和off方法。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpRequest = http.createHttp(); +``` + +## HttpRequest + +HTTP请求任务。在调用HttpRequest的方法前,需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300007 | Couldn't connect to server. | +| 2300028 | Timeout was reached. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300999 | Unknown Other Error. | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", +{ + method: http.RequestMethod.GET, + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 +}, (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址,发起HTTP网络请求,使用Promise方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------ | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 否 | 参考[HttpRequestOptions](#httprequestoptions)。 | + +**返回值:** + +| 类型 | 说明 | +| :------------------------------------- | :-------------------------------- | +| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +let promise = httpRequest.request("EXAMPLE_URL", { + method: http.RequestMethod.GET, + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } +}); +promise.then((data) => { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); +}).catch((err) => { + console.info('error:' + JSON.stringify(err)); +}); +``` + +### destroy + +destroy\(\): void + +中断请求任务。 + +**系统能力**:SystemCapability.Communication.NetStack + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.destroy(); +``` + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\): void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>此接口已废弃,建议使用[on\('headersReceive'\)8+](#onheadersreceive8)替代。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | --------------------------------- | +| type | string | 是 | 订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + JSON.stringify(data)); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +> +>1. 此接口已废弃,建议使用[off\('headersReceive'\)8+](#offheadersreceive8)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------- | +| type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headerReceive'); +``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | -------------------------------------- | +| type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headersReceive'); +``` + +### once\('headersReceive'\)8+ + +once\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件,但是只触发一次。一旦触发之后,订阅器就会被移除。使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.once('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer6+ | 否 | 发送请求的额外数据。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。6+
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。6+ | +| expectDataType9+ | [HttpDataType](#httpdatatype9) | 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 | +| usingCache9+ | boolean | 否 | 是否使用缓存,默认为true。 | +| priority9+ | number | 否 | 优先级,范围\[1,1000],默认是1。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 | +| usingProtocol9+ | [HttpProtocol](#httpprotocol9) | 否 | 使用协议。默认值由系统自动指定。 | + +## RequestMethod + +HTTP 请求方法。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| :------ | ------- | :------------------ | +| OPTIONS | "OPTIONS" | HTTP 请求 OPTIONS。 | +| GET | "GET" | HTTP 请求 GET。 | +| HEAD | "HEAD" | HTTP 请求 HEAD。 | +| POST | "POST" | HTTP 请求 POST。 | +| PUT | "PUT" | HTTP 请求 PUT。 | +| DELETE | "DELETE" | HTTP 请求 DELETE。 | +| TRACE | "TRACE" | HTTP 请求 TRACE。 | +| CONNECT | "CONNECT" | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求,但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理,但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误,服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留,将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求,但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源(网页)。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长,超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大,服务器无法处理,因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长(URI通常为网址),服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误,无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能,无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护,服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器,未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer6+ | 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string | +| resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | +| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时,此字段为[ResponseCode](#responsecode)。若执行失败,错误码将会从AsyncCallback中的err字段返回。 | +| header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server']; | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +## http.createHttpResponseCache9+ + +createHttpResponseCache(cacheSize?: number): HttpResponseCache + +创建一个默认的对象来存储HTTP访问请求的响应。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| cacheSize | number | 否 | 缓存大小最大为10\*1024\*1024(10MB),默认最大。 | + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| [HttpResponseCache](#httpresponsecache9) | 返回一个存储HTTP访问请求响应的对象。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpResponseCache = http.createHttpResponseCache(); +``` + +## HttpResponseCache9+ + +存储HTTP访问请求响应的对象。 + +### flush9+ + +flush(callback: AsyncCallback\): void + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush(err => { + if (err) { + console.log('flush fail'); + return; + } + console.log('flush success'); +}); +``` + +### flush9+ + +flush(): Promise\ + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\> | 以Promise形式返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300016 | Error in the HTTP2 framing layer | +| 2300018 | Transferred a partial file | +| 2300023 | Failed writing received data to disk/application | +| 2300025 | Upload failed | +| 2300026 | Failed to open/read local data from file/application | +| 2300027 | Out of memory | +| 2300028 | Timeout was reached | +| 2300047 | Number of redirects hit maximum amount | +| 2300052 | Server returned nothing (no headers, no data) | +| 2300055 | Failed sending data to the peer | +| 2300056 | Failure when receiving data from the peer | +| 2300058 | Problem with the local SSL certificate | +| 2300059 | Couldn't use specified SSL cipher | +| 2300060 | SSL peer certificate or SSH remote key was not OK | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | +| 2300063 | Maximum file size exceeded | +| 2300070 | Disk full or allocation exceeded | +| 2300073 | Remote file already exists | +| 2300077 | Problem with the SSL CA cert (path? access rights?) | +| 2300078 | Remote file not found | +| 2300094 | An authentication function returned an error | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush().then(() => { + console.log('flush success'); +}).catch(err => { + console.log('flush fail'); +}); +``` + +### delete9+ + +delete(callback: AsyncCallback\): void + +禁用缓存并删除其中的数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回删除结果。| + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol | +| 2300003 | URL using bad/illegal format or missing URL | +| 2300005 | Couldn't resolve proxy name | +| 2300006 | Couldn't resolve host name | +| 2300007 | Couldn't connect to server | +| 2300008 | Weird server reply | +| 2300009 | Access denied to remote resource | +| 2300999 | Unknown Other Error | + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete(err => { + if (err) { + console.log('delete fail'); + return; + } + console.log('delete success'); +}); +``` +### delete9+ + +delete(): Promise\ + +禁用缓存并删除其中的数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回删除结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error | + + +更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete().then(() => { + console.log('delete success'); +}).catch(err => { + console.log('delete fail'); +}); +``` + +## HttpDataType9+ + +http的数据类型。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 值 | 说明 | +| ------------------ | -- | ----------- | +| STRING | 0 | 字符串类型。 | +| OBJECT | 1 | 对象类型。 | +| ARRAY_BUFFER | 2 | 二进制数组类型。| + +## HttpProtocol9+ + +http协议版本。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 说明 | +| :-------- | :----------- | +| HTTP1_1 | 协议http1.1 | +| HTTP2 | 协议http2 | + + + + + + + + + + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | diff --git a/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208203943.md b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208203943.md new file mode 100755 index 0000000000..922349f9b7 --- /dev/null +++ b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208203943.md @@ -0,0 +1,1066 @@ +# @ohos.net.http (数据请求) + +本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 + +>**说明:** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> + +## 导入模块 + +```js +import http from '@ohos.net.http'; +``` + +## 完整示例 + +```js +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个HTTP请求任务,不可复用 +let httpRequest = http.createHttp(); +// 用于订阅HTTP响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +httpRequest.request( + // 填写HTTP请求的URL地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + extraData: { + "data": "data to send", + }, + expectDataType: http.HttpDataType.STRING, // 可选,指定返回数据的类型 + usingCache: true, // 可选,默认为true + priority: 1, // 可选,默认为1 + connectTimeout: 60000, // 可选,默认为60000ms + readTimeout: 60000, // 可选,默认为60000ms + usingProtocol: http.HttpProtocol.HTTP1_1, // 可选,协议类型默认值由系统自动指定 + }, (err, data) => { + if (!err) { + // data.result为HTTP响应内容,可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为HTTP响应头,可根据业务需要进行解析 + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + // 当该请求使用完毕时,调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个HTTP请求,里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header事件。每一个HttpRequest对象对应一个HTTP请求。如需发起多个HTTP请求,须为每个HTTP请求创建对应HttpRequest对象。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| HttpRequest | 返回一个HttpRequest对象,里面包括request、destroy、on和off方法。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpRequest = http.createHttp(); +``` + +## HttpRequest + +HTTP请求任务。在调用HttpRequest的方法前,需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300007 | Couldn't connect to server. | +| 2300028 | Timeout was reached. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", +{ + method: http.RequestMethod.GET, + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 +}, (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址,发起HTTP网络请求,使用Promise方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------ | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 否 | 参考[HttpRequestOptions](#httprequestoptions)。 | + +**返回值:** + +| 类型 | 说明 | +| :------------------------------------- | :-------------------------------- | +| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +let promise = httpRequest.request("EXAMPLE_URL", { + method: http.RequestMethod.GET, + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } +}); +promise.then((data) => { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); +}).catch((err) => { + console.info('error:' + JSON.stringify(err)); +}); +``` + +### destroy + +destroy\(\): void + +中断请求任务。 + +**系统能力**:SystemCapability.Communication.NetStack + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.destroy(); +``` + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\): void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>此接口已废弃,建议使用[on\('headersReceive'\)8+](#onheadersreceive8)替代。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | --------------------------------- | +| type | string | 是 | 订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + JSON.stringify(data)); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +> +>1. 此接口已废弃,建议使用[off\('headersReceive'\)8+](#offheadersreceive8)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------- | +| type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headerReceive'); +``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | -------------------------------------- | +| type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headersReceive'); +``` + +### once\('headersReceive'\)8+ + +once\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件,但是只触发一次。一旦触发之后,订阅器就会被移除。使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.once('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer6+ | 否 | 发送请求的额外数据。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。6+
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。6+ | +| expectDataType9+ | [HttpDataType](#httpdatatype9) | 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 | +| usingCache9+ | boolean | 否 | 是否使用缓存,默认为true。 | +| priority9+ | number | 否 | 优先级,范围\[1,1000],默认是1。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 | +| usingProtocol9+ | [HttpProtocol](#httpprotocol9) | 否 | 使用协议。默认值由系统自动指定。 | + +## RequestMethod + +HTTP 请求方法。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| :------ | ------- | :------------------ | +| OPTIONS | "OPTIONS" | HTTP 请求 OPTIONS。 | +| GET | "GET" | HTTP 请求 GET。 | +| HEAD | "HEAD" | HTTP 请求 HEAD。 | +| POST | "POST" | HTTP 请求 POST。 | +| PUT | "PUT" | HTTP 请求 PUT。 | +| DELETE | "DELETE" | HTTP 请求 DELETE。 | +| TRACE | "TRACE" | HTTP 请求 TRACE。 | +| CONNECT | "CONNECT" | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求,但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理,但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误,服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留,将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求,但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源(网页)。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长,超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大,服务器无法处理,因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长(URI通常为网址),服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误,无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能,无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护,服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器,未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer6+ | 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string | +| resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | +| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时,此字段为[ResponseCode](#responsecode)。若执行失败,错误码将会从AsyncCallback中的err字段返回。 | +| header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server']; | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +## http.createHttpResponseCache9+ + +createHttpResponseCache(cacheSize?: number): HttpResponseCache + +创建一个默认的对象来存储HTTP访问请求的响应。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| cacheSize | number | 否 | 缓存大小最大为10\*1024\*1024(10MB),默认最大。 | + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| [HttpResponseCache](#httpresponsecache9) | 返回一个存储HTTP访问请求响应的对象。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpResponseCache = http.createHttpResponseCache(); +``` + +## HttpResponseCache9+ + +存储HTTP访问请求响应的对象。 + +### flush9+ + +flush(callback: AsyncCallback\): void + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush().then(() => { + console.log('flush success'); +}).catch(err => { + console.log('flush fail'); +}); +``` + +### delete9+ + +delete(callback: AsyncCallback\): void + +禁用缓存并删除其中的数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回删除结果。| + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete(err => { + if (err) { + console.log('delete fail'); + return; + } + console.log('delete success'); +}); +``` +### delete9+ + +delete(): Promise\ + +禁用缓存并删除其中的数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回删除结果。 | + +**错误码:** + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete().then(() => { + console.log('delete success'); +}).catch(err => { + console.log('delete fail'); +}); +``` + +## HttpDataType9+ + +http的数据类型。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 值 | 说明 | +| ------------------ | -- | ----------- | +| STRING | 0 | 字符串类型。 | +| OBJECT | 1 | 对象类型。 | +| ARRAY_BUFFER | 2 | 二进制数组类型。| + +## HttpProtocol9+ + +http协议版本。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 说明 | +| :-------- | :----------- | +| HTTP1_1 | 协议http1.1 | +| HTTP2 | 协议http2 | + + + + + + + + + + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | diff --git a/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208204504.md b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208204504.md new file mode 100755 index 0000000000..8db5df2df8 --- /dev/null +++ b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208204504.md @@ -0,0 +1,926 @@ +# @ohos.net.http (数据请求) + +本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 + +>**说明:** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> + +## 导入模块 + +```js +import http from '@ohos.net.http'; +``` + +## 完整示例 + +```js +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个HTTP请求任务,不可复用 +let httpRequest = http.createHttp(); +// 用于订阅HTTP响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +httpRequest.request( + // 填写HTTP请求的URL地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + extraData: { + "data": "data to send", + }, + expectDataType: http.HttpDataType.STRING, // 可选,指定返回数据的类型 + usingCache: true, // 可选,默认为true + priority: 1, // 可选,默认为1 + connectTimeout: 60000, // 可选,默认为60000ms + readTimeout: 60000, // 可选,默认为60000ms + usingProtocol: http.HttpProtocol.HTTP1_1, // 可选,协议类型默认值由系统自动指定 + }, (err, data) => { + if (!err) { + // data.result为HTTP响应内容,可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为HTTP响应头,可根据业务需要进行解析 + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + // 当该请求使用完毕时,调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个HTTP请求,里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header事件。每一个HttpRequest对象对应一个HTTP请求。如需发起多个HTTP请求,须为每个HTTP请求创建对应HttpRequest对象。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| HttpRequest | 返回一个HttpRequest对象,里面包括request、destroy、on和off方法。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpRequest = http.createHttp(); +``` + +## HttpRequest + +HTTP请求任务。在调用HttpRequest的方法前,需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300007 | Couldn't connect to server. | +| 2300028 | Timeout was reached. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", +{ + method: http.RequestMethod.GET, + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 +}, (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址,发起HTTP网络请求,使用Promise方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------ | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 否 | 参考[HttpRequestOptions](#httprequestoptions)。 | + +**返回值:** + +| 类型 | 说明 | +| :------------------------------------- | :-------------------------------- | +| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +let promise = httpRequest.request("EXAMPLE_URL", { + method: http.RequestMethod.GET, + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } +}); +promise.then((data) => { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); +}).catch((err) => { + console.info('error:' + JSON.stringify(err)); +}); +``` + +### destroy + +destroy\(\): void + +中断请求任务。 + +**系统能力**:SystemCapability.Communication.NetStack + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.destroy(); +``` + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\): void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>此接口已废弃,建议使用[on\('headersReceive'\)8+](#onheadersreceive8)替代。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | --------------------------------- | +| type | string | 是 | 订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + JSON.stringify(data)); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +> +>1. 此接口已废弃,建议使用[off\('headersReceive'\)8+](#offheadersreceive8)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------- | +| type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headerReceive'); +``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | -------------------------------------- | +| type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headersReceive'); +``` + +### once\('headersReceive'\)8+ + +once\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件,但是只触发一次。一旦触发之后,订阅器就会被移除。使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.once('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer6+ | 否 | 发送请求的额外数据。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。6+
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。6+ | +| expectDataType9+ | [HttpDataType](#httpdatatype9) | 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 | +| usingCache9+ | boolean | 否 | 是否使用缓存,默认为true。 | +| priority9+ | number | 否 | 优先级,范围\[1,1000],默认是1。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 | +| usingProtocol9+ | [HttpProtocol](#httpprotocol9) | 否 | 使用协议。默认值由系统自动指定。 | + +## RequestMethod + +HTTP 请求方法。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| :------ | ------- | :------------------ | +| OPTIONS | "OPTIONS" | HTTP 请求 OPTIONS。 | +| GET | "GET" | HTTP 请求 GET。 | +| HEAD | "HEAD" | HTTP 请求 HEAD。 | +| POST | "POST" | HTTP 请求 POST。 | +| PUT | "PUT" | HTTP 请求 PUT。 | +| DELETE | "DELETE" | HTTP 请求 DELETE。 | +| TRACE | "TRACE" | HTTP 请求 TRACE。 | +| CONNECT | "CONNECT" | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求,但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理,但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误,服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留,将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求,但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源(网页)。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长,超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大,服务器无法处理,因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长(URI通常为网址),服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误,无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能,无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护,服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器,未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer6+ | 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string | +| resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | +| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时,此字段为[ResponseCode](#responsecode)。若执行失败,错误码将会从AsyncCallback中的err字段返回。 | +| header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server']; | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +## http.createHttpResponseCache9+ + +createHttpResponseCache(cacheSize?: number): HttpResponseCache + +创建一个默认的对象来存储HTTP访问请求的响应。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| cacheSize | number | 否 | 缓存大小最大为10\*1024\*1024(10MB),默认最大。 | + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| [HttpResponseCache](#httpresponsecache9) | 返回一个存储HTTP访问请求响应的对象。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpResponseCache = http.createHttpResponseCache(); +``` + +## HttpResponseCache9+ + +存储HTTP访问请求响应的对象。 + +### flush9+ + +flush(callback: AsyncCallback\): void + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush().then(() => { + console.log('flush success'); +}).catch(err => { + console.log('flush fail'); +}); +``` + +### delete9+ + +delete(callback: AsyncCallback\): void + +禁用缓存并删除其中的数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回删除结果。| + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete(err => { + if (err) { + console.log('delete fail'); + return; + } + console.log('delete success'); +}); +``` +### delete9+ + +delete(): Promise\ + +禁用缓存并删除其中的数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回删除结果。 | + +**错误码:** + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete().then(() => { + console.log('delete success'); +}).catch(err => { + console.log('delete fail'); +}); +``` + +## HttpDataType9+ + +http的数据类型。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 值 | 说明 | +| ------------------ | -- | ----------- | +| STRING | 0 | 字符串类型。 | +| OBJECT | 1 | 对象类型。 | +| ARRAY_BUFFER | 2 | 二进制数组类型。| + +## HttpProtocol9+ + +http协议版本。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 说明 | +| :-------- | :----------- | +| HTTP1_1 | 协议http1.1 | +| HTTP2 | 协议http2 | + + + + + + + + + + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | diff --git a/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208204945.md b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208204945.md new file mode 100755 index 0000000000..b43b8ec66a --- /dev/null +++ b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208204945.md @@ -0,0 +1,771 @@ +# @ohos.net.http (数据请求) + +本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 + +>**说明:** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> + +## 导入模块 + +```js +import http from '@ohos.net.http'; +``` + +## 完整示例 + +```js +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个HTTP请求任务,不可复用 +let httpRequest = http.createHttp(); +// 用于订阅HTTP响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +httpRequest.request( + // 填写HTTP请求的URL地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + extraData: { + "data": "data to send", + }, + expectDataType: http.HttpDataType.STRING, // 可选,指定返回数据的类型 + usingCache: true, // 可选,默认为true + priority: 1, // 可选,默认为1 + connectTimeout: 60000, // 可选,默认为60000ms + readTimeout: 60000, // 可选,默认为60000ms + usingProtocol: http.HttpProtocol.HTTP1_1, // 可选,协议类型默认值由系统自动指定 + }, (err, data) => { + if (!err) { + // data.result为HTTP响应内容,可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为HTTP响应头,可根据业务需要进行解析 + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + // 当该请求使用完毕时,调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个HTTP请求,里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header事件。每一个HttpRequest对象对应一个HTTP请求。如需发起多个HTTP请求,须为每个HTTP请求创建对应HttpRequest对象。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| HttpRequest | 返回一个HttpRequest对象,里面包括request、destroy、on和off方法。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpRequest = http.createHttp(); +``` + +## HttpRequest + +HTTP请求任务。在调用HttpRequest的方法前,需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300007 | Couldn't connect to server. | +| 2300028 | Timeout was reached. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", +{ + method: http.RequestMethod.GET, + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 +}, (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址,发起HTTP网络请求,使用Promise方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------ | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 否 | 参考[HttpRequestOptions](#httprequestoptions)。 | + +**返回值:** + +| 类型 | 说明 | +| :------------------------------------- | :-------------------------------- | +| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +let promise = httpRequest.request("EXAMPLE_URL", { + method: http.RequestMethod.GET, + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } +}); +promise.then((data) => { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); +}).catch((err) => { + console.info('error:' + JSON.stringify(err)); +}); +``` + +### destroy + +destroy\(\): void + +中断请求任务。 + +**系统能力**:SystemCapability.Communication.NetStack + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.destroy(); +``` + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\): void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>此接口已废弃,建议使用[on\('headersReceive'\)8+](#onheadersreceive8)替代。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | --------------------------------- | +| type | string | 是 | 订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + JSON.stringify(data)); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +> +>1. 此接口已废弃,建议使用[off\('headersReceive'\)8+](#offheadersreceive8)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------- | +| type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headerReceive'); +``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | -------------------------------------- | +| type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headersReceive'); +``` + +### once\('headersReceive'\)8+ + +once\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件,但是只触发一次。一旦触发之后,订阅器就会被移除。使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.once('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer6+ | 否 | 发送请求的额外数据。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。6+
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。6+ | +| expectDataType9+ | [HttpDataType](#httpdatatype9) | 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 | +| usingCache9+ | boolean | 否 | 是否使用缓存,默认为true。 | +| priority9+ | number | 否 | 优先级,范围\[1,1000],默认是1。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 | +| usingProtocol9+ | [HttpProtocol](#httpprotocol9) | 否 | 使用协议。默认值由系统自动指定。 | + +## RequestMethod + +HTTP 请求方法。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| :------ | ------- | :------------------ | +| OPTIONS | "OPTIONS" | HTTP 请求 OPTIONS。 | +| GET | "GET" | HTTP 请求 GET。 | +| HEAD | "HEAD" | HTTP 请求 HEAD。 | +| POST | "POST" | HTTP 请求 POST。 | +| PUT | "PUT" | HTTP 请求 PUT。 | +| DELETE | "DELETE" | HTTP 请求 DELETE。 | +| TRACE | "TRACE" | HTTP 请求 TRACE。 | +| CONNECT | "CONNECT" | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求,但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理,但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误,服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留,将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求,但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源(网页)。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长,超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大,服务器无法处理,因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长(URI通常为网址),服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误,无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能,无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护,服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器,未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer6+ | 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string | +| resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | +| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时,此字段为[ResponseCode](#responsecode)。若执行失败,错误码将会从AsyncCallback中的err字段返回。 | +| header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server']; | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +## http.createHttpResponseCache9+ + +createHttpResponseCache(cacheSize?: number): HttpResponseCache + +创建一个默认的对象来存储HTTP访问请求的响应。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| cacheSize | number | 否 | 缓存大小最大为10\*1024\*1024(10MB),默认最大。 | + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| [HttpResponseCache](#httpresponsecache9) | 返回一个存储HTTP访问请求响应的对象。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpResponseCache = http.createHttpResponseCache(); +``` + +## HttpResponseCache9+ + +存储HTTP访问请求响应的对象。 + +### flush9+ + +flush(callback: AsyncCallback\): void + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300070 | Disk full or allocation exceeded. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush().then(() => { + console.log('flush success'); +}).catch(err => { + console.log('flush fail'); +}); +``` + +### delete9+ + +delete(callback: AsyncCallback\): void + +禁用缓存并删除其中的数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回删除结果。| + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete(err => { + if (err) { + console.log('delete fail'); + return; + } + console.log('delete success'); +}); +``` +### delete9+ + +delete(): Promise\ + +禁用缓存并删除其中的数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回删除结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete().then(() => { + console.log('delete success'); +}).catch(err => { + console.log('delete fail'); +}); +``` + +## HttpDataType9+ + +http的数据类型。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 值 | 说明 | +| ------------------ | -- | ----------- | +| STRING | 0 | 字符串类型。 | +| OBJECT | 1 | 对象类型。 | +| ARRAY_BUFFER | 2 | 二进制数组类型。| + +## HttpProtocol9+ + +http协议版本。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 说明 | +| :-------- | :----------- | +| HTTP1_1 | 协议http1.1 | +| HTTP2 | 协议http2 | diff --git a/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208204946.md b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208204946.md new file mode 100755 index 0000000000..b43b8ec66a --- /dev/null +++ b/.history/zh-cn/application-dev/reference/apis/js-apis-http_20230208204946.md @@ -0,0 +1,771 @@ +# @ohos.net.http (数据请求) + +本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 + +>**说明:** +> +>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> + +## 导入模块 + +```js +import http from '@ohos.net.http'; +``` + +## 完整示例 + +```js +import http from '@ohos.net.http'; + +// 每一个httpRequest对应一个HTTP请求任务,不可复用 +let httpRequest = http.createHttp(); +// 用于订阅HTTP响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息 +// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+ +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +httpRequest.request( + // 填写HTTP请求的URL地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 + "EXAMPLE_URL", + { + method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET + // 开发者根据自身业务需要添加header字段 + header: { + 'Content-Type': 'application/json' + }, + // 当使用POST请求时此字段用于传递内容 + extraData: { + "data": "data to send", + }, + expectDataType: http.HttpDataType.STRING, // 可选,指定返回数据的类型 + usingCache: true, // 可选,默认为true + priority: 1, // 可选,默认为1 + connectTimeout: 60000, // 可选,默认为60000ms + readTimeout: 60000, // 可选,默认为60000ms + usingProtocol: http.HttpProtocol.HTTP1_1, // 可选,协议类型默认值由系统自动指定 + }, (err, data) => { + if (!err) { + // data.result为HTTP响应内容,可根据业务需要进行解析 + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + // data.header为HTTP响应头,可根据业务需要进行解析 + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + // 当该请求使用完毕时,调用destroy方法主动销毁。 + httpRequest.destroy(); + } + } +); +``` + +## http.createHttp + +createHttp\(\): HttpRequest + +创建一个HTTP请求,里面包括发起请求、中断请求、订阅/取消订阅HTTP Response Header事件。每一个HttpRequest对象对应一个HTTP请求。如需发起多个HTTP请求,须为每个HTTP请求创建对应HttpRequest对象。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| HttpRequest | 返回一个HttpRequest对象,里面包括request、destroy、on和off方法。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpRequest = http.createHttp(); +``` + +## HttpRequest + +HTTP请求任务。在调用HttpRequest的方法前,需要先通过[createHttp\(\)](#httpcreatehttp)创建一个任务。 + +### request + +request\(url: string, callback: AsyncCallback\\):void + +根据URL地址,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300007 | Couldn't connect to server. | +| 2300028 | Timeout was reached. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options: HttpRequestOptions, callback: AsyncCallback\):void + +根据URL地址和相关配置项,发起HTTP网络请求,使用callback方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 是 | 参考[HttpRequestOptions](#httprequestoptions)。 | +| callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.request("EXAMPLE_URL", +{ + method: http.RequestMethod.GET, + header: { + 'Content-Type': 'application/json' + }, + readTimeout: 60000, + connectTimeout: 60000 +}, (err, data) => { + if (!err) { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### request + +request\(url: string, options? : HttpRequestOptions\): Promise + +根据URL地址,发起HTTP网络请求,使用Promise方式作为异步方法。 + +**需要权限**:ohos.permission.INTERNET + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------ | ---- | ----------------------------------------------- | +| url | string | 是 | 发起网络请求的URL地址。 | +| options | HttpRequestOptions | 否 | 参考[HttpRequestOptions](#httprequestoptions)。 | + +**返回值:** + +| 类型 | 说明 | +| :------------------------------------- | :-------------------------------- | +| Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +let promise = httpRequest.request("EXAMPLE_URL", { + method: http.RequestMethod.GET, + connectTimeout: 60000, + readTimeout: 60000, + header: { + 'Content-Type': 'application/json' + } +}); +promise.then((data) => { + console.info('Result:' + data.result); + console.info('code:' + data.responseCode); + console.info('header:' + JSON.stringify(data.header)); + console.info('cookies:' + data.cookies); // 8+ + console.info('header.Content-Type:' + data.header['Content-Type']); + console.info('header.Status-Line:' + data.header['Status-Line']); +}).catch((err) => { + console.info('error:' + JSON.stringify(err)); +}); +``` + +### destroy + +destroy\(\): void + +中断请求任务。 + +**系统能力**:SystemCapability.Communication.NetStack + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.destroy(); +``` + +### on\('headerReceive'\) + +on\(type: 'headerReceive', callback: AsyncCallback\): void + +订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>此接口已废弃,建议使用[on\('headersReceive'\)8+](#onheadersreceive8)替代。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | --------------------------------- | +| type | string | 是 | 订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headerReceive', (err, data) => { + if (!err) { + console.info('header: ' + JSON.stringify(data)); + } else { + console.info('error:' + JSON.stringify(err)); + } +}); +``` + +### off\('headerReceive'\) + +off\(type: 'headerReceive', callback?: AsyncCallback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +> +>1. 此接口已废弃,建议使用[off\('headersReceive'\)8+](#offheadersreceive8)替代。 +> +>2. 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------- | +| type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | +| callback | AsyncCallback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headerReceive'); +``` + +### on\('headersReceive'\)8+ + +on\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.on('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +### off\('headersReceive'\)8+ + +off\(type: 'headersReceive', callback?: Callback\): void + +取消订阅HTTP Response Header 事件。 + +>![](public_sys-resources/icon-note.gif) **说明:** +>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | -------------------------------------- | +| type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 否 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.off('headersReceive'); +``` + +### once\('headersReceive'\)8+ + +once\(type: 'headersReceive', callback: Callback\): void + +订阅HTTP Response Header 事件,但是只触发一次。一旦触发之后,订阅器就会被移除。使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------ | ---- | ---------------------------------- | +| type | string | 是 | 订阅的事件类型:'headersReceive'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpRequest.once('headersReceive', (header) => { + console.info('header: ' + JSON.stringify(header)); +}); +``` + +## HttpRequestOptions + +发起请求可选参数的类型和取值范围。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | +| extraData | string \| Object \| ArrayBuffer6+ | 否 | 发送请求的额外数据。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。6+
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。6+ | +| expectDataType9+ | [HttpDataType](#httpdatatype9) | 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 | +| usingCache9+ | boolean | 否 | 是否使用缓存,默认为true。 | +| priority9+ | number | 否 | 优先级,范围\[1,1000],默认是1。 | +| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | +| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 | +| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 | +| usingProtocol9+ | [HttpProtocol](#httpprotocol9) | 否 | 使用协议。默认值由系统自动指定。 | + +## RequestMethod + +HTTP 请求方法。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| :------ | ------- | :------------------ | +| OPTIONS | "OPTIONS" | HTTP 请求 OPTIONS。 | +| GET | "GET" | HTTP 请求 GET。 | +| HEAD | "HEAD" | HTTP 请求 HEAD。 | +| POST | "POST" | HTTP 请求 POST。 | +| PUT | "PUT" | HTTP 请求 PUT。 | +| DELETE | "DELETE" | HTTP 请求 DELETE。 | +| TRACE | "TRACE" | HTTP 请求 TRACE。 | +| CONNECT | "CONNECT" | HTTP 请求 CONNECT。 | + +## ResponseCode + +发起请求返回的响应码。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | ------------------------------------------------------------ | +| OK | 200 | 请求成功。一般用于GET与POST请求。 | +| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | +| ACCEPTED | 202 | 已接受。已经接受请求,但未处理完成。 | +| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | +| NO_CONTENT | 204 | 无内容。服务器成功处理,但未返回内容。 | +| RESET | 205 | 重置内容。 | +| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | +| MULT_CHOICE | 300 | 多种选择。 | +| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。 | +| MOVED_TEMP | 302 | 临时移动。 | +| SEE_OTHER | 303 | 查看其它地址。 | +| NOT_MODIFIED | 304 | 未修改。 | +| USE_PROXY | 305 | 使用代理。 | +| BAD_REQUEST | 400 | 客户端请求的语法错误,服务器无法理解。 | +| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | +| PAYMENT_REQUIRED | 402 | 保留,将来使用。 | +| FORBIDDEN | 403 | 服务器理解请求客户端的请求,但是拒绝执行此请求。 | +| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源(网页)。 | +| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | +| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | +| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | +| CLIENT_TIMEOUT | 408 | 请求时间过长,超时。 | +| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。 | +| GONE | 410 | 客户端请求的资源已经不存在。 | +| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | +| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | +| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大,服务器无法处理,因此拒绝请求。 | +| REQ_TOO_LONG | 414 | 请求的URI过长(URI通常为网址),服务器无法处理。 | +| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | +| INTERNAL_ERROR | 500 | 服务器内部错误,无法完成请求。 | +| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能,无法完成请求。 | +| BAD_GATEWAY | 502 | 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。 | +| UNAVAILABLE | 503 | 由于超载或系统维护,服务器暂时的无法处理客户端的请求。 | +| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器,未及时从远端服务器获取请求。 | +| VERSION | 505 | 服务器请求的HTTP协议的版本。 | + +## HttpResponse + +request方法回调函数的返回值类型。 + +**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| result | string \| Object \| ArrayBuffer6+ | 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string | +| resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | +| responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时,此字段为[ResponseCode](#responsecode)。若执行失败,错误码将会从AsyncCallback中的err字段返回。 | +| header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server']; | +| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | + +## http.createHttpResponseCache9+ + +createHttpResponseCache(cacheSize?: number): HttpResponseCache + +创建一个默认的对象来存储HTTP访问请求的响应。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| cacheSize | number | 否 | 缓存大小最大为10\*1024\*1024(10MB),默认最大。 | + +**返回值:** + +| 类型 | 说明 | +| :---------- | :----------------------------------------------------------- | +| [HttpResponseCache](#httpresponsecache9) | 返回一个存储HTTP访问请求响应的对象。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +import http from '@ohos.net.http'; +let httpResponseCache = http.createHttpResponseCache(); +``` + +## HttpResponseCache9+ + +存储HTTP访问请求响应的对象。 + +### flush9+ + +flush(callback: AsyncCallback\): void + +将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回写入结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300070 | Disk full or allocation exceeded. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.flush().then(() => { + console.log('flush success'); +}).catch(err => { + console.log('flush fail'); +}); +``` + +### delete9+ + +delete(callback: AsyncCallback\): void + +禁用缓存并删除其中的数据,使用callback方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数返回删除结果。| + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete(err => { + if (err) { + console.log('delete fail'); + return; + } + console.log('delete success'); +}); +``` +### delete9+ + +delete(): Promise\ + +禁用缓存并删除其中的数据,使用Promise方式作为异步方法。 + +**系统能力**:SystemCapability.Communication.NetStack + +**返回值:** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回删除结果。 | + +**错误码:** + +| 错误码ID | 错误信息 | +|---------|-------------------------------------------------------| +| 401 | Parameter error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 + +**示例:** + +```js +httpResponseCache.delete().then(() => { + console.log('delete success'); +}).catch(err => { + console.log('delete fail'); +}); +``` + +## HttpDataType9+ + +http的数据类型。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 值 | 说明 | +| ------------------ | -- | ----------- | +| STRING | 0 | 字符串类型。 | +| OBJECT | 1 | 对象类型。 | +| ARRAY_BUFFER | 2 | 二进制数组类型。| + +## HttpProtocol9+ + +http协议版本。 + +**系统能力**:SystemCapability.Communication.NetStack + +| 名称 | 说明 | +| :-------- | :----------- | +| HTTP1_1 | 协议http1.1 | +| HTTP2 | 协议http2 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-http.md b/zh-cn/application-dev/reference/apis/js-apis-http.md index dd8a5784ef..b43b8ec66a 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-http.md +++ b/zh-cn/application-dev/reference/apis/js-apis-http.md @@ -79,12 +79,11 @@ createHttp\(\): HttpRequest | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| -| 401 | Parameter error. | -| 2100002 | System internal error. | -| 2300999 | Unknown Other Error | +| 2300999 | Unknown Other Error. | -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -114,21 +113,19 @@ request\(url: string, callback: AsyncCallback\\):void | url | string | 是 | 发起网络请求的URL地址。 | | callback | AsyncCallback\<[HttpResponse](#httpresponse)\> | 是 | 回调函数。 | -**错误码:** +**错误码:** | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| | 401 | Parameter error. | -| 2300001 | Unsupported protocol | -| 2300003 | URL using bad/illegal format or missing URL | -| 2300005 | Couldn't resolve proxy name | -| 2300006 | Couldn't resolve host name | -| 2300007 | Couldn't connect to server | -| 2300052 | Server returned nothing (no headers, no data) | -| 2300999 | Unknown Other Error | - +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300007 | Couldn't connect to server. | +| 2300028 | Timeout was reached. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300999 | Unknown Other Error. | -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -163,22 +160,43 @@ request\(url: string, options: HttpRequestOptions, callback: AsyncCallback | 是 | 回调函数。 | -**错误码:** +**错误码:** | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| | 401 | Parameter error. | -| 2300001 | Unsupported protocol | -| 2300003 | URL using bad/illegal format or missing URL | -| 2300005 | Couldn't resolve proxy name | -| 2300006 | Couldn't resolve host name | -| 2300007 | Couldn't connect to server | -| 2300008 | Weird server reply | -| 2300009 | Access denied to remote resource | -| 2300999 | Unknown Other Error | - - -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -228,20 +246,43 @@ request\(url: string, options? : HttpRequestOptions\): Promise | :------------------------------------- | :-------------------------------- | | Promise<[HttpResponse](#httpresponse)> | 以Promise形式返回发起请求的结果。 | -**错误码:** +**错误码:** | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| | 401 | Parameter error. | -| 2300001 | Unsupported protocol | -| 2300003 | URL using bad/illegal format or missing URL | -| 2300005 | Couldn't resolve proxy name | -| 2300006 | Couldn't resolve host name | -| 2300007 | Couldn't connect to server | -| 2300009 | Access denied to remote resource | -| 2300999 | Unknown Other Error | - -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +| 2300001 | Unsupported protocol. | +| 2300003 | URL using bad/illegal format or missing URL. | +| 2300005 | Couldn't resolve proxy name. | +| 2300006 | Couldn't resolve host name. | +| 2300007 | Couldn't connect to server. | +| 2300008 | Weird server reply. | +| 2300009 | Access denied to remote resource. | +| 2300016 | Error in the HTTP2 framing layer. | +| 2300018 | Transferred a partial file. | +| 2300023 | Failed writing received data to disk/application. | +| 2300025 | Upload failed. | +| 2300026 | Failed to open/read local data from file/application. | +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300047 | Number of redirects hit maximum amount. | +| 2300052 | Server returned nothing (no headers, no data). | +| 2300055 | Failed sending data to the peer. | +| 2300056 | Failure when receiving data from the peer. | +| 2300058 | Problem with the local SSL certificate. | +| 2300059 | Couldn't use specified SSL cipher. | +| 2300060 | SSL peer certificate or SSH remote key was not OK. | +| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding.| +| 2300063 | Maximum file size exceeded. | +| 2300070 | Disk full or allocation exceeded. | +| 2300073 | Remote file already exists. | +| 2300077 | Problem with the SSL CA cert (path? access rights?). | +| 2300078 | Remote file not found. | +| 2300094 | An authentication function returned an error. | +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -278,10 +319,10 @@ destroy\(\): void | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| -| 401 | Parameter error. | -| 2300999 | Unknown Other Error | +| 2300999 | Unknown Other Error. | -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -307,34 +348,15 @@ on\(type: 'headerReceive', callback: AsyncCallback\): void | type | string | 是 | 订阅的事件类型,'headerReceive'。 | | callback | AsyncCallback\ | 是 | 回调函数。 | -**错误码:** +**错误码:** | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| | 401 | Parameter error. | -| 2300001 | Unsupported protocol | -| 2300003 | URL using bad/illegal format or missing URL | -| 2300005 | Couldn't resolve proxy name | -| 2300006 | Couldn't resolve host name | -| 2300007 | Couldn't connect to server | -| 2300008 | Weird server reply | -| 2300009 | Access denied to remote resource | -| 2300023 | Failed writing received data to disk/application | -| 2300025 | Upload failed | -| 2300027 | Out of memory | -| 2300028 | Timeout was reached | -| 2300052 | Server returned nothing (no headers, no data) | -| 2300056 | Failure when receiving data from the peer | -| 2300058 | Problem with the local SSL certificate | -| 2300060 | SSL peer certificate or SSH remote key was not OK | -| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | -| 2300063 | Maximum file size exceeded | -| 2300070 | Disk full or allocation exceeded | -| 2300077 | Problem with the SSL CA cert (path? access rights?) | -| 2300078 | Remote file not found | -| 2300999 | Unknown Other Error | - -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -369,21 +391,15 @@ off\(type: 'headerReceive', callback?: AsyncCallback\): void | type | string | 是 | 取消订阅的事件类型,'headerReceive'。 | | callback | AsyncCallback\ | 否 | 回调函数。 | -**错误码:** +**错误码:** | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| | 401 | Parameter error. | -| 2300001 | Unsupported protocol | -| 2300003 | URL using bad/illegal format or missing URL | -| 2300005 | Couldn't resolve proxy name | -| 2300006 | Couldn't resolve host name | -| 2300007 | Couldn't connect to server | -| 2300008 | Weird server reply | -| 2300009 | Access denied to remote resource | -| 2300999 | Unknown Other Error | +| 2300999 | Unknown Other Error. | -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -406,34 +422,15 @@ on\(type: 'headersReceive', callback: Callback\): void | type | string | 是 | 订阅的事件类型:'headersReceive'。 | | callback | Callback\ | 是 | 回调函数。 | -**错误码:** +**错误码:** | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| | 401 | Parameter error. | -| 2300001 | Unsupported protocol | -| 2300003 | URL using bad/illegal format or missing URL | -| 2300005 | Couldn't resolve proxy name | -| 2300006 | Couldn't resolve host name | -| 2300007 | Couldn't connect to server | -| 2300008 | Weird server reply | -| 2300009 | Access denied to remote resource | -| 2300023 | Failed writing received data to disk/application | -| 2300025 | Upload failed | -| 2300027 | Out of memory | -| 2300028 | Timeout was reached | -| 2300052 | Server returned nothing (no headers, no data) | -| 2300056 | Failure when receiving data from the peer | -| 2300058 | Problem with the local SSL certificate | -| 2300060 | SSL peer certificate or SSH remote key was not OK | -| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | -| 2300063 | Maximum file size exceeded | -| 2300070 | Disk full or allocation exceeded | -| 2300077 | Problem with the SSL CA cert (path? access rights?) | -| 2300078 | Remote file not found | -| 2300999 | Unknown Other Error | - -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -461,21 +458,15 @@ off\(type: 'headersReceive', callback?: Callback\): void | type | string | 是 | 取消订阅的事件类型:'headersReceive'。 | | callback | Callback\ | 否 | 回调函数。 | -**错误码:** +**错误码:** | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| | 401 | Parameter error. | -| 2300001 | Unsupported protocol | -| 2300003 | URL using bad/illegal format or missing URL | -| 2300005 | Couldn't resolve proxy name | -| 2300006 | Couldn't resolve host name | -| 2300007 | Couldn't connect to server | -| 2300008 | Weird server reply | -| 2300009 | Access denied to remote resource | -| 2300999 | Unknown Other Error | +| 2300999 | Unknown Other Error. | -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -498,34 +489,15 @@ once\(type: 'headersReceive', callback: Callback\): void | type | string | 是 | 订阅的事件类型:'headersReceive'。 | | callback | Callback\ | 是 | 回调函数。 | -**错误码:** +**错误码:** | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| | 401 | Parameter error. | -| 2300001 | Unsupported protocol | -| 2300003 | URL using bad/illegal format or missing URL | -| 2300005 | Couldn't resolve proxy name | -| 2300006 | Couldn't resolve host name | -| 2300007 | Couldn't connect to server | -| 2300008 | Weird server reply | -| 2300009 | Access denied to remote resource | -| 2300023 | Failed writing received data to disk/application | -| 2300025 | Upload failed | -| 2300027 | Out of memory | -| 2300028 | Timeout was reached | -| 2300052 | Server returned nothing (no headers, no data) | -| 2300056 | Failure when receiving data from the peer | -| 2300058 | Problem with the local SSL certificate | -| 2300060 | SSL peer certificate or SSH remote key was not OK | -| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | -| 2300063 | Maximum file size exceeded | -| 2300070 | Disk full or allocation exceeded | -| 2300077 | Problem with the SSL CA cert (path? access rights?) | -| 2300078 | Remote file not found | -| 2300999 | Unknown Other Error | - -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -653,32 +625,10 @@ createHttpResponseCache(cacheSize?: number): HttpResponseCache | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| | 401 | Parameter error. | -| 2300008 | Weird server reply | -| 2300009 | Access denied to remote resource | -| 2300016 | Error in the HTTP2 framing layer | -| 2300018 | Transferred a partial file | -| 2300023 | Failed writing received data to disk/application | -| 2300025 | Upload failed | -| 2300026 | Failed to open/read local data from file/application | -| 2300027 | Out of memory | -| 2300028 | Timeout was reached | -| 2300047 | Number of redirects hit maximum amount | -| 2300052 | Server returned nothing (no headers, no data) | -| 2300055 | Failed sending data to the peer | -| 2300056 | Failure when receiving data from the peer | -| 2300058 | Problem with the local SSL certificate | -| 2300059 | Couldn't use specified SSL cipher | -| 2300060 | SSL peer certificate or SSH remote key was not OK | -| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | -| 2300063 | Maximum file size exceeded | -| 2300070 | Disk full or allocation exceeded | -| 2300073 | Remote file already exists | -| 2300077 | Problem with the SSL CA cert (path? access rights?) | -| 2300078 | Remote file not found | -| 2300094 | An authentication function returned an error | -| 2300999 | Unknown Other Error | - -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +| 2300999 | Unknown Other Error. | + +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -710,92 +660,13 @@ flush(callback: AsyncCallback\): void | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| | 401 | Parameter error. | -| 2300001 | Unsupported protocol | -| 2300008 | Weird server reply | -| 2300009 | Access denied to remote resource | -| 2300016 | Error in the HTTP2 framing layer | -| 2300018 | Transferred a partial file | -| 2300023 | Failed writing received data to disk/application | -| 2300025 | Upload failed | -| 2300026 | Failed to open/read local data from file/application | -| 2300027 | Out of memory | -| 2300028 | Timeout was reached | -| 2300047 | Number of redirects hit maximum amount | -| 2300052 | Server returned nothing (no headers, no data) | -| 2300055 | Failed sending data to the peer | -| 2300056 | Failure when receiving data from the peer | -| 2300058 | Problem with the local SSL certificate | -| 2300059 | Couldn't use specified SSL cipher | -| 2300060 | SSL peer certificate or SSH remote key was not OK | -| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | -| 2300063 | Maximum file size exceeded | -| 2300070 | Disk full or allocation exceeded | -| 2300073 | Remote file already exists | -| 2300077 | Problem with the SSL CA cert (path? access rights?) | -| 2300078 | Remote file not found | -| 2300094 | An authentication function returned an error | -| 2300999 | Unknown Other Error | - -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +| 2300027 | Out of memory. | +| 2300028 | Timeout was reached. | +| 2300070 | Disk full or allocation exceeded. | +| 2300999 | Unknown Other Error. | -**示例:** - -```js -httpResponseCache.flush(err => { - if (err) { - console.log('flush fail'); - return; - } - console.log('flush success'); -}); -``` - -### flush9+ - -flush(): Promise\ - -将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用Promise方式作为异步方法。 - -**系统能力**:SystemCapability.Communication.NetStack - -**返回值:** - -| 类型 | 说明 | -| --------------------------------- | ------------------------------------- | -| Promise\> | 以Promise形式返回写入结果。 | - -**错误码:** - -| 错误码ID | 错误信息 | -|---------|-------------------------------------------------------| -| 401 | Parameter error. | -| 2300001 | Unsupported protocol | -| 2300008 | Weird server reply | -| 2300009 | Access denied to remote resource | -| 2300016 | Error in the HTTP2 framing layer | -| 2300018 | Transferred a partial file | -| 2300023 | Failed writing received data to disk/application | -| 2300025 | Upload failed | -| 2300026 | Failed to open/read local data from file/application | -| 2300027 | Out of memory | -| 2300028 | Timeout was reached | -| 2300047 | Number of redirects hit maximum amount | -| 2300052 | Server returned nothing (no headers, no data) | -| 2300055 | Failed sending data to the peer | -| 2300056 | Failure when receiving data from the peer | -| 2300058 | Problem with the local SSL certificate | -| 2300059 | Couldn't use specified SSL cipher | -| 2300060 | SSL peer certificate or SSH remote key was not OK | -| 2300061 | Unrecognized or bad HTTP Content or Transfer-Encoding | -| 2300063 | Maximum file size exceeded | -| 2300070 | Disk full or allocation exceeded | -| 2300073 | Remote file already exists | -| 2300077 | Problem with the SSL CA cert (path? access rights?) | -| 2300078 | Remote file not found | -| 2300094 | An authentication function returned an error | -| 2300999 | Unknown Other Error | - -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -826,16 +697,10 @@ delete(callback: AsyncCallback\): void | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| | 401 | Parameter error. | -| 2300001 | Unsupported protocol | -| 2300003 | URL using bad/illegal format or missing URL | -| 2300005 | Couldn't resolve proxy name | -| 2300006 | Couldn't resolve host name | -| 2300007 | Couldn't connect to server | -| 2300008 | Weird server reply | -| 2300009 | Access denied to remote resource | -| 2300999 | Unknown Other Error | +| 2300999 | Unknown Other Error. | -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** @@ -867,10 +732,10 @@ delete(): Promise\ | 错误码ID | 错误信息 | |---------|-------------------------------------------------------| | 401 | Parameter error. | -| 2300999 | Unknown Other Error | - +| 2300999 | Unknown Other Error. | -更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 +>**错误码说明:** +>HTTP 错误码映射关系:2300000 + curl错误码。更多常用错误码,可参考:[curl错误码](https://curl.se/libcurl/c/libcurl-errors.html)。 **示例:** -- GitLab