网络探测
即对客户端设备进行网络诊断以获设备的网络状况,可以通过以下类、接口来设置 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);