Skip to content

[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: nodes
How 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-ID
How 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: 1
How 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_example
How 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.

Feedback

Is this page helpful?