网络探测

即对客户端设备进行网络诊断以获设备的网络状况，可以通过以下类、接口来设置 ICMPPing 、TCPPing 、MTR 等任务进行获取。当应用在后台时，触发网络探测任务将不执行。

网络探测类

类名	说明
NBSTaskCondition	网络探测任务执行条件类
NBSTCPPingDiagnosisTask	TCPPing 网络探测任务类
NBSICMPPingDiagnosisTask	ICMPPing 网络探测类
NBSMTRDiagnosisTask	MTR 网络探测类
NBSDownloadDiagnosisTask	Download 网络探测类

NBSTaskCondition

网络探测任务执行条件类 ，用于创建网络探测任务条件;可以设置场景、执行域名、错误码等属性。

• 接口

  /**
    * @param scene 任务执行场景
    * 支持以下两种场景
    * NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetFinished，请求后（响应码为 200）执行
    * NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetError，请求错误后执行
    * @return NBSTaskCondition.Builder
    */
  NBSTaskCondition.Builder(NBSDiagnosisTaskScene scene)
  
  /**
    * @param domain 匹配的域名，支持配置 host、uri（不能包含？及参数），支持 * 通配，如 *baidu.com、https://www.baidu*、*baidu.com*
    * @return NBSTaskCondition.Builder
    */
  NBSTaskCondition.Builder.patternDomains(List<String> domain)
  
  /**
    * @param errorCode 匹配的错误码，支持配置 http code 4xx、5xx，及 SDK 定义的部分网络错误码如 901（UnknownHostException）、902（ConnectException）、903(SocketTimeoutException)、908(SSLException) 等，仅可在 NBSDiagnosisTaskSceneAfterNetError (网络出错)场景下设置
    * @return NBSTaskCondition.Builder
    */
  NBSTaskCondition.Builder.patternErrorCodes(List<String> errorCode)
  
  /**
    * @return NBSTaskCondition
    */
  NBSTaskCondition.Builder.build()

• 示例

  // 执行条件为请求（响应为 200）完成后
  NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetFinished).build();
  
  // 执行条件为网络出错后
  NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetError).build();
  
  // 执行条件为 url 包含 baidu.com 的请求（响应为 200）完成
  NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetFinished)
  .patternDomains(new ArrayList<String>() {{
    add("*baidu.com*");
  }})
  .build();
  
  // 执行条件为 url 包含 baidu.com 的请求出错
  NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetError)
  .patternDomains(new ArrayList<String>() {{
    add("*baidu.com*");
  }})
  .build();
  
  // 执行条件为 url 包含 baidu.com 的请求出现 404 错误或超时错误
  NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetError)
  .patternDomains(new ArrayList<String>() {{
    add("*baidu.com*");
  }})
  .patternErrorCodes(new ArrayList<String>() {{
    add("404");
    add("903");
  }})
  .build()

NBSTCPPingDiagnosisTask

TCPPing 网络探测任务类，用于创建 TCPPing 网络探测任务。

• 接口

  /**
   * @param taskName 任务名称，最大支持 64 个字符，超长截取前 64 位
   * @param host 执行域名
   * @param port 端口号
   * @param condition 执行条件，仅配置轮询任务时配置
   * @return NBSTCPPingDiagnosisTask.Builder
     */
  NBSTCPPingDiagnosisTask.Builder(String taskName, String host, int port)
  NBSTCPPingDiagnosisTask.Builder(String taskName, String host, int port, NBSTaskCondition condition)
    
  /**
    * @param setRepeat ping 次数，默认 3 次，支持设置范围 3-100
    * @return NBSTCPPingDiagnosisTask.Builder
    */
  NBSTCPPingDiagnosisTask.Builder.setRepeat(int repeat)
  
  /**
    * @param execFrequency 执行频率，再次执行任务的间隔时间，默认 60 秒
    * @return NBSTCPPingDiagnosisTask.Builder
    */
  NBSTCPPingDiagnosisTask.Builder.setExecFrequency(int execFrequency)
  
  /**
    * @return NBSTCPPingDiagnosisTask
    */
  NBSTCPPingDiagnosisTask.Builder.build()

