@ohos.net.http (Data Request)

The http module provides APIs for implementing HTTP data request capabilities. An application can initiate a data request over HTTP. Common HTTP methods include GET, POST, OPTIONS, HEAD, PUT, DELETE, TRACE, and CONNECT.

NOTE

The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { http } from '@kit.NetworkKit';

Example

// Import the http namespace.
import { http } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

// Each httpRequest corresponds to an HTTP request task and cannot be reused.
let httpRequest = http.createHttp();
// This API is used to listen for HTTP Response Header events, which is returned earlier than the result of the HTTP request. It is up to you whether to listen for HTTP response header events.
// on('headerReceive', AsyncCallback) is replaced by on('headersReceive', Callback) since API version 8.
httpRequest.on('headersReceive', (header: Object) => {
  console.info('header: ' + JSON.stringify(header));
});

httpRequest.request(// Customize EXAMPLE_URL in extraData on your own. It is up to you whether to add parameters to the URL.
  "EXAMPLE_URL",
  {
    method: http.RequestMethod.POST, // Optional. The default value is http.RequestMethod.GET.
    // This field is used to transfer the request body when a POST request is used. Its format needs to be negotiated with the server.
    extraData: 'data to send',
    expectDataType: http.HttpDataType.STRING, // Optional. This parameter specifies the type of the return data.
    usingCache: true, // Optional. The default value is true.
    priority: 1, // Optional. The default value is 1.
    // You can add header fields based on service requirements.
    header: { 'Accept' : 'application/json' },
    readTimeout: 60000, // Optional. The default value is 60000, in ms.
    connectTimeout: 60000 // Optional. The default value is 60000, in ms.
    usingProtocol: http.HttpProtocol.HTTP1_1, // Optional. The default protocol type is automatically specified by the system.
    usingProxy: false, // Optional. By default, network proxy is not used. This field is supported since API version 10.
    caPath: '/path/to/cacert.pem', // Optional. The preset CA certificate is used by default. This field is supported since API version 10.
    clientCert: { // Optional. The client certificate is not used by default. This field is supported since API version 11.
      certPath: '/path/to/client.pem', // The client certificate is not used by default. This field is supported since API version 11.
      keyPath: '/path/to/client.key', // If the certificate contains key information, an empty string is passed. This field is supported since API version 11.
      certType: http.CertType.PEM, // Certificate type, optional. A certificate in the PEM format is used by default. This field is supported since API version 11.
      keyPassword: "passwordToKey" // Password of the key file, optional. It is supported since API version 11.
    },
    certificatePinning: [ // Optional. It determines whether to enable dynamic configuration of certificate pinning. This attribute is supported since API version 12.
      {
        publicKeyHash: 'Pin1', // Certificate PIN passed by the application. This attribute is supported since API version 12.
        hashAlgorithm: 'SHA-256' // Encryption algorithm. Currently, it can only be set to SHA-256. This attribute is supported since API version 12.
      }, {
        publicKeyHash: 'Pin2', // Certificate PIN passed by the application. This attribute is supported since API version 12.
        hashAlgorithm: 'SHA-256' // Encryption algorithm. Currently, it can only be set to SHA-256. This attribute is supported since API version 12.
      }
    ],
    multiFormDataList: [ // Optional. This field is valid only when content-Type in the header is multipart/form-data. It is supported since API version 11.
      {
        name: "Part1", // Data name. This field is supported since API version 11.
        contentType: 'text/plain', // Data type. This field is supported since API version 11.
        data: 'Example data', // Data content, optional. This field is supported since API version 11.
        remoteFileName: 'example.txt' // Optional. This field is supported since API version 11.
      }, {
        name: "Part2", // Data name. This field is supported since API version 11.
        contentType: 'text/plain', // Data type. This field is supported since API version 11.
        // data/app/el2/100/base/com.example.myapplication/haps/entry/files/fileName.txt
        filePath: `${getContext(this).filesDir}/fileName.txt`, // File path, optional. This field is supported since API version 11.
        remoteFileName: 'fileName.txt' // Optional. This field is supported since API version 11.
      }
    ]
    addressFamily: http.AddressFamily.DEFAULT // Optional. By default, the IPv4 or IPv6 address of the target domain name is selected. This attribute is supported since API version 15.
  },
  (err: BusinessError, data: http.HttpResponse) => {
    if (!err) {
      // data.result carries the HTTP response. Parse the response based on service requirements.
      console.info('Result:' + JSON.stringify(data.result));
      console.info('code:' + JSON.stringify(data.responseCode));
      console.info('type:' + JSON.stringify(data.resultType));
      // data.header carries the HTTP response header. Parse the content based on service requirements.
      console.info('header:' + JSON.stringify(data.header));
      console.info('cookies:' + JSON.stringify(data.cookies)); // Cookies are supported since API version 8.
      // Unsubscribe from HTTP Response Header events.
      httpRequest.off('headersReceive');
      // Call destroy() to destroy the JavaScript object after the HTTP request is complete.
      httpRequest.destroy();
    } else {
      console.info('error:' + JSON.stringify(err));
      // Unsubscribe from HTTP Response Header events.
      httpRequest.off('headersReceive');
      // Call destroy() to destroy the JavaScript object after the HTTP request is complete.
      httpRequest.destroy();
    }
  });

NOTE If the data in console.info() contains a newline character, the data will be truncated.

HTTP responses compressed by the brotli algorithm are supported since API version 12.

http.createHttp

createHttp(): HttpRequest

Creates an HTTP request. You can use this API to initiate or destroy an HTTP request, or enable or disable listening for HTTP Response Header events. An HttpRequest object corresponds to an HTTP request. To initiate multiple HTTP requests, you must create an HttpRequest object for each HTTP request.

NOTE Call the destroy() method to release resources after the HttpRequest is complete.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
HttpRequest	An HttpRequest object, which contains the request, requestInStream, destroy, on, or off method.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();

HttpRequest

Defines an HTTP request task. Before invoking methods of HttpRequest, you must call createHttp() to create an HTTP request task.

request

request(url: string, callback: AsyncCallback<HttpResponse>): void

Initiates an HTTP request to a given URL. This API uses an asynchronous callback to return the result.

NOTE This API supports only receiving of data not greater than 5 MB. If the URL contains non-English characters, call encodeURL(url) to encode the URL before initiating an HTTP request.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
url	string	Yes	URL for initiating an HTTP request.
callback	AsyncCallback<HttpResponse>	Yes	Callback used to return the result.

Error codes

ID	Error Message
401	Parameter error.
201	Permission denied.
2300001	Unsupported protocol.
2300003	Invalid URL format or missing URL.
2300005	Failed to resolve the proxy name.
2300006	Failed to resolve the host name.
2300007	Failed to connect to the server.
2300008	Invalid server response.
2300009	Access to the remote resource denied.
2300016	Error in the HTTP2 framing layer.
2300018	Transferred a partial file.
2300023	Failed to write the received data to the disk or application.
2300025	Upload failed.
2300026	Failed to open or read local data from the file or application.
2300027	Out of memory.
2300028	Operation timeout.
2300047	The number of redirections reaches the maximum allowed.
2300052	The server returned nothing (no header or data).
2300055	Failed to send data to the peer.
2300056	Failed to receive data from the peer.
2300058	Local SSL certificate error.
2300059	The specified SSL cipher cannot be used.
2300060	Invalid SSL peer certificate or SSH remote key.
2300061	Invalid HTTP encoding format.
2300063	Maximum file size exceeded.
2300070	Remote disk full.
2300073	Remote file already exists.
2300077	The SSL CA certificate does not exist or is inaccessible.
2300078	Remote file not found.
2300094	Authentication error.
2300997	Cleartext traffic not permitted.
2300998	It is not allowed to access this domain.
2300999	Unknown error.

