[Mobile Synthetic Test] Node and Node Group Query¶
GET /api/v1/dialing_task/mobile/resources
Overview¶
Query the real-time nodes available for mobile synthetic tests and their static display mappings.
Prerequisites and Usage Steps¶
Pass type=mobile, or use a mobile taskUUID that already exists in the current workspace; the latter takes precedence. The task is not modified and no synthetic test is executed. The current public call requests only real-time nodes, not upstream node groups, so groups is usually a fixed []; there is no include_groups query to enable, and internal SDK parameters must not be guessed. The groups mode is compatible with existing templates and confirmed group IDs, and current members are verified again when saving.
nodes is the intersection of IDs between the real-time list and the local static mapping, and is not re-filtered by region/ISP/network type. If the mapping is missing or there is no intersection, [] and nodeMapping=null or the corresponding summary are returned; this does not mean the platform definitively has no nodes. Upstream failures still report errors and are not downgraded into a fake "no nodes" result. A successful resource list does not guarantee that the nodes will still be available the next time a task is dispatched; writes to nodes validate only the ID structure, while groups additionally verifies groups and members. The legacy id/area/location/isp/clientType fields are preserved as-is, and mapping is used for unified Chinese/English display.
Request Header¶
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| DF-API-KEY | string | Y | OpenAPI authentication credential of the workspace. Example: <DF-API-KEY>How to obtain or specify: Obtain an OpenAPI Key with this operation permission from API Key Management in the target workspace. |
Query Parameters¶
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| taskUUID | string | Optional. When provided, it takes precedence over type; its existence and actual type are checked. It is not a remote ID.Example: dial_exampleHow to obtain or specify: Take the uuid of a type=mobile task from the task list in the current workspace. |
|
| type | string | Optional. At least one of type/taskUUID must be a valid choice; when taskUUID is absent, it must be mobile.Allowed values: ['mobile'] Example: mobileHow to obtain or specify: When creating a new mobile task, select type=mobile; if the target already exists, taskUUID can also be used. |
Additional Parameter Notes¶
nodes is the flattened intersection produced by joining the vivo real-time list with the database static mapping on string IDs; the legacy id/area/location/isp/clientType fields are preserved as-is. mapping contains nodeId, the code/zh/en of continent/country/province/city/operator, and network/client_type; province can be null. nodeMapping returns version/sha256 or null. When there is no mapping or no match, nodes is empty; upstream failures still report errors, and the groups contract is preserved.
Request Example¶
curl --get 'https://openapi.guance.com/api/v1/dialing_task/mobile/resources' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode type=mobile
Response¶
HTTP 200, application/json. The example below shows the main fields that can be read directly.
| Field | Type | Description |
|---|---|---|
| content.nodes | array<object> | Intersection of real-time nodes and the local static mapping joined by string ID; [] when there is no mapping or no match. |
| content.nodes[].id | string or integer | Original upstream node ID; it must be converted to a string when written to nodeSelection.ids. |
| content.nodes[].area | JSON | Legacy upstream area field, preserved as-is. |
| content.nodes[].location | JSON | Legacy upstream location field, preserved as-is. |
| content.nodes[].isp | JSON | Legacy upstream ISP field, preserved as-is. |
| content.nodes[].clientType | JSON | Legacy upstream client type, preserved as-is. |
| content.nodes[].mapping | object | Display information from the static mapping. |
| content.nodes[].mapping.nodeId | string | Node string ID. |
| content.nodes[].mapping.network | string | Static network type. |
| content.nodes[].mapping.client_type | string | Static client type. |
| content.nodes[].mapping.continent | object or null | Static region/ISP label; province can be null. |
| content.nodes[].mapping.continent.code | string | Source code. |
| content.nodes[].mapping.continent.zh | string | Chinese name. |
| content.nodes[].mapping.continent.en | string | English name. |
| content.nodes[].mapping.country | object or null | Static region/ISP label; province can be null. |
| content.nodes[].mapping.country.code | string | Source code. |
| content.nodes[].mapping.country.zh | string | Chinese name. |
| content.nodes[].mapping.country.en | string | English name. |
| content.nodes[].mapping.province | object or null | Static region/ISP label; province can be null. |
| content.nodes[].mapping.province.code | string | Source code. |
| content.nodes[].mapping.province.zh | string | Chinese name. |
| content.nodes[].mapping.province.en | string | English name. |
| content.nodes[].mapping.city | object or null | Static region/ISP label; province can be null. |
| content.nodes[].mapping.city.code | string | Source code. |
| content.nodes[].mapping.city.zh | string | Chinese name. |
| content.nodes[].mapping.city.en | string | English name. |
| content.nodes[].mapping.operator | object or null | Static region/ISP label; province can be null. |
| content.nodes[].mapping.operator.code | string | Source code. |
| content.nodes[].mapping.operator.zh | string | Chinese name. |
| content.nodes[].mapping.operator.en | string | English name. |
| content.groups | array<object> | Compatibility group array; the current public call does not request upstream groups by default and returns [], so this cannot be used to conclude that no historical groups exist. |
| content.groups[].id | string or integer | Compatibility group ID; no entries are currently produced. |
| content.groups[].clusterGroupId | string or integer | Legacy compatibility group ID. |
| content.groups[].name | string | Group name. |
| content.groups[].description | string | Group description. |
| content.groups[].clientType | JSON | Group client type. |
| content.groups[].children | array | Compatibility group members; not produced by the current public call. |
| content.groups[].children[] | string or integer or object | Upstream group member shape; handle it according to the actual resource protocol. |
| content.groups[].children[].id | string or integer | Object member ID; can be omitted. |
| content.maxSampleCount | integer | Fixed at 5; the sampling limit for each node independently. |
| content.nodeMapping | object or null | Static mapping version/digest; null when no mapping is available. |
| content.nodeMapping.version | integer | Mapping structure version; currently 2. |
| content.nodeMapping.sha256 | string | Digest of the mapping content; not a credential or task ID. |
| content.declaration | object | Outer public declaration. |
{
"code": 200,
"content": {
"nodes": [
{
"id": "NODE-ID",
"area": "示例区域",
"location": "示例位置",
"isp": "示例运营商",
"clientType": "mobile",
"mapping": {
"nodeId": "NODE-ID",
"network": "mobile",
"client_type": "mobile",
"continent": {
"code": "asia",
"zh": "亚洲",
"en": "Asia"
},
"country": {
"code": "cn",
"zh": "中国",
"en": "China"
},
"province": null,
"city": {
"code": "example",
"zh": "示例城市",
"en": "Example city"
},
"operator": {
"code": "example",
"zh": "示例运营商",
"en": "Example ISP"
}
}
}
],
"groups": [],
"maxSampleCount": 5,
"nodeMapping": {
"version": 2,
"sha256": "SHA256-EXAMPLE"
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
Error Response¶
For authentication, rate limiting, and common request errors, see Common Error Definitions.
| HTTP Status | errorCode | Trigger Condition | Message or Response Description | Resolution |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | A request field is missing, or a field value violates the declared validation conditions | Parameter parsing failed | Check the parameter location, field name, type, and value. |
| 400 | ft.ParamsValidateError | The identifier, node selection structure/range, name, template count, or protocol parameters do not conform to the current contract | Parameter validation failed: {} | Fix according to message and the optional content.reason/field, and first re-fetch the target from the task list in the current workspace. |
| 400 | ft.InvalidAction | Mobile synthetic testing is currently disabled, or an operation/transaction state is not allowed | Invalid operation | Ask the administrator to confirm the mobile synthetic testing capability; reading/deleting templates is not automatically blocked just because the switch is off. |
| 400 | ft.DialingServerError | The mobile service call failed, or the returned resource shape/binding information does not match | Synthetic test service API call failed | Check reason and outcomeUnknown together with traceId; a missing static mapping must not be used to conceal an upstream failure. |
| 404 | ft.NotFoundDialTask | taskUUID does not belong to a non-deleted task in the current workspace | The specified cloud synthetic test task was not found | Take a mobile UUID from the task list in the current workspace; a regular task cannot be used even if it exists. |
| 500 | ft.InternalServerError | An exception occurred while reading storage, historical configuration, or formatting the local static mapping | Internal error | Narrow down to a specific task/template or filter; if the failure persists, retain traceId to check the read stage. |