• 示例

  任务完整示例「任务创建到添加任务队列」⻅「立即执行」或「循环执行」。

  
  // 创建一个 tcpPing 任务(任务名为 tcpPing_task，执行域名和端口分别为 www.baidu.com、443)
  NBSTCPPingDiagnosisTask tcpPing = new NBSTCPPingDiagnosisTask.Builder("tcpPing_task", "www.baidu.com", 443).build();
  
  // 创建一个带 condition 条件的tcpPing任务(任务名为 tcpPing_task，执行域名和端口分别为 www.baidu.com、443)
  NBSTCPPingDiagnosisTask tcpPing = new NBSTCPPingDiagnosisTask.Builder("tcpPing_task", "www.baidu.com", 443, new NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetFinished).build()).build();
  
  // 创建一个带 condition 条件的tcpPing任务(任务名为 tcpPing_task，执行域名和端口分别为 www.baidu.com、443，ping 次数为 5 次，执行频率间隔为 30秒)
  NBSTCPPingDiagnosisTask tcpPing = new NBSTCPPingDiagnosisTask.Builder("tcpPing_task", "www.baidu.com", 443, new NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetFinished).build())
  .setRepeat(5)
  .execFrequency(30)
  .build();

NBSICMPPingDiagnosisTask

ICMPPing 网络探测类，用于创建 ICMPPing 网络探测任务。

• 接口

  /**
    * @param taskName 任务名称，最大支持 64 个字符，超长截取前 64 位
    * @param host 执行域名
    * @param codition 执行条件，仅配置轮询任务时配置
    * @return NBSICMPPingDiagnosisTask.Builder
      */
  NBSICMPPingDiagnosisTask.Builder(String taskName, String host)
  NBSICMPPingDiagnosisTask.Builder(String taskName, String host, NBSTaskCondition codition)
  
  /**
    * @param setRepeat ping 次数，默认 3 次，支持设置范围 3-100
    * @return NBSICMPPingDiagnosisTask.Builder
    */
  NBSICMPPingDiagnosisTask.Builder.setRepeat(int repeat)
  
  /**
    * @param execFrequency 执行频率，再次执行任务的间隔时间，默认 60 秒
    * @return NBSICMPPingDiagnosisTask.Builder
    */
  NBSICMPPingDiagnosisTask.Builder.setExecFrequency(int execFrequency)
  
  /**
    * @return NBSICMPPingDiagnosisTask
    */
  NBSICMPPingDiagnosisTask.Builder.build()

• 示例

  任务完整示例「任务创建到添加任务队列」⻅「立即执行」或「循环执行」。

  // 创建一个 icmpPing 任务(任务名为 icmpPing_task ，执行域名为 www.baidu.com)
  NBSICMPPingDiagnosisTask icmpPing = new NBSICMPPingDiagnosisTask.Builder("icmpPing_task", "www.baidu.com").build();
  
  // 创建一个带 condition 条件的 icmpPing 任务(任务名为 icmpPing_task，执行域名为 www.baidu.com)
  NBSICMPPingDiagnosisTask icmpPing = new NBSICMPPingDiagnosisTask.Builder("icmpPing_task", "www.baidu.com", new NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetFinished).build()).build();
  
  // 创建一个带 condition 条件的 icmpPing 任务(任务名为 icmpPing_task，执行域名为 www.baidu.com，ping 次数为 5 次，执行频率间隔为 30 秒)
  NBSICMPPingDiagnosisTask icmpPing = new NBSICMPPingDiagnosisTask.Builder("icmpPing_task", "www.baidu.com", new NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetFinished).build())
  .setRepeat(5)
  .execFrequency(30)
  .build();