NOTE For details about the error codes, see Common Error Codes and HTTP Error Codes. The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.request("EXAMPLE_URL", (err: Error, data: http.HttpResponse) => {
  if (!err) {
    console.info('Result:' + data.result);
    console.info('code:' + data.responseCode);
    console.info('type:' + JSON.stringify(data.resultType));
    console.info('header:' + JSON.stringify(data.header));
    console.info('cookies:' + data.cookies); // Cookies are supported since API version 8.
  } else {
    console.info('error:' + JSON.stringify(err));
  }
});

request

request(url: string, options: HttpRequestOptions, callback: AsyncCallback<HttpResponse>):void

Initiates an HTTP request containing specified options to a given URL. This API uses an asynchronous callback to return the result.

NOTE This API can receive only data whose size is less than 5 MB. If the data size exceeds 5 MB, you need to set maxLimit to a larger value in HttpRequestOptions.

If you need to pass in cookies, add them to the options parameter.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
url	string	Yes	URL for initiating an HTTP request.
options	HttpRequestOptions	Yes	Request options. For details, see HttpRequestOptions.
callback	AsyncCallback<HttpResponse>	Yes	Callback used to return the result.

Error codes

ID	Error Message
401	Parameter error.
201	Permission denied.
2300001	Unsupported protocol.
2300003	Invalid URL format or missing URL.
2300005	Failed to resolve the proxy name.
2300006	Failed to resolve the host name.
2300007	Failed to connect to the server.
2300008	Invalid server response.
2300009	Access to the remote resource denied.
2300016	Error in the HTTP2 framing layer.
2300018	Transferred a partial file.
2300023	Failed to write the received data to the disk or application.
2300025	Upload failed.
2300026	Failed to open or read local data from the file or application.
2300027	Out of memory.
2300028	Operation timeout.
2300047	The number of redirections reaches the maximum allowed.
2300052	The server returned nothing (no header or data).
2300055	Failed to send data to the peer.
2300056	Failed to receive data from the peer.
2300058	Local SSL certificate error.
2300059	The specified SSL cipher cannot be used.
2300060	Invalid SSL peer certificate or SSH remote key.
2300061	Invalid HTTP encoding format.
2300063	Maximum file size exceeded.
2300070	Remote disk full.
2300073	Remote file already exists.
2300077	The SSL CA certificate does not exist or is inaccessible.
2300078	Remote file not found.
2300094	Authentication error.
2300997	Cleartext traffic not permitted.
2300998	It is not allowed to access this domain.
2300999	Unknown error.

NOTE For details about the error codes, see Common Error Codes and HTTP Error Codes. The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';

class Header {
  public contentType: string;

  constructor(contentType: string) {
    this.contentType = contentType;
  }
}

let httpRequest = http.createHttp();
let options: http.HttpRequestOptions = {
    method: http.RequestMethod.POST, // Optional. The default value is http.RequestMethod.GET.
    // This field is used to transfer the request body when a POST request is used. Its format needs to be negotiated with the server.
    extraData: 'data to send',
    expectDataType: http.HttpDataType.STRING, // Optional. This parameter specifies the type of the return data.
    usingCache: true, // Optional. The default value is true.
    priority: 1, // Optional. The default value is 1.
    // You can add header fields based on service requirements.
    header: new Header('application/json'),
    readTimeout: 60000, // Optional. The default value is 60000, in ms.
    connectTimeout: 60000 // Optional. The default value is 60000, in ms.
    usingProtocol: http.HttpProtocol.HTTP1_1, // Optional. The default protocol type is automatically specified by the system.
    usingProxy: false, // Optional. By default, network proxy is not used. This field is supported since API version 10.
};

httpRequest.request("EXAMPLE_URL", options, (err: Error, data: http.HttpResponse) => {
  if (!err) {
    console.info('Result:' + data.result);
    console.info('code:' + data.responseCode);
    console.info('type:' + JSON.stringify(data.resultType));
    console.info('header:' + JSON.stringify(data.header));
    console.info('cookies:' + data.cookies); // Cookies are supported since API version 8.
  } else {
    console.info('error:' + JSON.stringify(err));
  }
});

request

request(url: string, options? : HttpRequestOptions): Promise<HttpResponse>

Initiates an HTTP request containing specified options to a given URL. This API uses a promise to return the result.

NOTE This API can receive only data whose size is less than 5 MB. If the data size exceeds 5 MB, you need to set maxLimit to a larger value in HttpRequestOptions.

If you need to pass in cookies, add them to the options parameter.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
url	string	Yes	URL for initiating an HTTP request.
options	HttpRequestOptions	No	Request options. For details, see HttpRequestOptions.

Return value

Type	Description
Promise<HttpResponse>	Promise used to return the result.

Error codes

ID	Error Message
401	Parameter error.
201	Permission denied.
2300001	Unsupported protocol.
2300003	Invalid URL format or missing URL.
2300005	Failed to resolve the proxy name.
2300006	Failed to resolve the host name.
2300007	Failed to connect to the server.
2300008	Invalid server response.
2300009	Access to the remote resource denied.
2300016	Error in the HTTP2 framing layer.
2300018	Transferred a partial file.
2300023	Failed to write the received data to the disk or application.
2300025	Upload failed.
2300026	Failed to open or read local data from the file or application.
2300027	Out of memory.
2300028	Operation timeout.
2300047	The number of redirections reaches the maximum allowed.
2300052	The server returned nothing (no header or data).
2300055	Failed to send data to the peer.
2300056	Failed to receive data from the peer.
2300058	Local SSL certificate error.
2300059	The specified SSL cipher cannot be used.
2300060	Invalid SSL peer certificate or SSH remote key.
2300061	Invalid HTTP encoding format.
2300063	Maximum file size exceeded.
2300070	Remote disk full.
2300073	Remote file already exists.
2300077	The SSL CA certificate does not exist or is inaccessible.
2300078	Remote file not found.
2300094	Authentication error.
2300997	Cleartext traffic not permitted.
2300998	It is not allowed to access this domain.
2300999	Unknown error.

NOTE For details about the error codes, see Common Error Codes and HTTP Error Codes. The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';

class Header {
  public contentType: string;

  constructor(contentType: string) {
    this.contentType = contentType;
  }
}

let httpRequest = http.createHttp();
let promise = httpRequest.request("EXAMPLE_URL", {
  method: http.RequestMethod.GET,
  connectTimeout: 60000,
  readTimeout: 60000,
  header: new Header('application/json')
});
promise.then((data:http.HttpResponse) => {
  console.info('Result:' + data.result);
  console.info('code:' + data.responseCode);
  console.info('type:' + JSON.stringify(data.resultType));
  console.info('header:' + JSON.stringify(data.header));
  console.info('cookies:' + data.cookies); // Cookies are supported since API version 8.
  console.info('header.content-Type:' + data.header);
  console.info('header.Status-Line:' + data.header);
}).catch((err:Error) => {
  console.info('error:' + JSON.stringify(err));
});

destroy

destroy(): void

Destroys an HTTP request.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Example

import { http } from '@kit.NetworkKit';
let httpRequest = http.createHttp();

httpRequest.destroy();

requestInStream¹⁰⁺

requestInStream(url: string, callback: AsyncCallback<number>): void

Initiates an HTTP request containing specified options to a given URL. This API uses an asynchronous callback to return the result, which is a streaming response.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
url	string	Yes	URL for initiating an HTTP request.
callback	AsyncCallback<number>	Yes	Callback used to return the result.

Error codes

