[Mobile Synthetic Test] Save Node Selection Template¶
POST /api/v1/dialing_task/mobile/templates/save
Overview¶
Create or fully update a snapshot of a mobile synthetic test node selection template.
Prerequisites and Usage Steps¶
Omit templateUUID to create; a non-empty value updates an existing template in the same workspace. A maximum of 100 templates is allowed; updating an existing template does not increase the count. Both name and nodeSelection are required and are replaced as a whole rather than merged by leaf field. For nodes, only the ID structure is checked, and the original IDs/order are preserved; existence and static mappings are not queried in real time. For groups, groups and members are queried in real time; the request fails if a group does not exist, is empty, or a member is not in the current node set.
Saving a template does not create a task, does not run a synthetic test, and does not batch-modify tasks that already reference the same selection. Saving a template itself does not require accepting the Mobile Synthetic Test terms, but the service must be currently enabled and you must have write permission. Workspace mutual exclusion and transactions are used. On error, first use list/get to confirm whether it has been saved; the successful response assembles static mappings after commit, so a final 500 may still mean the template has been saved—do not create it again.
Request Headers¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| DF-API-KEY | string | Y | OpenAPI authentication credential for the workspace. Example: <DF-API-KEY>How to obtain or enter: Obtain an OpenAPI Key with this operation permission from API Key Management in the target workspace. |
Body Request Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| nodeSelection.mode | string | Required for mobile; nodes specifies nodes, and groups specifies node groups.Example: nodesHow to obtain or enter: Read from mobile resources/templates, then select. |
|
| nodeSelection.ids | array | Required for mobile; a non-empty, unique string array containing the corresponding resource IDs, not region UUIDs. Example: ["NODE-ID"]How to obtain or enter: Read from mobile resources/templates, then select. |
|
| nodeSelection.ids[*] | string | Required for mobile; a single current node or group ID. For nodes, only letters, digits, underscores, and hyphens are allowed.Example: NODE-IDHow to obtain or enter: Read from mobile resources/templates, then select. |
|
| nodeSelection.sampleCount | integer | Required for mobile; the independent sampling count per node, 1..5, not limited by the number of selected nodes/group members. Example: 1How to obtain or enter: Read from mobile resources/templates, then select. |
|
| name | string | Y | Required; non-empty after trim and ≤256 characters; after whitespace removal, the name must be unique within the same workspace; an old name with whitespace cannot be used to bypass this. Example: 生产节点How to obtain or enter: The business party defines a template name unique within the current workspace. |
| nodeSelection | json | Y | Required for mobile; must have exactly three keys: mode/ids/sampleCount; saves a snapshot and does not dynamically follow the template. For nodes, only the ID structure is validated and the original IDs/order are preserved; real-time existence or mapped status is not guaranteed. For groups, the current group and its members are queried and checked against the node set.Example: {"mode": "nodes", "ids": ["NODE-ID"], "sampleCount": 1}How to obtain or enter: For nodes, obtain node IDs from Mobile Resources; for groups, currently obtain group IDs from existing templates in the same workspace or group records confirmed by an administrator (the resource entry point does not currently fetch groups); you can also reuse a node selection template snapshot. |
| templateUUID | string | Optional; omit or use an empty string to create; a non-empty value updates the specified existing template; you cannot specify a new UUID across workspaces or fabricate one. Example: dsel_exampleHow to obtain or enter: When updating, obtain templateUUID from the template list in the current workspace. |
Additional Parameter Notes¶
Each returned template item includes a selectedNodeMappings array. Its elements reuse resources.nodes[].mapping: nodeId:string, continent/country/province/city/operator:{code,zh,en}|null, network/client_type:string.
Only the current database display mappings for nodeSelection.ids are retrieved. IDs are converted to strings and deduplicated; IDs not found are skipped. If mappings are missing or mode is groups, [] is returned. Display information does not indicate real-time availability; the list batch reads mappings only once.
This field is read-only and not persisted; do not send it back when saving. The original real-time resource and selection validity checks remain unchanged.
Request Example¶
curl --request POST 'https://openapi.guance.com/api/v1/dialing_task/mobile/templates/save' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"生产节点","nodeSelection":{"mode":"nodes","ids":["NODE-ID"],"sampleCount":1}}'
Response¶
HTTP 200, application/json. The example below shows the main fields that can be read directly.
| Field | Type | Description |
|---|---|---|
| content.templateUUID | string | Template UUID within the dsel_ workspace, not a task or node ID. |
| content.name | string | Template name after trim. |
| content.nodeSelection | object | Saved node selection snapshot that is copied to tasks, not a live reference. |
| content.nodeSelection.mode | string | nodes/groups. |
| content.nodeSelection.ids | array<string> | Non-empty, duplicate-free array of original node or group IDs; duplicates are rejected before saving, original IDs/order are preserved, and region UUIDs cannot be passed. |
| content.nodeSelection.ids[] | string | Corresponding resource ID. |
| content.nodeSelection.sampleCount | integer | Independent sampling count per node, 1..5. |
| content.selectedNodeMappings | array<object> | Static mappings of selected nodes for nodes only; real-time availability is not queried; [] when missing or for groups. |
| content.selectedNodeMappings[].nodeId | string | Node string ID. |
| content.selectedNodeMappings[].network | string | Static network type. |
| content.selectedNodeMappings[].client_type | string | Static client type. |
| content.selectedNodeMappings[].continent | object or null | Static region/operator label; province can be null. |
| content.selectedNodeMappings[].continent.code | string | Source code. |
| content.selectedNodeMappings[].continent.zh | string | Chinese name. |
| content.selectedNodeMappings[].continent.en | string | English name. |
| content.selectedNodeMappings[].country | object or null | Static region/operator label; province can be null. |
| content.selectedNodeMappings[].country.code | string | Source code. |
| content.selectedNodeMappings[].country.zh | string | Chinese name. |
| content.selectedNodeMappings[].country.en | string | English name. |
| content.selectedNodeMappings[].province | object or null | Static region/operator label; province can be null. |
| content.selectedNodeMappings[].province.code | string | Source code. |
| content.selectedNodeMappings[].province.zh | string | Chinese name. |
| content.selectedNodeMappings[].province.en | string | English name. |
| content.selectedNodeMappings[].city | object or null | Static region/operator label; province can be null. |
| content.selectedNodeMappings[].city.code | string | Source code. |
| content.selectedNodeMappings[].city.zh | string | Chinese name. |
| content.selectedNodeMappings[].city.en | string | English name. |
| content.selectedNodeMappings[].operator | object or null | Static region/operator label; province can be null. |
| content.selectedNodeMappings[].operator.code | string | Source code. |
| content.selectedNodeMappings[].operator.zh | string | Chinese name. |
| content.selectedNodeMappings[].operator.en | string | English name. |
| content.declaration | object | Common declaration. |
{
"code": 200,
"content": {
"templateUUID": "dsel_example",
"name": "生产节点",
"nodeSelection": {
"mode": "nodes",
"ids": [
"NODE-ID"
],
"sampleCount": 1
},
"selectedNodeMappings": [],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
Error Response¶
See Common Error Definitions for authentication, rate limiting, and common request errors.
| HTTP Status | errorCode | Trigger Condition | Message or Response Description | Resolution |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | Request fields are missing, or field values violate the declared validation conditions | Parameter parsing failed | Check the parameter location, field name, type, and value. |
| 400 | ft.RequestJsonFormatError | Request JSON syntax is invalid | Request JSON format error | Fix the JSON according to content.reason, line, and column. |
| 400 | ft.JsonFormatError | Body is not a JSON object | Partial JSON file format error | Submit a complete name/nodeSelection object. |
| 400 | ft.ParamsValidateError | Identifier, node selection structure/scope, name, template count, or protocol parameters do not conform to the current contract | Parameter validation failed: {} | Fix according to message and optional content.reason/field; first retrieve the target again from the list in this workspace. |
| 400 | ft.InvalidAction | Mobile synthetic test is currently not enabled, or a disallowed operation/transaction state exists | Invalid operation | The administrator should confirm the mobile synthetic test capability; reading/deleting templates is not automatically prohibited when the switch is disabled. |
| 400 | ft.DialingServerError | Mobile service call failed, or the returned resource shape/binding information does not match | Synthetic test service API call failed | Check reason and outcomeUnknown with traceId; do not use missing static mappings to mask upstream failures. |
| 409 | ft.MobileDialingOperationBusy | Timed out waiting for the workspace mutex; this operation was not executed | Another operation is in progress in the current workspace. This operation was not executed. Please try again later. | When operationExecuted=false/retryable=true, back off and retry; do not overwrite concurrently. |
| 401 | ft.WKSPNotExistOrReleased | After waiting, the workspace no longer exists/has been released | Workspace does not exist or has been released | Stop retrying and check for a valid workspace. |
| 403 | ft.WorkspaceIsLocked | After waiting, the workspace is locked | The workspace is locked and cannot be operated on | Confirm that it is unlocked and can be operated on. |
| 406 | ft.NotFoundWorkspace | The workspace record does not exist when acquiring the save lock | The specified workspace was not found | Check for a valid workspace. |
| 500 | ft.InternalServerError | Storage read, historical configuration, or local static mapping formatting exception | Internal error | Narrow it down to a specific task/template or filter. If it keeps failing, retain traceId to check the read stage. |