NBSMTRDiagnosisTask

MTR 网络探测类，用于创建 MTR 网络探测任务。

• 接口

  /**
    * @param taskName 任务名称，最大支持 64 个字符，超长截取前 64 位
    * @param host 执行域名
    * @param codition 执行条件，仅配置轮询任务时配置
    * @return NBSMTRDiagnosisTask.Builder
    */
  NBSMTRDiagnosisTask.Builder(String taskName, String host)
  NBSMTRDiagnosisTask.Builder(String taskName, String host, NBSTaskCondition codition)
  
  /**
    * @param execFrequency 执行频率，再次执行任务的间隔时间，默认 60 秒
    * @return NBSMTRDiagnosisTask.Builder
    */
  NBSMTRDiagnosisTask.Builder.setExecFrequency(int execFrequency)
  
  /**
    * @return NBSMTRDiagnosisTask
    */
  NBSMTRDiagnosisTask.Builder.build()

• 示例

  任务完整示例「任务创建到添加任务队列」⻅「立即执行」或「循环执行」。

   
  //创建一个 MTR 任务(任务名为 mtr_task，执行域名为 www.baidu.com)
  NBSMTRDiagnosisTask mtr = new NBSMTRDiagnosisTask.Builder("mtr_task", "www.baidu.com").build();
  
  // 创建一个带 condition 条件的 MTR 任务(任务名为 mtr_task，执行域名为www.baidu.com)
  NBSMTRDiagnosisTask mtr = new NBSMTRDiagnosisTask.Builder("mtr_task", "www.baidu.com", new NBSTaskCondition.Builder(NBSICMPPingDiagnosisTask.NBSDiagnosisTaskSceneAfterNetFinished).build()).build();
  
  // 创建一个带 condition 条件的 MTR 任务(任务名为 mtr_task，执行域名为www.baidu.com，设置执行频率间隔为 300 秒)
  NBSMTRDiagnosisTask mrt = new NBSMTRDiagnosisTask.Builder("mtr_task", "www.baidu.com", new NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetFinished).build())
  .execFrequency(300)
  .build();

NBSDownloadDiagnosisTask

Download 网络探测类，用于创建 Download 网络探测任务「 Download 网络探测任务只支持立即 执行，即只能通过调用 startDiagnosisTask 添加」。

• 接口

  /**
    * @param taskName 任务名称，最大支持 64 个字符，超长截取前 64 位
    * @param url 执行 url
    * @return NBSDownloadDiagnosisTask.Builder
    */
  NBSDownloadDiagnosisTask.Builder(String taskName, String url)
  
  /**
    * @return NBSDownloadDiagnosisTask
    */
  NBSDownloadDiagnosisTask.Builder.build()

• 示例

  任务完整示例「任务创建到添加任务队列」⻅「立即执行」。

  // 创建一个 download 任务(任务名为 download_task，执行 url 为 https://www.baidu.com )
  NBSDownloadDiagnosisTask download = new NBSDownloadDiagnosisTask.Builder("download_task", "https://www.baidu.com").build();

任务类型

任务类型	说明
立即执行	任务立即执行，执行完后该任务消失
循环执行	任务轮循执行，满触发条件执行完后该任务，任务不消失

立即执行

添加 NBSDiagnosisTask 后会加入到立即执行队列，执行完后该任务消失。

• 接口

  /**
    * @param task 任务
    * 支持 NBSTCPPingDiagnosisTask、NBSICMPPingDiagnosisTask、NBSMTRDiagnosisTask 及 NBSDownloadDiagnosisTask
    */
  startDiagnosisTask(NBSDiagnosisTask task)