ID	Error Message
401	Parameter error.
201	Permission denied.
2300001	Unsupported protocol.
2300003	Invalid URL format or missing URL.
2300005	Failed to resolve the proxy name.
2300006	Failed to resolve the host name.
2300007	Failed to connect to the server.
2300008	Invalid server response.
2300009	Access to the remote resource denied.
2300016	Error in the HTTP2 framing layer.
2300018	Transferred a partial file.
2300023	Failed to write the received data to the disk or application.
2300025	Upload failed.
2300026	Failed to open or read local data from the file or application.
2300027	Out of memory.
2300028	Operation timeout.
2300047	The number of redirections reaches the maximum allowed.
2300052	The server returned nothing (no header or data).
2300055	Failed to send data to the peer.
2300056	Failed to receive data from the peer.
2300058	Local SSL certificate error.
2300059	The specified SSL cipher cannot be used.
2300060	Invalid SSL peer certificate or SSH remote key.
2300061	Invalid HTTP encoding format.
2300063	Maximum file size exceeded.
2300070	Remote disk full.
2300073	Remote file already exists.
2300077	The SSL CA certificate does not exist or is inaccessible.
2300078	Remote file not found.
2300094	Authentication error.
2300997	Cleartext traffic not permitted.
2300998	It is not allowed to access this domain.
2300999	Unknown error.

NOTE For details about the error codes, see Common Error Codes and HTTP Error Codes. The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

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

let httpRequest = http.createHttp();
httpRequest.requestInStream("EXAMPLE_URL", (err: BusinessError, data: number) => {
  if (!err) {
    console.info("requestInStream OK! ResponseCode is " + JSON.stringify(data));
  } else {
    console.info("requestInStream ERROR : err = " + JSON.stringify(err));
  }
})

requestInStream¹⁰⁺

requestInStream(url: string, options: HttpRequestOptions, callback: AsyncCallback<number>): void

Initiates an HTTP request containing specified options to a given URL. This API uses an asynchronous callback to return the result, which is a streaming response.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
url	string	Yes	URL for initiating an HTTP request.
options	HttpRequestOptions	Yes	Request options. For details, see HttpRequestOptions.
callback	AsyncCallback<number>	Yes	Callback used to return the result.

Error codes

ID	Error Message
401	Parameter error.
201	Permission denied.
2300001	Unsupported protocol.
2300003	Invalid URL format or missing URL.
2300005	Failed to resolve the proxy name.
2300006	Failed to resolve the host name.
2300007	Failed to connect to the server.
2300008	Invalid server response.
2300009	Access to the remote resource denied.
2300016	Error in the HTTP2 framing layer.
2300018	Transferred a partial file.
2300023	Failed to write the received data to the disk or application.
2300025	Upload failed.
2300026	Failed to open or read local data from the file or application.
2300027	Out of memory.
2300028	Operation timeout.
2300047	The number of redirections reaches the maximum allowed.
2300052	The server returned nothing (no header or data).
2300055	Failed to send data to the peer.
2300056	Failed to receive data from the peer.
2300058	Local SSL certificate error.
2300059	The specified SSL cipher cannot be used.
2300060	Invalid SSL peer certificate or SSH remote key.
2300061	Invalid HTTP encoding format.
2300063	Maximum file size exceeded.
2300070	Remote disk full.
2300073	Remote file already exists.
2300077	The SSL CA certificate does not exist or is inaccessible.
2300078	Remote file not found.
2300094	Authentication error.
2300997	Cleartext traffic not permitted.
2300998	It is not allowed to access this domain.
2300999	Unknown error.

NOTE For details about the error codes, see Common Error Codes and HTTP Error Codes. The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

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

class Header {
  public contentType: string;

  constructor(contentType: string) {
    this.contentType = contentType;
  }
}

let httpRequest = http.createHttp();
let options: http.HttpRequestOptions = {
    method: http.RequestMethod.POST, // Optional. The default value is http.RequestMethod.GET.
    // This field is used to transfer the request body when a POST request is used. Its format needs to be negotiated with the server.
    extraData: 'data to send',
    expectDataType: http.HttpDataType.STRING, // Optional. This parameter specifies the type of the return data.
    usingCache: true, // Optional. The default value is true.
    priority: 1, // Optional. The default value is 1.
    // You can add header fields based on service requirements.
    header: new Header('application/json'),
    readTimeout: 60000, // Optional. The default value is 60000, in ms.
    connectTimeout: 60000 // Optional. The default value is 60000, in ms.
    usingProtocol: http.HttpProtocol.HTTP1_1, // Optional. The default protocol type is automatically specified by the system.
    usingProxy: false, // Optional. By default, network proxy is not used. This field is supported since API version 10.
};
httpRequest.requestInStream("EXAMPLE_URL", options, (err: BusinessError<void> , data: number) => {
  if (!err) {
    console.info("requestInStream OK! ResponseCode is " + JSON.stringify(data));
  } else {
    console.info("requestInStream ERROR : err = " + JSON.stringify(err));
  }
})

requestInStream¹⁰⁺

requestInStream(url: string, options? : HttpRequestOptions): Promise<number>

Initiates an HTTP request containing specified options to a given URL. This API uses a promise to return the result, which is a streaming response.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
url	string	Yes	URL for initiating an HTTP request.
options	HttpRequestOptions	No	Request options. For details, see HttpRequestOptions.

Return value

Type	Description
Promise<number>	Promise used to return the result.

Error codes

ID	Error Message
401	Parameter error.
201	Permission denied.
2300001	Unsupported protocol.
2300003	Invalid URL format or missing URL.
2300005	Failed to resolve the proxy name.
2300006	Failed to resolve the host name.
2300007	Failed to connect to the server.
2300008	Invalid server response.
2300009	Access to the remote resource denied.
2300016	Error in the HTTP2 framing layer.
2300018	Transferred a partial file.
2300023	Failed to write the received data to the disk or application.
2300025	Upload failed.
2300026	Failed to open or read local data from the file or application.
2300027	Out of memory.
2300028	Operation timeout.
2300047	The number of redirections reaches the maximum allowed.
2300052	The server returned nothing (no header or data).
2300055	Failed to send data to the peer.
2300056	Failed to receive data from the peer.
2300058	Local SSL certificate error.
2300059	The specified SSL cipher cannot be used.
2300060	Invalid SSL peer certificate or SSH remote key.
2300061	Invalid HTTP encoding format.
2300063	Maximum file size exceeded.
2300070	Remote disk full.
2300073	Remote file already exists.
2300077	The SSL CA certificate does not exist or is inaccessible.
2300078	Remote file not found.
2300094	Authentication error.
2300997	Cleartext traffic not permitted.
2300998	It is not allowed to access this domain.
2300999	Unknown error.

NOTE For details about the error codes, see Common Error Codes and HTTP Error Codes. The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';

class Header {
  public contentType: string;

  constructor(contentType: string) {
    this.contentType = contentType;
  }
}

let httpRequest = http.createHttp();
let promise = httpRequest.requestInStream("EXAMPLE_URL", {
  method: http.RequestMethod.GET,
  connectTimeout: 60000,
  readTimeout: 60000,
  header: new Header('application/json')
});
promise.then((data: number) => {
  console.info("requestInStream OK!" + data);
}).catch((err: Error) => {
  console.info("requestInStream ERROR : err = " + JSON.stringify(err));
});

on("headerReceive")^(deprecated)

on(type: "headerReceive", callback: AsyncCallback<Object>): void

Registers an observer for HTTP Response Header events.

NOTE This API has been deprecated. You are advised to use on("headersReceive")⁸⁺.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is headerReceive.
callback	AsyncCallback<Object>	Yes	Callback used to return the result.

Example

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

let httpRequest = http.createHttp();
httpRequest.on("headerReceive", (data: BusinessError) => {
  console.info("error:" + JSON.stringify(data));
});

off("headerReceive")^(deprecated)

off(type: "headerReceive", callback?: AsyncCallback<Object>): void

Unregisters the observer for HTTP Response Header events.

NOTE

This API has been deprecated. You are advised to use off("headersReceive")⁸⁺.

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is headerReceive.
callback	AsyncCallback<Object>	No	Callback used to return the result.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.off("headerReceive");

on("headersReceive")⁸⁺

on(type: "headersReceive", callback: Callback<Object>): void

Registers an observer for HTTP Response Header events.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is headersReceive.
callback	Callback<Object>	Yes	Callback used to return the result.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("headersReceive", (header: Object) => {
  console.info("header: " + JSON.stringify(header));
});
httpRequest.off("headersReceive");

