【모바일 테스트】노드 선택 템플릿 저장¶
POST /api/v1/dialing_task/mobile/templates/save
개요¶
모바일 테스트 노드 선택 템플릿 스냅샷을 생성하거나 전체 업데이트합니다.
호출 전 및 사용 단계¶
templateUUID를 생략하면 생성하고, 비어 있지 않으면 동일 워크스페이스에 이미 존재하는 템플릿을 업데이트합니다. 최대 100개이며, 기존 템플릿을 업데이트해도 개수가 늘어나지 않습니다. name/nodeSelection은 모두 필수이며 전체 교체되고, 리프 필드 기준으로 병합되지 않습니다. nodes는 ID 구조만 검사하고 원래 ID/순서를 유지하며, 존재 여부/정적 매핑을 실시간으로 조회하지 않습니다. groups는 그룹 및 멤버를 실시간으로 조회하며, 그룹이 없거나 비어 있거나 멤버가 현재 노드 집합에 없으면 실패합니다.
템플릿을 저장해도 작업이 생성되지 않고, 테스트가 실행되지 않으며, 동일한 선택을 이미 참조하는 작업이 일괄 수정되지 않습니다. 템플릿 저장 자체에는 모바일 테스트 약관 동의가 필요하지 않지만, 서비스가 현재 활성화되어 있고 쓰기 권한이 있어야 합니다. 워크스페이스 상호 배제와 트랜잭션을 사용하며, 오류 발생 시 먼저 목록/get으로 저장 여부를 확인해야 합니다. 성공 응답의 정적 매핑 조립은 커밋 후에 이루어지므로, 최종 500 응답이어도 이미 저장되었을 수 있으니 중복 생성하지 마십시오.
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| nodeSelection.mode | string | 모바일에서 필수; nodes는 노드를 지정하고, groups는 노드 그룹을 지정합니다. 예시: nodes획득 또는 입력 방법: 모바일 리소스/템플릿에서 읽은 후 선택합니다. |
|
| nodeSelection.ids | array | 모바일에서 필수; 비어 있지 않고 고유한 문자열 배열이며, 해당 리소스 id를 사용하며 region UUID가 아닙니다. 예시: ["NODE-ID"]획득 또는 입력 방법: 모바일 리소스/템플릿에서 읽은 후 선택합니다. |
|
| nodeSelection.ids[*] | string | 모바일에서 필수; 단일 현재 노드 또는 그룹 id이며, nodes는 영문자, 숫자, 밑줄, 하이픈만 허용합니다. 예시: NODE-ID획득 또는 입력 방법: 모바일 리소스/템플릿에서 읽은 후 선택합니다. |
|
| nodeSelection.sampleCount | integer | 모바일에서 필수; 각 노드의 독립 샘플링 횟수는 1..5이며, 선택한 노드/그룹 멤버 수에 제한받지 않습니다. 예시: 1획득 또는 입력 방법: 모바일 리소스/템플릿에서 읽은 후 선택합니다. |
|
| name | string | Y | 필수이며, trim 후 비어 있지 않고 256자 이하여야 하며, 이름은 공백 제거 후 동일 워크스페이스에서 고유해야 합니다. 이전 공백 이름으로 우회할 수 없습니다. 예시: 生产节点획득 또는 입력 방법: 비즈니스 담당자가 현재 워크스페이스에서 고유한 템플릿 이름을 정의합니다. |
| nodeSelection | json | Y | 모바일에서 필수이며, 정확히 mode/ids/sampleCount 세 개의 키를 가집니다. 스냅샷을 저장하며 템플릿을 동적으로 따르지 않습니다. nodes는 ID 구조만 검증하고 원래 ID/순서를 유지하며, 실시간 존재 또는 매핑 여부를 보장하지 않습니다. groups는 현재 그룹 및 멤버를 조회하고 노드 집합을 확인합니다. 예시: {"mode": "nodes", "ids": ["NODE-ID"], "sampleCount": 1}획득 또는 입력 방법: nodes는 모바일 리소스에서 노드 ID를 가져옵니다. groups는 현재 동일 워크스페이스의 기존 템플릿 또는 관리자가 확인한 그룹 기록에서 ID를 가져와야 합니다(리소스 진입점은 현재 그룹을 가져오지 않음). 노드 선택 템플릿 스냅샷을 재사용할 수도 있습니다. |
| templateUUID | string | 선택 사항이며, 생략/빈 문자열이면 생성하고, 비어 있지 않으면 지정한 기존 템플릿을 업데이트합니다. 워크스페이스를 넘거나 임의로 새 UUID를 지정할 수 없습니다. 예시: dsel_example획득 또는 입력 방법: 업데이트 시 현재 워크스페이스 템플릿 목록에서 templateUUID를 가져옵니다. |
매개변수 추가 설명¶
반환되는 각 템플릿 항목에는 selectedNodeMappings 배열이 포함되며, 요소는 resources.nodes[].mapping을 재사용합니다: nodeId:string, continent/country/province/city/operator:{code,zh,en}|null, network/client_type:string. nodeSelection.ids의 현재 데이터베이스 표시 매핑만 가져오며, ID를 문자열로 변환하고 중복 제거하며, 찾지 못하면 건너뜁니다. 매핑이 없거나 groups 모드이면 []를 반환합니다. 표시 정보는 실시간 사용 가능을 의미하지 않으며, 목록 배치는 매핑을 한 번만 읽습니다. 이 필드는 읽기 전용이며 영구 저장되지 않으므로 저장 시 다시 전송해서는 안 됩니다. 원래의 실시간 리소스 및 선택 유효성 검증은 유지됩니다.
요청 예시¶
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}}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.templateUUID | string | dsel_ 워크스페이스 내 템플릿 UUID이며, 작업 또는 노드 ID가 아닙니다. |
| content.name | string | trim 후 템플릿 이름입니다. |
| content.nodeSelection | object | 노드 선택 스냅샷을 저장하며, 작업에 복사되고 실시간 참조가 아닙니다. |
| content.nodeSelection.mode | string | nodes/groups. |
| content.nodeSelection.ids | array<string> | 비어 있지 않고 중복이 없는 원본 노드 또는 그룹 ID 배열입니다. 저장 전에 중복을 거부하며, 원래 ID/순서를 유지하고 region UUID를 전달할 수 없습니다. |
| content.nodeSelection.ids[] | string | 해당 리소스 id입니다. |
| content.nodeSelection.sampleCount | integer | 각 노드의 독립 샘플링 횟수는 1..5입니다. |
| content.selectedNodeMappings | array<object> | nodes의 선택된 정적 매핑만 제공하며, 실시간 사용 가능 여부를 조회하지 않습니다. 누락되었거나 groups이면 []입니다. |
| content.selectedNodeMappings[].nodeId | string | 노드 문자열 ID입니다. |
| content.selectedNodeMappings[].network | string | 정적 네트워크 유형입니다. |
| content.selectedNodeMappings[].client_type | string | 정적 클라이언트 유형입니다. |
| content.selectedNodeMappings[].continent | object 또는 null | 정적 지역/통신사 레이블이며, province는 null일 수 있습니다. |
| content.selectedNodeMappings[].continent.code | string | 출처 코드입니다. |
| content.selectedNodeMappings[].continent.zh | string | 중국어 이름입니다. |
| content.selectedNodeMappings[].continent.en | string | 영어 이름입니다. |
| content.selectedNodeMappings[].country | object 또는 null | 정적 지역/통신사 레이블이며, province는 null일 수 있습니다. |
| content.selectedNodeMappings[].country.code | string | 출처 코드입니다. |
| content.selectedNodeMappings[].country.zh | string | 중국어 이름입니다. |
| content.selectedNodeMappings[].country.en | string | 영어 이름입니다. |
| content.selectedNodeMappings[].province | object 또는 null | 정적 지역/통신사 레이블이며, province는 null일 수 있습니다. |
| content.selectedNodeMappings[].province.code | string | 출처 코드입니다. |
| content.selectedNodeMappings[].province.zh | string | 중국어 이름입니다. |
| content.selectedNodeMappings[].province.en | string | 영어 이름입니다. |
| content.selectedNodeMappings[].city | object 또는 null | 정적 지역/통신사 레이블이며, province는 null일 수 있습니다. |
| content.selectedNodeMappings[].city.code | string | 출처 코드입니다. |
| content.selectedNodeMappings[].city.zh | string | 중국어 이름입니다. |
| content.selectedNodeMappings[].city.en | string | 영어 이름입니다. |
| content.selectedNodeMappings[].operator | object 또는 null | 정적 지역/통신사 레이블이며, province는 null일 수 있습니다. |
| content.selectedNodeMappings[].operator.code | string | 출처 코드입니다. |
| content.selectedNodeMappings[].operator.zh | string | 중국어 이름입니다. |
| content.selectedNodeMappings[].operator.en | string | 영어 이름입니다. |
| content.declaration | object | 공통 선언입니다. |
{
"code": 200,
"content": {
"templateUUID": "dsel_example",
"name": "生产节点",
"nodeSelection": {
"mode": "nodes",
"ids": [
"NODE-ID"
],
"sampleCount": 1
},
"selectedNodeMappings": [],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다. | 매개변수 구문 분석 실패 | 매개변수 위치, 필드 이름, 유형 및 값을 확인하십시오. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않습니다. | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하십시오. |
| 400 | ft.JsonFormatError | Body가 JSON 객체가 아닙니다. | 일부 json 파일 형식 오류 | 완전한 name/nodeSelection 객체를 제출하십시오. |
| 400 | ft.ParamsValidateError | 식별자, 노드 선택 구조/범위, 이름, 템플릿 수 또는 프로토콜 매개변수가 현재 계약과 일치하지 않습니다. | 매개변수 검증 실패: {} | message와 선택적 content.reason/field에 따라 수정하고, 먼저 현재 워크스페이스 목록에서 대상을 다시 가져오십시오. |
| 400 | ft.InvalidAction | 모바일 테스트가 현재 활성화되지 않았거나 허용되지 않는 작업/트랜잭션 상태가 있습니다. | 유효하지 않은 작업 | 관리자가 모바일 테스트 기능을 확인해야 합니다. 템플릿 읽기/삭제는 스위치가 꺼져 있다고 해서 자동으로 금지되지 않습니다. |
| 400 | ft.DialingServerError | 모바일 서비스 호출 실패, 리소스 반환 형태/바인딩 정보 불일치 | 테스트 서비스 인터페이스 호출 실패 | reason, outcomeUnknown을 확인하고 traceId와 함께 검증하십시오. 정적 매핑 누락으로 업스트림 실패를 감춰서는 안 됩니다. |
| 409 | ft.MobileDialingOperationBusy | 워크스페이스 상호 배제 잠금 대기 시간이 초과되어 이번 작업이 실행되지 않았습니다. | 현재 워크스페이스에서 다른 작업이 진행 중이라 이번 작업이 실행되지 않았습니다. 나중에 다시 시도하십시오. | operationExecuted=false/retryable=true이면 백오프 후 재시도하고, 동시에 덮어쓰지 마십시오. |
| 401 | ft.WKSPNotExistOrReleased | 대기 후 워크스페이스가 더 이상 존재하지 않거나 해제되었습니다. | 워크스페이스가 존재하지 않거나 해제되었습니다. | 재시도를 중지하고 유효한 워크스페이스를 확인하십시오. |
| 403 | ft.WorkspaceIsLocked | 대기 후 워크스페이스가 잠겼습니다. | 워크스페이스가 잠겨 있어 작업할 수 없습니다. | 잠금 해제 및 작업 가능 상태를 확인하십시오. |
| 406 | ft.NotFoundWorkspace | 저장 잠금 시 워크스페이스 레코드가 존재하지 않습니다. | 지정한 워크스페이스를 찾을 수 없습니다. | 유효한 워크스페이스를 확인하십시오. |
| 500 | ft.InternalServerError | 스토리지 읽기, 이전 구성 또는 로컬 정적 매핑 형식 지정 예외 | 내부 오류 | 특정 작업/템플릿 또는 필터로 범위를 좁히고, 지속적으로 실패하면 traceId를 보관하여 읽기 단계를 확인하십시오. |