• 示例

  该示例为:当触发 startDiagnosisTask 方法时，会立即执行 TCPPing、ICMPPing、MTR、Download 网络探 测任务。

  // 创建一个 tcpPing 任务，taskName 为 tcpPing_task，执行域名为 www.baidu.com，ping 的端口为 443
  NBSTCPPingDiagnosisTask tcpPing = new NBSTCPPingDiagnosisTask.Builder("tcpPing_task", "www.baidu.com", 443).build();
  
  // 创建一个 ICMPPing 任务，taskName 为 icmpPing_task，执行域名为 www.baidu.com
  NBSICMPPingDiagnosisTask icmpPing = new NBSICMPPingDiagnosisTask.Builder("icmpPing_task", "www.baidu.com").build();
  
  // 创建一个 MTR 任务，taskName 为 mtr_task，执行域名为 www.baidu.com
  NBSMTRDiagnosisTask mtr = new NBSMTRDiagnosisTask.Builder("mtr_task", "www.baidu.com").build();
  
  // 创建一个 download 任务，taskName 为 download_task，执行 url 为 https://www.baidu.com
  NBSDownloadDiagnosisTask download = new NBSDownloadDiagnosisTask.Builder"download_task", "https://www.baidu.com").build();
  
  //执行任务
  NBSAppAgent.startDiagnosisTask(tcpPing);
  NBSAppAgent.startDiagnosisTask(icmpPing);
  NBSAppAgent.startDiagnosisTask(mtr);
  NBSAppAgent.startDiagnosisTask(download);

循环执行

添加 NBSDiagnosisTask 后会加入到轮循执行队列，每当满足触发的条件时会执行相应网络探测任务「执行频率会受网络探测任务中 execFrequency 属性限制」。

• 接口

  /**
    * @param task 任务
    * 支持 NBSTCPPingDiagnosisTask、NBSICMPPingDiagnosisTask 及 NBSMTRDiagnosisTask
    * 循环执行的任务必须设置 NBSTaskCondition 执行条件
    */
  addDiagnosisTask(NBSDiagnosisTask task)

  • 示例

    • 请求错误后轮循任务

    该示例为：当请求 URL「URL能匹配执行条件域名」出现 404、502、建联失败、请求超时错误时，会执行 TCPPing、ICMPPing、MTR 网络探测任务。

    NBSTaskCondition condition = new NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetError)
    .patternDomains(new ArrayList<String>() {{// 执行条件域名「可配制通配符*，如 『*qq.com、qq.com*、 *qq.com*』;但不支持只设置*」
    add("*.qq.com");
    }})
    .patternErrorCodes(new ArrayList<String>() {{// 为执行条件增加出错码条件:设置触发404、502、建联失败、请求超时错误时执行网络探测任务「若不设置patternErrorCodes，则所有请求错误都满足触发条件」 
    add("404");
    add("502");
    add("902");
    add("903");
    }})
    .build();
    
    // 创建一个 tcpPing 任务，taskName 为 tcpPing_task，执行域名为 www.baidu.com，ping 的端口为 443
    NBSTCPPingDiagnosisTask tcpPing = new NBSTCPPingDiagnosisTask.Builder("tcpPing_task", "www.baidu.com", 443, condition).build();
    
    // 创建一个 ICMPPing 任务，taskName 为 icmpPing_task，执行域名为 www.baidu.com
    NBSICMPPingDiagnosisTask icmpPing = new NBSICMPPingDiagnosisTask.Builder("icmpPing_task", "www.baidu.com", condition).build();
    
    // 创建一个 MTR 任务，taskName 为 mtr_task，执行域名为 www.baidu.com
    NBSMTRDiagnosisTask mtr = new NBSMTRDiagnosisTask.Builder("mtr_task", "www.baidu.com", condition).build();
    
    //将创建好的 tcpPing、icmpPing、mtr 任务加入到轮循执行任务队列中 「注:轮循执行任务不支持加入 Download 任务，若加入了Download任务也不会执行」
    NBSAppAgent.addDiagnosisTask(tcpPing);
    NBSAppAgent.addDiagnosisTask(icmpPing);
    NBSAppAgent.addDiagnosisTask(mtr);

    • 请求结束后轮循任务

    该示例为：当请求 URL「URL能匹配执行条件域名」正常结束后，会执行 TCPPing、ICMPPing、 MTR 网络探测任务。

    NBSTaskCondition condition = new NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetFinished).build();
    
    // 创建一个 tcpPing 任务，taskName 为 tcpPing_task，执行域名为 www.baidu.com，ping 的端口为 443
    NBSTCPPingDiagnosisTask tcpPing = new NBSTCPPingDiagnosisTask.Builder("tcpPing_task", "www.baidu.com", 443, condition).build();
    
    // 创建一个 ICMPPing 任务，taskName 为 icmpPing_task，执行域名为 www.baidu.com
    NBSICMPPingDiagnosisTask icmpPing = new NBSICMPPingDiagnosisTask.Builder("icmpPing_task", "www.baidu.com", condition).build();
    
    // 创建一个 MTR 任务，taskName 为 mtr_task，执行域名为 www.baidu.com
    NBSMTRDiagnosisTask mtr = new NBSMTRDiagnosisTask.Builder("mtr_task", "www.baidu.com", condition).build();
    
    //将创建好的 tcpPing、icmpPing、mtr 任务加入到轮循执行任务队列中 「注:轮循执行任务不支持加入 Download 任务，若加入了Download任务也不会执行」
    NBSAppAgent.addDiagnosisTask(tcpPing);
    NBSAppAgent.addDiagnosisTask(icmpPing);
    NBSAppAgent.addDiagnosisTask(mtr);