off("headersReceive")⁸⁺

off(type: "headersReceive", callback?: Callback<Object>): void

Unregisters the observer for HTTP Response Header events.

NOTE You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is headersReceive.
callback	Callback<Object>	No	Callback used to return the result.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("headersReceive", (header: Object) => {
  console.info("header: " + JSON.stringify(header));
});
httpRequest.off("headersReceive");

once("headersReceive")⁸⁺

once(type: "headersReceive", callback: Callback<Object>): void

Registers a one-time observer for HTTP Response Header events. Once triggered, the observer will be removed. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is headersReceive.
callback	Callback<Object>	Yes	Callback used to return the result.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.once("headersReceive", (header: Object) => {
  console.info("header: " + JSON.stringify(header));
});

on("dataReceive")¹⁰⁺

on(type: "dataReceive", callback: Callback<ArrayBuffer>): void

Registers an observer for events indicating receiving of HTTP streaming responses.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is dataReceive.
callback	AsyncCallback<ArrayBuffer>	Yes	Callback used to return the result.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataReceive", (data: ArrayBuffer) => {
  console.info("dataReceive length: " + JSON.stringify(data.byteLength));
});
httpRequest.off("dataReceive");

off("dataReceive")¹⁰⁺

off(type: "dataReceive", callback?: Callback<ArrayBuffer>): void

Unregisters the observer for events indicating receiving of HTTP streaming responses.

NOTE You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is dataReceive.
callback	Callback<ArrayBuffer>	No	Callback used to return the result.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataReceive", (data: ArrayBuffer) => {
  console.info("dataReceive length: " + JSON.stringify(data.byteLength));
});
httpRequest.off("dataReceive");

on("dataEnd")¹⁰⁺

on(type: "dataEnd", callback: Callback<void>): void

Registers an observer for events indicating completion of receiving HTTP streaming responses.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is dataEnd.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataEnd", () => {
  console.info("Receive dataEnd !");
});
httpRequest.off("dataEnd");

off("dataEnd")¹⁰⁺

off(type: "dataEnd", callback?: Callback<void>): void

Unregisters the observer for events indicating completion of receiving HTTP streaming responses.

NOTE You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is dataEnd.
callback	Callback<void>	No	Callback used to return the result.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataEnd", () => {
  console.info("Receive dataEnd !");
});
httpRequest.off("dataEnd");

on('dataReceiveProgress')¹⁰⁺

on(type: 'dataReceiveProgress', callback: Callback<DataReceiveProgressInfo>): void

Registers an observer for events indicating progress of receiving HTTP streaming responses.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is dataReceiveProgress.
callback	AsyncCallback<DataReceiveProgressInfo>	Yes	Callback used to return the result.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataReceiveProgress", (data: http.DataReceiveProgressInfo) => {
  console.info("dataReceiveProgress:" + JSON.stringify(data));
});
httpRequest.off("dataReceiveProgress");

off('dataReceiveProgress')¹⁰⁺

off(type: 'dataReceiveProgress', callback?: Callback<DataReceiveProgressInfo>): void

Unregisters the observer for events indicating progress of receiving HTTP streaming responses.

NOTE You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is dataReceiveProgress.
callback	Callback<DataReceiveProgressInfo>	No	Callback used to return the result.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataReceiveProgress", (data: http.DataReceiveProgressInfo) => {
  console.info("dataReceiveProgress:" + JSON.stringify(data));
});
httpRequest.off("dataReceiveProgress");

on('dataSendProgress')¹¹⁺

on(type: 'dataSendProgress', callback: Callback<DataSendProgressInfo>): void

Registers an observer for events indicating progress of sending HTTP requests.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is dataSendProgress.
callback	AsyncCallback<DataSendProgressInfo>	Yes	Callback used to return the result.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataSendProgress", (data: http.DataSendProgressInfo) => {
  console.info("dataSendProgress:" + JSON.stringify(data));
});
httpRequest.off("dataSendProgress");

off('dataSendProgress')¹¹⁺

off(type: 'dataSendProgress', callback?: Callback<DataSendProgressInfo>): void

Unregisters the observer for events indicating progress of sending HTTP requests.

NOTE You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is dataSendProgress.
callback	Callback<DataSendProgressInfo>	No	Callback used to return the result.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataSendProgress", (data: http.DataSendProgressInfo) => {
  console.info("dataSendProgress:" + JSON.stringify(data));
});
httpRequest.off("dataSendProgress");

HttpRequestOptions

Specifies the type and value range of the optional parameters in the HTTP request.

System capability: SystemCapability.Communication.NetStack

Name	Type	Mandatory	Description
method	RequestMethod	No	Request method. The default value is GET. Atomic service API: This API can be used in atomic services since API version 11.
extraData	string \|Object \|ArrayBuffer	No	Additional data for sending a request. This parameter is not used by default. - If the HTTP request uses a POST or PUT method, this field serves as the content of the HTTP request and is encoded in UTF-8 format. (1) If content-Type is application/x-www-form-urlencoded, the data in the request body must be encoded in the format of key1=value1&key2=value2&key3=value3 after URL transcoding (encodeURIComponent/encodeURI) and this field is usually in the String format. (2) If content-Type is text/xml, this field is usually in the String format. (3) If content-Type is application/json, this field is usually in the Object format. (4) If content-Type is application/octet-stream, this field is usually in the ArrayBuffer format. (5) If content-Type is multipart/form-data and the content to be uploaded is a file, this field is usually in the ArrayBuffer format. The preceding information is for reference only and may vary according to the actual situation. - If the HTTP request uses the GET, OPTIONS, DELETE, TRACE, or CONNECT method, this parameter serves as a supplement to HTTP request parameters. Parameters of the string type need to be encoded before being passed to the HTTP request. Parameters of the object type do not need to be precoded and will be directly concatenated to the URL. Parameters of the ArrayBuffer type will not be concatenated to the URL. Atomic service API: This API can be used in atomic services since API version 11.
expectDataType⁹⁺	HttpDataType	No	Type of the returned data. This parameter is not used by default. If this parameter is set, the system returns the specified type of data preferentially. If the specified type is Object, the value can contain a maximum of 65536 characters. Atomic service API: This API can be used in atomic services since API version 11.
usingCache⁹⁺	boolean	No	Whether to use the cache. The default value is true. The cache takes effect with the current process. The new cache will replace the old one. Atomic service API: This API can be used in atomic services since API version 11.
priority⁹⁺	number	No	Priority of concurrent HTTP/HTTPS requests. A larger value indicates a higher priority. The value range is [1,1000]. The default value is 1. Atomic service API: This API can be used in atomic services since API version 11.
header	Object	No	HTTP request header. If the request method is POST, PUT, DELETE, or null, the default value is {'content-Type': 'application/json'}. Otherwise, the default value is {'content-Type': 'application/x-www-form-urlencoded'}. Atomic service API: This API can be used in atomic services since API version 11.
readTimeout	number	No	Read timeout duration. The default value is 60000, in ms. The value 0 indicates no timeout. Atomic service API: This API can be used in atomic services since API version 11.
connectTimeout	number	No	Connection timeout interval. The default value is 60000, in ms. Atomic service API: This API can be used in atomic services since API version 11.
usingProtocol⁹⁺	HttpProtocol	No	Protocol. The default value is automatically specified by the system. Atomic service API: This API can be used in atomic services since API version 11.
usingProxy¹⁰⁺	boolean \|HttpProxy	No	Whether to use HTTP proxy. The default value is false, which means not to use HTTP proxy. - If usingProxy is of the Boolean type and the value is true, network proxy is used by default. - If usingProxy is of the HttpProxy type, the specified network proxy is used. Atomic service API: This API can be used in atomic services since API version 11.
caPath¹⁰⁺	string	No	Path of the CA certificate. If this parameter is set, the system uses the CA certificate in the specified path. Otherwise, the system uses the preset CA certificate. The preset CA certificate is available at /etc/ssl/certs/cacert.pem. This path is the sandbox mapping path, which can be obtained through getContext().filesDir. Currently, only .pem certificates are supported. Atomic service API: This API can be used in atomic services since API version 11.
resumeFrom¹¹⁺	number	No	Download start position. This field can be used only for the GET method. As stipulated in section 3.1 of RFC 7233, servers are allowed to ignore range requests. - If the HTTP PUT method is used, do not use this option because it may conflict with other options. - The value ranges from 1 to 4294967296 (4 GB). If the value is out of this range, this field does not take effect.
resumeTo¹¹⁺	number	No	Download end position. This field can be used only for the GET method. As stipulated in section 3.1 of RFC 7233, servers are allowed to ignore range requests. - If the HTTP PUT method is used, do not use this option because it may conflict with other options. - The value ranges from 1 to 4294967296 (4 GB). If the value is out of this range, this field does not take effect.
clientCert¹¹⁺	ClientCert	No	Client certificate.
dnsOverHttps¹¹⁺	string	No	DNS resolution for a server that uses the HTTPS protocol. - The value must be URL-encoded in the following format: "https://host:port/path".
dnsServers¹¹⁺	Array<string>	No	Array of DNS servers used for DNS resolution. - You can set a maximum of three DNS servers. If there are more than three DNS servers, only the first three DNS servers are used. - The DNS servers must be expressed as IPv4 or IPv6 addresses.
maxLimit¹¹⁺	number	No	Maximum number of bytes in a response. The default value is 510241024, in bytes. The maximum value is *10010241024*.
multiFormDataList¹¹⁺	Array<MultiFormData>	No	Form data list. This field is valid when content-Type is set to multipart/form-data.
certificatePinning¹²⁺	CertificatePinning \|CertificatePinning[]	No	Dynamic configuration of certificate pinning. One or more certificate PINs can be specified.
addressFamily¹⁵⁺	AddressFamily	No	IP address family. You can specify an address type for domain name resolution.
remoteValidation¹⁸⁺	RemoteValidation	No	Certificate authority (CA), which is used to verify the identity of a remote server. If the parameter is not set, the default value is used. The options are as follows: Atomic service API: This API can be used in atomic services since API version 18.
tlsOptions¹⁸⁺	TlsOptions	No	TLS configuration. Atomic service API: This API can be used in atomic services since API version 18.
serverAuthentication¹⁸⁺	ServerAuthentication	No	Indicates whether to verify the server identity during a secure connection. The identity is not verified by default. Atomic service API: This API can be used in atomic services since API version 18.

