Software-defined DNS-Enterprise Mobile Application Studio(EMAS)-阿里云帮助中心

This topic describes how to perform software-defined DNS resolution using the HarmonyOS SDK.

Terms

To learn how to use software-defined DNS, see the Overview and related documents.

Software-defined DNS

Compared to standard domain name resolution, software-defined DNS (SDNS) in the SDK requires you to manage SDNS parameters, cache keys, and extra parameters in the resolution results.

SDNS asynchronous requests

HTTPDNS provides the getSDnsResultAsync asynchronous method to perform SDNS resolution. The following is an example:

import { httpdns, HttpDnsError, HttpDnsResult, IpType } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console.';

httpdns.getService(ACCOUNT_ID).then((service) => {
  // ************* SDNS request begin *************
  return service.getSDnsResultAsync(HOST, { 'keyA': 'valueA' }, 'cacheKey1', IpType.Auto);
  // ************* SDNS request end *************
}).then((result: HttpDnsResult) => {
  console.log(`Resolved domain name: ${result.host}`);
  console.log(`Resolved IPv4 addresses: ${result.ipv4s?.join(',')}`);
  console.log(`Resolved IPv6 addresses: ${result.ipv6s?.join(',')}`);
  console.log(`SDNS extra parameters (string format): ${result.extraStr}`);
  console.log(`SDNS extra parameters (converted to an object): ${result.extra}`);
}).catch((e: HttpDnsError) => {
  console.error(`Failed: ${e.code} ${e.message}`);
});

The getSDnsResultAsync method has four parameters:

Parameter	Type	Required	Description
host	string	Yes	The domain name to resolve. This parameter has the same meaning as the host parameter of getHttpDnsResultAsync.
params	Record<string, string>	Yes	The parameters for this SDNS request, which is an object of key-value pairs. These parameters are consumed by the custom SDNS resolution function.
cacheKey	string	Yes	The cache identifier for this SDNS request. The SDK uses this key. Resolution results with the same cacheKey are stored in the same cache.
type	IpType	No	The expected IP address type. This parameter has the same meaning as the type parameter of getHttpDnsResultAsync. There are four options, with the default being IpType.V4. IpType.V4: Resolves IPv4 addresses. IpType.V6: Resolves IPv6 addresses. IpType.Both: Resolves both IPv4 and IPv6 addresses. IpType.Auto: The SDK determines the IP address type based on the device's current network stack. If the device supports only IPv4, the SDK resolves IPv4 addresses. If the device supports only IPv6 or supports both, the SDK resolves both IPv4 and IPv6 addresses.

The getSDnsResultAsync method returns an object with five parameters:

Parameter	Type	Description
host	string	The resolved domain name.
ipv4s	Array<string>	An array of resolved IPv4 addresses. If no result is found, this parameter is undefined.
ipv6s	Array<string>	An array of resolved IPv6 addresses. If no result is found, this parameter is undefined.
extraStr	string	The extra field set by the custom SDNS resolution function.
extra	Record<string, string>	The object of key-value pairs obtained from the JSON deserialization of the extraStr field.

Unlike getHttpDnsResultAsync, the getSDnsResultAsync method includes the params and cacheKey parameters. These parameters are used to pass arguments to the custom SDNS resolution function. The method also returns the extra and extraStr fields, which contain the value of the extra field set by the custom function.

SDNS common parameters

The SDK provides methods to simplify the management of common parameters for SDNS requests. The following is an example:

import { httpdns, HttpDnsError } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console.';

httpdns.getService(ACCOUNT_ID).then((service) => {
  // ************* SDNS common parameter maintenance begin *************
  // Add common parameters
  service.setSDnsGlobalParams({
    'globalKeyA': 'globalValueA',
    'globalKeyB': 'globalValueB'
  });
  // Clear common parameters
  service.clearSDnsGlobalParams();
  // ************* SDNS common parameter maintenance end *************
}).catch((e: HttpDnsError) => {
  console.error(`Failed: ${e.code} ${e.message}`);
});

You can use setSDnsGlobalParams to add common parameters and clearSDnsGlobalParams to clear them.

The added common parameters are included in each SDNS request.

Important

If a parameter key in a single SDNS request is the same as a common parameter key, the parameter in the single request overwrites the common parameter.

SDNS sync requests

Similar to getHttpDnsResultAsync, the SDK provides the getSDnsResultSyncNonBlocking method for synchronous SDNS resolution. The following is an example:

import { httpdns, HttpDnsError, HttpDnsResult, IpType } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console.';

httpdns.getService(ACCOUNT_ID).then((service) => {
  // ************* SDNS sync request begin *************
  const result = service.getSDnsResultSyncNonBlocking(HOST, { 'keyA': 'valueA' }, 'cacheKey1', IpType.Auto);
  // ************* SDNS sync request end *************
  console.log(`Resolved domain name: ${result.host}`);
  console.log(`Resolved IPv4 addresses: ${result.ipv4s?.join(',')}`);
  console.log(`Resolved IPv6 addresses: ${result.ipv6s?.join(',')}`);
  console.log(`SDNS extra parameters (string format): ${result.extraStr}`);
  console.log(`SDNS extra parameters (converted to an object): ${result.extra}`);
}).catch((e: HttpDnsError) => {
  console.error(`Failed: ${e.code} ${e.message}`);
});

The parameters and return value of the getSDnsResultSyncNonBlocking method are the same as those of the getSDnsResultAsync method.