网络探测数据回传

网络探测数据回传即将执行的网络探测任务结果通过回调接口返回，您可以使用该结果进行相应开发。

• 示例

  NBSDiagnosisTaskDelegate delegate = new NBSDiagnosisTaskDelegate() {
      @Override
      public void diagnosisTask(NBSDiagnosisTaskResult nbsDiagnosisTaskResult) {
          try {// 建议对返回数据做判空，或添加 catch
              if (nbsDiagnosisTaskResult instanceof NBSTCPPingDiagnosisTaskResult) {
                  NBSTCPPingDiagnosisTaskResult tcpResult = (NBSTCPPingDiagnosisTaskResult) nbsDiagnosisTaskResult;
                  ...
              } else if (nbsDiagnosisTaskResult instanceof NBSICMPPingDiagnosisTaskResult) {
                  NBSICMPPingDiagnosisTaskResult icmpPingResult = (NBSICMPPingDiagnosisTaskResult) nbsDiagnosisTaskResult;
                  ...
              } else if (nbsDiagnosisTaskResult instanceof NBSMTRDiagnosisTaskResult) {
                  NBSMTRDiagnosisTaskResult mtrResult = (NBSMTRDiagnosisTaskResult) nbsDiagnosisTaskResult;
                  ...
              } else if (nbsDiagnosisTaskResult instanceof NBSDownloadDiagnosisTaskResult) {
                  NBSDownloadDiagnosisTaskResult downloadTaskResult = (NBSDownloadDiagnosisTaskResult) nbsDiagnosisTaskResult;
                  ...
              }
          }catch (Exception e) {      
          }
      }
  }    
  
  NBSTCPPingDiagnosisTask tcpPing = new NBSTCPPingDiagnosisTask.Builder("tcpPing_task", "www.baidu.com", 443).build();
  tcpPing.setDelegate(delegate);
  NBSAppAgent.startDiagnosisTask(tcpPing);
  
  NBSICMPPingDiagnosisTask icmpPing = new NBSICMPPingDiagnosisTask.Builder("icmpPing_task", "www.baidu.com", new NBSTaskCondition.Builder(NBSDiagnosisTaskScene.NBSDiagnosisTaskSceneAfterNetFinished).build()).build();
  icmpPing.setDelegate(delegate);
  NBSAppAgent.addDiagnosisTask(icmpPing);