RequestMethod

Defines an HTTP request method.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Name	Value	Description
OPTIONS	"OPTIONS"	Describes the communication options of the target resource.
GET	"GET"	Requests the representation of the specified resource. The GET request should only retrieve data and should not contain the request content.
HEAD	"HEAD"	Requests the same response (but does not have a response body) as the GET request.
POST	"POST"	Submits an entity to a specified resource, which usually causes a status change on the server.
PUT	"PUT"	Replaces all current representations of the target resource with the requested content.
DELETE	"DELETE"	Deletes the specified resource.
TRACE	"TRACE"	Performs a message loopback test along the path to the target resource.
CONNECT	"CONNECT"	Establishes a tunnel to the server identified by the target resource.

ResponseCode

Enumerates the response codes for an HTTP request.

System capability: SystemCapability.Communication.NetStack

Name	Value	Description
OK	200	The request is successful. This return code is generally used for GET and POST requests. Atomic service API: This API can be used in atomic services since API version 11.
CREATED	201	"Created." The request has been successfully sent and a new resource is created. Atomic service API: This API can be used in atomic services since API version 11.
ACCEPTED	202	"Accepted." The request has been accepted for processing, but the processing has not been completed. Atomic service API: This API can be used in atomic services since API version 11.
NOT_AUTHORITATIVE	203	"Non-Authoritative Information." The request is successful. Atomic service API: This API can be used in atomic services since API version 11.
NO_CONTENT	204	"No Content." The server has successfully fulfilled the request but there is no additional content to send in the response payload body. Atomic service API: This API can be used in atomic services since API version 11.
RESET	205	"Reset Content." The server has successfully fulfilled the request and desires that the user agent reset the content. Atomic service API: This API can be used in atomic services since API version 11.
PARTIAL	206	"Partial Content." The server has successfully fulfilled the partial GET request for a given resource. Atomic service API: This API can be used in atomic services since API version 11.
MULT_CHOICE	300	"Multiple Choices." The requested resource corresponds to any one of a set of representations. Atomic service API: This API can be used in atomic services since API version 11.
MOVED_PERM	301	"Moved Permanently." The requested resource has been assigned a new permanent URI and any future references to this resource will be redirected to this URI. Atomic service API: This API can be used in atomic services since API version 11.
MOVED_TEMP	302	"Moved Temporarily." The requested resource is moved temporarily to a different URI. Atomic service API: This API can be used in atomic services since API version 11.
SEE_OTHER	303	"See Other." The response to the request can be found under a different URI. Atomic service API: This API can be used in atomic services since API version 11.
NOT_MODIFIED	304	"Not Modified." The client has performed a conditional GET request and access is allowed, but the content has not been modified. Atomic service API: This API can be used in atomic services since API version 11.
USE_PROXY	305	"Use Proxy." The requested resource can only be accessed through the proxy. Atomic service API: This API can be used in atomic services since API version 11.
BAD_REQUEST	400	"Bad Request." The request could not be understood by the server due to incorrect syntax. Atomic service API: This API can be used in atomic services since API version 11.
UNAUTHORIZED	401	"Unauthorized." The request requires user authentication. Atomic service API: This API can be used in atomic services since API version 11.
PAYMENT_REQUIRED	402	"Payment Required." This code is reserved for future use. Atomic service API: This API can be used in atomic services since API version 11.
FORBIDDEN	403	"Forbidden." The server understands the request but refuses to process it. Atomic service API: This API can be used in atomic services since API version 11.
NOT_FOUND	404	"Not Found." The server does not find anything matching the Request-URI. Atomic service API: This API can be used in atomic services since API version 11.
BAD_METHOD	405	"Method Not Allowed." The method specified in the request is not allowed for the resource identified by the Request-URI. Atomic service API: This API can be used in atomic services since API version 11.
NOT_ACCEPTABLE	406	"Not Acceptable." The server cannot fulfill the request according to the content characteristics of the request. Atomic service API: This API can be used in atomic services since API version 11.
PROXY_AUTH	407	"Proxy Authentication Required." The request requires user authentication with the proxy. Atomic service API: This API can be used in atomic services since API version 11.
CLIENT_TIMEOUT	408	"Request Timeout." The client fails to generate a request within the timeout period. Atomic service API: This API can be used in atomic services since API version 11.
CONFLICT	409	"Conflict." The request cannot be fulfilled due to a conflict with the current state of the resource. Conflicts are most likely to occur in response to a PUT request. Atomic service API: This API can be used in atomic services since API version 11.
GONE	410	"Gone." The requested resource has been deleted permanently and is no longer available. Atomic service API: This API can be used in atomic services since API version 11.
LENGTH_REQUIRED	411	"Length Required." The server refuses to process the request without a defined Content-Length. Atomic service API: This API can be used in atomic services since API version 11.
PRECON_FAILED	412	"Precondition Failed." The precondition in the request is incorrect. Atomic service API: This API can be used in atomic services since API version 11.
ENTITY_TOO_LARGE	413	"Request Entity Too Large." The server refuses to process a request because the request entity is larger than the server is able to process. Atomic service API: This API can be used in atomic services since API version 11.
REQ_TOO_LONG	414	"Request-URI Too Long." The Request-URI is too long for the server to process. Atomic service API: This API can be used in atomic services since API version 11.
UNSUPPORTED_TYPE	415	"Unsupported Media Type." The server is unable to process the media format in the request. Atomic service API: This API can be used in atomic services since API version 11.
RANGE_NOT_SATISFIABLE¹²⁺	416	"Range Not Satisfiable." The server cannot serve the requested ranges. Atomic service API: This API can be used in atomic services since API version 12.
INTERNAL_ERROR	500	"Internal Server Error." The server encounters an unexpected error that prevents it from fulfilling the request. Atomic service API: This API can be used in atomic services since API version 11.
NOT_IMPLEMENTED	501	"Not Implemented." The server does not support the function required to fulfill the request. Atomic service API: This API can be used in atomic services since API version 11.
BAD_GATEWAY	502	"Bad Gateway." The server acting as a gateway or proxy receives an invalid response from the upstream server. Atomic service API: This API can be used in atomic services since API version 11.
UNAVAILABLE	503	"Service Unavailable." The server is currently unable to process the request due to a temporary overload or system maintenance. Atomic service API: This API can be used in atomic services since API version 11.
GATEWAY_TIMEOUT	504	"Gateway Timeout." The server acting as a gateway or proxy does not receive requests from the remote server within the timeout period. Atomic service API: This API can be used in atomic services since API version 11.
VERSION	505	"HTTP Version Not Supported." The server does not support the HTTP protocol version used in the request. Atomic service API: This API can be used in atomic services since API version 11.

