HarmonyOS SDK接入 - HTTPDNS

本章節介紹了HarmonyOS SDK的接入方法。

前言

本SDK基於HarmonyOS API 12開發，compileSdkVersion 為 5.0.0(12)。

說明

在Beta5以下版本的HarmonyOS中，開發人員在通過定製DNS解析規則訪問特定IP的伺服器時，必須在URL中顯式指定訪問連接埠，否則可能會導致定製DNS解析規則不生效，自動降級到LocalDNS

準備工作

請瞭解產品使用流程，擷取Account ID
請參考HarmonyOS應用開發文檔準備HarmonyOS應用開發環境

第一步：安裝SDK

在HarmonyOS應用根目錄執行以下命令安裝SDK：

ohpm install @aliyun/httpdns

ohpm工具及更多關於OpenHarmony安裝第三方SDK的資訊請參考OpenHarmony三方庫中心倉說明。

第二步：配置SDK

在Alibity onCreate生命週期回調中執行以下代碼配置SDK：

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = '這裡需要替換為阿里雲HTTPDNS控制台的Account ID'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // ************* 初始化配置 begin *************
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // 設定啟動服務節點，需明確選取目的地區域，可選Region為Region.SG、Region.HK、Region.US、Region.DE
      region: Region.SG, 
      useHttps: true,
    });
    // ************* 初始化配置 end *************
  }

  // 省略其它代碼
}

其中ACCOUNT_ID變數為產品使用流程中擷取Account ID。

重要

useHttps參數設定為true後，計費會增加，請仔細閱讀產品計費文檔。
如果您對網域名稱資訊或SDNS參數有更高的安全訴求，可以配置aesSecretKey參數啟用對解析請求進行內容層加密，使用內容加密後計費會增加，請仔細閱讀產品計費文檔。

第三步：使用SDK

addCustomDnsRule方式

在發起網路請求之前，調用SDK的網域名稱解析API進行HTTPDNS解析，通過connection.addCustomDnsRuleAPI配置HTTPDNS的解析結果，為當前應用程式添加自訂host和對應的IP地址的映射。以HTTP請求為例，代碼如下：

import { http } from '@kit.NetworkKit';
import connection from '@ohos.net.connection';
import { httpdns, IpType, } from '@aliyun/httpdns';
import Url from '@ohos.url';

const ACCOUNT_ID = '這裡需要替換為阿里雲HTTPDNS控制台的Account ID'

export async function requestWithHttpDns(url: string, options: http.HttpRequestOptions): Promise<http.HttpResponse> {
  let urlObject = Url.URL.parseURL(url);
  const host = urlObject.hostname;
  // ************* HTTPDNS解析擷取網域名稱 begin *************
  const httpdnsService = await httpdns.getService(ACCOUNT_ID);
  const result = await httpdnsService.getHttpDnsResultAsync(host, IpType.Auto);
  // ************* HTTPDNS解析擷取網域名稱 end *************
  // ************* 通過系統API設定DNS規則 begin *************
  try {
    await connection.removeCustomDnsRule(host);
  } catch (ignored) {
  }
  
  const allIps: string[] = [];
  if (result.ipv4s && result.ipv4s.length > 0) {
    allIps.push(...result.ipv4s);
  }
  if (result.ipv6s && result.ipv6s.length > 0) {
    allIps.push(...result.ipv6s);
  }
  if (allIps.length > 0) {
    console.info(`request with ${allIps?.join(',')}`);
    await connection.addCustomDnsRule(host, allIps);
  } else {
    console.log(`httpdns解析沒有結果，不設定dns`);
  }
  // ************* 通過系統API設定DNS規則 begin *************
  // ************* 通過系統API進行網路請求 begin *************
  const httpRequest = http.createHttp();
  return httpRequest.request(url, options);
  // ************* 通過系統API進行網路請求 end *************
}

其中ACCOUNT_ID變數為產品使用流程中擷取Account ID。

重要

HarmonyOS 如何定製DNS解析規則

HarmonyOS 提供了定製DNS解析規則的API：addCustomDnsRule、removeCustomDnsRule、clearCustomDnsRules。

通過addCustomDnsRule API應用可以添加自訂host和對應的IP地址的映射，

通過removeCustomDnsRule API應用可以刪除對應host的自訂DNS規則，

通過clearCustomDnsRules API應用可以刪除所有的自訂DNS規則。

因此，當應用想要定製網路請求的DNS規則時，可以在網路請求之前，通過上述API設定對應的規則，然後再發起網路請求。

Remote Communication Kit的dnsRules方式

當使用Remote Communication Kit包進行網路請求時，可以先調用SDK的網域名稱解析API進行HTTPDNS解析，然後通過配置dnsRules欄位，修改DNS規則，以fetch請求為例，代碼如下：

import { httpdns, IpType } from '@aliyun/httpdns';
import { rcp } from '@kit.RemoteCommunicationKit';
import Url from '@ohos.url';

const ACCOUNT_ID = '這裡需要替換為阿里雲HTTPDNS控制台的Account ID';

export async function rcpWithHttpDns(url: string): Promise<rcp.Response> {
  let urlObject = Url.URL.parseURL(url);
  const host = urlObject.hostname;

  // ************* HTTPDNS解析網域名稱擷取IP結果 begin *************
  const httpdnsService = await httpdns.getService(ACCOUNT_ID);
  const httpdnsResult = await httpdnsService.getHttpDnsResultAsync(host, IpType.Auto);
  let addresses: string[] = [];
  if (httpdnsResult.ipv4s) {
    addresses.push(...httpdnsResult.ipv4s)
  }
  if (httpdnsResult.ipv6s) {
    addresses.push(...httpdnsResult.ipv6s)
  }
  // ************* HTTPDNS解析網域名稱擷取IP結果 end *************

  const request = new rcp.Request(url, "GET");
  request.configuration = {
    dns: {
      // ************* 通過dnsRules設定IP begin *************
      dnsRules: [{
        host,
        port: 80,
        ipAddresses: addresses
      }, {
        host,
        port: 443,
        ipAddresses: addresses
      }]
      // ************* 通過dnsRules設定IP end *************
    }
  }

  // ************* 通過系統API進行網路請求 begin *************
  const session = rcp.createSession();
  return session.fetch(request);
  // ************* 通過系統API進行網路請求 end *************
}

其中ACCOUNT_ID變數為產品使用流程中擷取Account ID。

後續步驟

如果要對SDK進行更精細的配置或者使用鑒權請求等其它功能，可以參考HarmonyOS SDK API。