HttpResponse

Defines the response to an HTTP request.

System capability: SystemCapability.Communication.NetStack

Name	Type	Mandatory	Description
result	string \|Object \|ArrayBuffer	Yes	Response content returned based on Content-type in the response header. If HttpRequestOptions does not contain the expectDataType field, the response content is returned according to the following rules: - application/json: string in JSON format - application/octet-stream: ArrayBuffer - image: ArrayBuffer - Others: string If HttpRequestOptions contains the expectDataType field, the response content must be of the same type as the data returned by the server. Atomic service API: This API can be used in atomic services since API version 11.
resultType⁹⁺	HttpDataType	Yes	Type of the return value. Atomic service API: This API can be used in atomic services since API version 11.
responseCode	ResponseCode \|number	Yes	Result code for an HTTP request. If the callback function is successfully executed, a result code defined in ResponseCode will be returned. Otherwise, an error code will be returned in the err field in AsyncCallback. Atomic service API: This API can be used in atomic services since API version 11.
header	Object	Yes	Response header. The return value is a string in JSON format. If you want to use specific content in the response, you need to implement parsing of that content. Common fields and parsing methods are as follows: - content-type: header['content-type'] - status-line: header['status-line'] - date: header.date/header['date'] - server: header.server/header['server'] Atomic service API: This API can be used in atomic services since API version 11.
cookies⁸⁺	string	Yes	Original cookies returned by the server. How to process the cookies is up to your decision. Atomic service API: This API can be used in atomic services since API version 11.
performanceTiming¹¹⁺	PerformanceTiming	Yes	Time consumed in each phase of an HTTP request.

ClientCert¹¹⁺

Defines the client certificate type.

System capability: SystemCapability.Communication.NetStack

Name	Type	Mandatory	Description
certPath	string	Yes	Certificate path.
certType	CertType	No	Certificate type. The default value is PEM.
keyPath	string	Yes	Path of the certificate key file.
keyPassword	string	No	Password of the certificate key file.

PerformanceTiming¹¹⁺

Configures the timing for performance tracing, in ms.

System capability: SystemCapability.Communication.NetStack

Name	Type	Mandatory	Description
dnsTiming	number	Yes	Duration from the time when the request is sent to the time when the DNS resolution is complete.
tcpTiming	number	Yes	Duration from the time when the request is sent to the time when the TCP connection is complete.
tlsTiming	number	Yes	Duration from the time when the request is sent to the time when the TLS connection is complete.
firstSendTiming	number	Yes	Duration from the time when the request is sent to the time when the first byte is sent.
firstReceiveTiming	number	Yes	Duration from the time when the request is sent to the time when the first byte is received.
totalFinishTiming	number	Yes	Duration from the time when the request is sent to the time when the request is complete.
redirectTiming	number	Yes	Duration from the time when the request is sent to the time when all redirection steps are complete.
responseHeaderTiming	number	Yes	Duration from the time when the request is sent to the time when the header resolution is complete.
responseBodyTiming	number	Yes	Duration from the time when the request is sent to the time when the body resolution is complete.
totalTiming	number	Yes	Duration from the time when the request is sent to the time when a callback is returned to the application.

DataReceiveProgressInfo¹¹⁺

Defines the data receiving progress information.

System capability: SystemCapability.Communication.NetStack

Name	Type	Mandatory	Description
receiveSize	number	Yes	Size of data that has been received, in bytes.
totalSize	number	Yes	Total size of data to be received, in bytes.

DataSendProgressInfo¹¹⁺

Defines the data sending progress information.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Attributes

Name	Type	Mandatory	Description
sendSize	number	Yes	Size of data to be sent, in bytes.
totalSize	number	Yes	Total size of data to be sent, in bytes.

MultiFormData¹¹⁺

Defines the type of multi-form data.

System capability: SystemCapability.Communication.NetStack

Name	Type	Mandatory	Description
name	string	Yes	Data name.
contentType	string	Yes	Data type, for example, text/plain, image/png, image/jpeg, audio/mpeg, or video/mp4.
remoteFileName	string	No	Name of the file uploaded to the server.
data	string \|Object \|ArrayBuffer	No	Form data content.
filePath	string	No	File path. This field is used to configure the MIME body content based on the file content. This field is used as the substitute of data to set the file data as data content. If data is empty, filePath must be set. If data is present, filePath does not take effect.

http.createHttpResponseCache⁹⁺

createHttpResponseCache(cacheSize?: number): HttpResponseCache

Creates an HttpResponseCache object that stores the response data of HTTP requests. You can call the flush or delete method as needed in the object. cacheSize specifies the cache size.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
cacheSize	number	No	Cache size. The maximum value is 1010241024 (10 MB). By default, the maximum value is used.

Return value

Type	Description
HttpResponseCache	Object that stores the response to the HTTP request.

Example

import { http } from '@kit.NetworkKit';

let httpResponseCache = http.createHttpResponseCache();

HttpResponseCache⁹⁺

Defines an object that stores the response to an HTTP request. Before invoking APIs provided by HttpResponseCache, you must call createHttpResponseCache() to create an HttpRequestTask object.

Usage of Keywords in the Response Header

Cache-Control: specifies the cache policy, for example, no-cache, no-store, max-age, public, or private.
Expires: specifies the expiration time of a resource. The value is in the GMT format.
ETag: identifies the resource version. The client can use the If-None-Match request header to check whether the resource has been modified.
Last-Modified: specifies the last modification time of a resource. The client can use the If-Modified-Since request header to check whether a resource has been modified.
Vary: specifies the parts of the request header that affect the cached response. This field is used to distinguish different cache versions.

When using these keywords, ensure that the response header is correctly configured on the server. The client determines whether to use the cached resource and how to verify whether the resource is the latest based on the response header. Correct cache policies help to improve application performance and user experience.

How to Set the Cache-Control Header

Cache-Control is a common header, but it is usually used on the server. It allows you to define when, how, and how long a response should be cached. The following are some common Cache-Control directives:

no-cache: indicates that the response can be stored in the cache, but it must be verified with the origin server before each reuse. If the resource remains unchanged, the response status code is 304 (Not Modified). In this case, the resource content is not sent, and the resource in the cache is used. If the resource has expired, the response status code is 200 and the resource content is sent.
no-store: indicates that resources cannot be cached. Resources must be obtained from the server for each request.
max-age: specifies the maximum cache duration, in seconds. For example, Cache-Control: max-age=3600 indicates that the valid cache duration is 3,600 seconds (that is, 1 hour).
public: indicates that the response can be cached by any object, for example, the client that sends the request or the proxy server.
private: indicates that the response can be cached only by a single user and cannot be used as a shared cache (that is, the response cannot be cached by the proxy server).
must-revalidate: indicates that a resource must be revalidated with the origin server once it has become stable.
no-transform: indicates that the proxy server is not allowed to modify the response content.
proxy-revalidate: works in a way similar to must-revalidate, but applies only to shared caches.
s-maxage: works in a way similar to max-age, but applies only to shared caches.

flush⁹⁺

flush(callback: AsyncCallback<void>): void

Flushes data in the cache to the file system so that the cached data can be accessed in the next HTTP request. This API uses an asynchronous callback to return the result. Cached data includes the response header (header), response body (result), cookies, request time (requestTime), and response time (responseTime).

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

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

let httpResponseCache = http.createHttpResponseCache();
let httpRequest = http.createHttp();
httpRequest.request("EXAMPLE_URL", (err: BusinessError, data: http.HttpResponse) => {
  if (!err) {
    httpResponseCache.flush((err: BusinessError) => {
      if (err) {
        console.error('flush fail');
      }
      console.info('flush success');
    });
    httpRequest.destroy();
  } else {
    console.error('error:' + JSON.stringify(err));
    // Call destroy() to destroy the JavaScript object after the HTTP request is complete.
    httpRequest.destroy();
  }
});

flush⁹⁺

flush(): Promise<void>

Flushes data in the cache to the file system so that the cached data can be accessed in the next HTTP request. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<void>	Promise used to return the result.

Example

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

let httpRequest = http.createHttp();
let httpResponseCache = http.createHttpResponseCache();
let promise = httpRequest.request("EXAMPLE_URL");

promise.then((data: http.HttpResponse) => {
  httpResponseCache.flush().then(() => {
    console.error('flush success');
  }).catch((err: BusinessError) => {
    console.info('flush fail');
  });
}).catch((err: Error) => {
  console.error('error:' + JSON.stringify(err));
});

delete⁹⁺

delete(callback: AsyncCallback<void>): void

Disables the cache and deletes the data in it. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

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

let httpRequest = http.createHttp();
httpRequest.request("EXAMPLE_URL").then(data => {
  const httpResponseCache = http.createHttpResponseCache();
  httpResponseCache.delete((err: BusinessError) => {
    try {
      if (err) {
        console.error('fail: ' + err);
      } else {
        console.info('success');
      }
    } catch (err) {
      console.error('error: ' + err);
    }
  });
  httpRequest.destroy();
}).catch((error: BusinessError) => {
  console.error("errocode" + JSON.stringify(error));
});

delete⁹⁺

delete(): Promise<void>

Disables the cache and deletes the data in it. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<void>	Promise used to return the result.

Example

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

let httpRequest = http.createHttp();
httpRequest.request("EXAMPLE_URL").then(data => {
  const httpResponseCache = http.createHttpResponseCache();
  httpResponseCache.delete().then(() => {
    console.log("success");
  }).catch((err: BusinessError) => {
    console.error("fail");
  });
  httpRequest.destroy();
}).catch((error: BusinessError) => {
  console.error("errocode" + JSON.stringify(error));
});

HttpDataType⁹⁺

Enumerates HTTP data types.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Name	Value	Description
STRING	0	String type.
OBJECT	1	Object type.
ARRAY_BUFFER	2	Binary array type.

HttpProtocol⁹⁺

Enumerates HTTP protocol versions.

System capability: SystemCapability.Communication.NetStack

Name	Value	Description
HTTP1_1	0	HTTP1.1 Atomic service API: This API can be used in atomic services since API version 11.
HTTP2	1	HTTP2 Atomic service API: This API can be used in atomic services since API version 11.
HTTP3¹¹⁺	2	HTTP3 protocol. If the system or server does not support HTTP3, the HTTP protocol of an earlier version is used. This field is valid only for HTTPS URLs. For HTTP URLs, the request fails.

CertType¹¹⁺

Enumerates certificate types.

System capability: SystemCapability.Communication.NetStack

Name	Description
PEM	PEM certificate.
DER	DER certificate.
P12	P12 certificate.

CertificatePinning¹²⁺

Defines the dynamic configuration of certificate pinning.

System capability: SystemCapability.Communication.NetStack

Name	Type	Mandatory	Description
publicKeyHash	string	Yes	Certificate PIN of the string type.
hashAlgorithm	'SHA-256'	Yes	Encryption algorithm. Currently, only SHA-256 is supported.

HttpProxy¹⁰⁺

type HttpProxy = connection.HttpProxy

Defines the network proxy configuration.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Type	Description
connection.HttpProxy	Network proxy configuration.

AddressFamily¹⁵⁺

Enumerates the address types for domain name resolution.

System capability: SystemCapability.Communication.NetStack

Name	Description
DEFAULT	Automatically selects the IPv4 or IPv6 address of the target domain name.
ONLY_V4	Resolves only the IPv4 address of the target domain name and ignores the IPv6 address.
ONLY_V6	Resolves only the IPv6 address of the target domain name and ignores the IPv4 address.

RemoteValidation¹⁸⁺

type RemoteValidation = 'system'|'skip'

Certificate authority (CA), which is used to verify the identity of a remote server. You can configure RemoteValidation to use the system CA or skip CA verification.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Type	Description
'system'	Use of the system CA for verification.
'skip'	Skipping of CA verification.

Credential¹⁸⁺

Represents the credential used for server identity verification in a session, including the user name and password.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read Only	Optional	Description
username	string	No	No	User name used for verification. The default value is ''.
password	string	No	No	Password used for verification. The default value is ''.

ServerAuthentication¹⁸⁺

Defines HTTP server identity verification information.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read Only	Optional	Description
credential	Credential	No	No	Server credential. The default value is undefined.
authenticationType	AuthenticationType	No	Yes	Server identity verification type. If the type is not set, negotiation with the server is required.

TlsConfig¹⁸⁺

Defines the the TLS configuration, including the version and cipher suite.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read Only	Optional	Description
tlsVersionMin	TlsVersion	No	No	Earliest TLS version.
tlsVersionMax	TlsVersion	No	No	Latest TLS version.
cipherSuites	CipherSuite[]	No	Yes	Array of cipher suite types.

TlsVersion¹⁸⁺

Enumerates TLS versions.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Name	Value	Description
TLS_V_1_0	4	TLS version 1.0.
TLS_V_1_1	5	TLS version 1.1.
TLS_V_1_2	6	TLS version 1.2.
TLS_V_1_3	7	TLS version 1.3.

TlsOptions¹⁸⁺

type TlsOptions = 'system'|TlsConfig

Defines the TLS configuration.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Type	Description
'system'	TLS version of the system. This field is defaulted to system when the value is not set.
TlsOptions	Custom TLS version and cipher suites.

RemoteValidation¹⁸⁺

type RemoteValidation = 'system'|'skip'

Enumerates the identity verification modes of the remote server.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Type	Description
'system'	Use of the system CA. This field is defaulted to system when the value is not set.
'skip'	Skipping of CA verification. This field has a fixed value of skip.

AuthenticationType¹⁸⁺

type AuthenticationType = 'basic'|'ntlm'|'digest'

Enumerates server authentication modes in a session.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Type	Description
'basic'	Basic authentication mode. This field has a fixed value of basic.
'ntlm'	NTLM authentication mode. This field has a fixed value of ntlm.
'digest'	Digest authentication mode. This field has a fixed value of digest.

CipherSuite¹⁸⁺

type CipherSuite = TlsV13CipherSuite

Declares the cipher suite.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Type	Description
TlsV13CipherSuite	Cipher suite defined in TlsV13CipherSuite.

TlsV13CipherSuite¹⁸⁺

type TlsV13CipherSuite = TlsV12CipherSuite|TlsV13SpecificCipherSuite

Declares the cipher suite for TLS 1.3, which is also compatible with TLS 1.2.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Type	Description
TlsV12CipherSuite	TlsV12CipherSuite.
TlsV13SpecificCipherSuite	TlsV13SpecificCipherSuite.

TlsV12CipherSuite¹⁸⁺

type TlsV12CipherSuite = TlsV11CipherSuite|TlsV12SpecificCipherSuite

Declares the cipher suite for TLS 1.2, which is also compatible with TLS 1.1.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Type	Description
TlsV11CipherSuite	TlsV11CipherSuite.
TlsV12SpecificCipherSuite	TlsV12SpecificCipherSuite.

TlsV11CipherSuite¹⁸⁺

type TlsV11CipherSuite = TlsV10CipherSuite

Declares the cipher suite for TLS 1.1, which is the same as that for TLS1.0.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Type	Description
TlsV10CipherSuite	TlsV10CipherSuite.

TlsV10CipherSuite¹⁸⁺

type TlsV10CipherSuite = TlsV10SpecificCipherSuite

Declares the cipher suite for TLS 1.0.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Type	Description
TlsV10SpecificCipherSuite	TlsV10SpecificCipherSuite.

TlsV13SpecificCipherSuite¹⁸⁺

type TlsV13SpecificCipherSuite = 'TLS_AES_128_GCM_SHA256'|'TLS_AES_256_GCM_SHA384'|'TLS_CHACHA20_POLY1305_SHA256'

Enumerates cipher suites supported by TLS 1.3 or later.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Type	Description
'TLS_AES_128_GCM_SHA256'	Supported cipher suite: TLS_AES_128_GCM_SHA256. The value is a string.
'TLS_AES_256_GCM_SHA384'	Supported cipher suite: TLS_AES_256_GCM_SHA384. The value is a string.
'TLS_CHACHA20_POLY1305_SHA256'	Supported cipher suite: TLS_CHACHA20_POLY1305_SHA256. The value is a string.

TlsV12SpecificCipherSuite¹⁸⁺

type TlsV12SpecificCipherSuite = 'TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256'|'TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256'| 'TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384'|'TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384'| 'TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256'|'TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256'| 'TLS_RSA_WITH_AES_128_GCM_SHA256'|'TLS_RSA_WITH_AES_256_GCM_SHA384'

Enumerates cipher suites supported by TLS 1.2 or later.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Type	Description
'TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256'	Supported cipher suite: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256. The value is a string.
'TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256'	Supported cipher suite: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256. The value is a string.
'TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384'	Supported cipher suite: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384. The value is a string.
'TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384'	Supported cipher suite: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384. The value is a string.
'TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256'	Supported cipher suite: TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256. The value is a string.
'TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256'	Supported cipher suite: TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256. The value is a string.
'TLS_RSA_WITH_AES_128_GCM_SHA256'	Supported cipher suite: TLS_RSA_WITH_AES_128_GCM_SHA256. The value is a string.
'TLS_RSA_WITH_AES_256_GCM_SHA384'	Supported cipher suite: TLS_RSA_WITH_AES_256_GCM_SHA384. The value is a string.

TlsV10SpecificCipherSuite¹⁸⁺

Enumerates cipher suites supported by TLS 1.0 or later.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

Type	Description
'TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA'	Supported cipher suite: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA. The value is a string.
'TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA'	Supported cipher suite: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA. The value is a string.
'TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA'	Supported cipher suite: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA. The value is a string.
'TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA'	Supported cipher suite: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA. The value is a string.
'TLS_RSA_WITH_AES_128_CBC_SHA'	Supported cipher suite: TLS_RSA_WITH_AES_128_CBC_SHA. The value is a string.
'TLS_RSA_WITH_AES_256_CBC_SHA'	Supported cipher suite: TLS_RSA_WITH_AES_256_CBC_SHA. The value is a string.
'TLS_RSA_WITH_3DES_EDE_CBC_SHA'	Supported cipher suite: TLS_RSA_WITH_3DES_EDE_CBC_SHA. The value is a string.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Network Kit

harmony 鸿蒙NetConn_ConnectionProperties

harmony 鸿蒙NetConn_HttpProxy

harmony 鸿蒙NetConn_NetAddr

harmony 鸿蒙NetConn_NetCapabilities

harmony 鸿蒙NetConn_NetConnCallback

harmony 鸿蒙NetConn_NetHandle

harmony 鸿蒙NetConn_NetHandleList

harmony 鸿蒙NetConn_NetSpecifier

harmony 鸿蒙NetConn_Route

@ohos.net.http (Data Request)

Modules to Import

Example

http.createHttp

HttpRequest

request

request

request

destroy

requestInStream10+

requestInStream10+

requestInStream10+

on("headerReceive")(deprecated)

off("headerReceive")(deprecated)

on("headersReceive")8+

off("headersReceive")8+

once("headersReceive")8+

on("dataReceive")10+

off("dataReceive")10+

on("dataEnd")10+

off("dataEnd")10+

on('dataReceiveProgress')10+

off('dataReceiveProgress')10+

on('dataSendProgress')11+

off('dataSendProgress')11+

HttpRequestOptions

RequestMethod

ResponseCode

HttpResponse

ClientCert11+

PerformanceTiming11+

DataReceiveProgressInfo11+

DataSendProgressInfo11+

Attributes

MultiFormData11+

http.createHttpResponseCache9+

HttpResponseCache9+

flush9+

flush9+

delete9+

delete9+

HttpDataType9+

HttpProtocol9+

CertType11+

CertificatePinning12+

HttpProxy10+

AddressFamily15+

RemoteValidation18+

Credential18+

ServerAuthentication18+

TlsConfig18+

TlsVersion18+

TlsOptions18+

RemoteValidation18+

AuthenticationType18+

CipherSuite18+

TlsV13CipherSuite18+

TlsV12CipherSuite18+

TlsV11CipherSuite18+

TlsV10CipherSuite18+

TlsV13SpecificCipherSuite18+

TlsV12SpecificCipherSuite18+

TlsV10SpecificCipherSuite18+

你可能感兴趣的鸿蒙文章

标签云

最热博客

最新博客

requestInStream¹⁰⁺

requestInStream¹⁰⁺

requestInStream¹⁰⁺

on("headerReceive")^(deprecated)

off("headerReceive")^(deprecated)

on("headersReceive")⁸⁺

off("headersReceive")⁸⁺

once("headersReceive")⁸⁺

on("dataReceive")¹⁰⁺

off("dataReceive")¹⁰⁺

on("dataEnd")¹⁰⁺

off("dataEnd")¹⁰⁺

on('dataReceiveProgress')¹⁰⁺

off('dataReceiveProgress')¹⁰⁺

on('dataSendProgress')¹¹⁺

off('dataSendProgress')¹¹⁺

ClientCert¹¹⁺

PerformanceTiming¹¹⁺

DataReceiveProgressInfo¹¹⁺

DataSendProgressInfo¹¹⁺

MultiFormData¹¹⁺

http.createHttpResponseCache⁹⁺

HttpResponseCache⁹⁺

flush⁹⁺

flush⁹⁺

delete⁹⁺

delete⁹⁺

HttpDataType⁹⁺

HttpProtocol⁹⁺

CertType¹¹⁺

CertificatePinning¹²⁺

HttpProxy¹⁰⁺

AddressFamily¹⁵⁺

RemoteValidation¹⁸⁺

Credential¹⁸⁺

ServerAuthentication¹⁸⁺

TlsConfig¹⁸⁺

TlsVersion¹⁸⁺

TlsOptions¹⁸⁺

RemoteValidation¹⁸⁺

AuthenticationType¹⁸⁺

CipherSuite¹⁸⁺

TlsV13CipherSuite¹⁸⁺

TlsV12CipherSuite¹⁸⁺

TlsV11CipherSuite¹⁸⁺

TlsV10CipherSuite¹⁸⁺

TlsV13SpecificCipherSuite¹⁸⁺

TlsV12SpecificCipherSuite¹⁸⁺

TlsV10SpecificCipherSuite¹⁸⁺