목록 조회¶
GET /api/v1/dialing_region/list
개요¶
현재 워크스페이스의 자체 호스팅 신서틱 테스트 노드 목록을 조회합니다.
호출 전 및 사용 단계¶
owner=custom이고 이 워크스페이스에 속한 경우에만 해당하며, 기본 공용 노드나 모바일 리소스는 포함하지 않습니다. isAlive를 생략하면 온라인 상태를 제한하지 않고, true이면 온라인 노드만, false이면 오프라인 노드만 조회합니다. 결과는 업스트림 create_at 기준 내림차순이며 페이지네이션/총 개수는 없습니다. 이름은 현재 요청 언어에 따라 폴백 표시되며 nameI18n에는 다국어 매핑이 유지됩니다.
createAt/creator/updateAt/updator는 extend_info에서 보완되며 업스트림 create_at/heartbeat와 다릅니다. 목록에서는 신원 정보를 추가로 보완하며, 누락 시 {}입니다. 목록의 노드 uuid는 일반 작업 regions에 사용됩니다. 등록에 성공했지만 설치/하트비트가 없는 노드는 온라인 상태라고 보장할 수 없습니다. 설치 및 검증은 자체 호스팅 노드 관리를 참조하고, 기본 노드는 기본 리전 목록을 사용하며, 모바일 노드는 모바일 리소스 진입점을 사용합니다.
요청 헤더¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 매개변수¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| isAlive | string | 선택 사항이며, 생략하면 온라인 상태를 제한하지 않습니다. Query 문자열이며 JSON boolean 또는 작업 ok/stop이 아닙니다. null 허용: True 선택 가능한 값: ['true', 'false'] 예: true가져오기 또는 입력 방법: 온라인 노드만 조회할지 여부에 따라 true/false 문자열을 선택합니다. |
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/dialing_region/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode isAlive=true
응답¶
HTTP 200, application/json입니다. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | array<object> | 자체 호스팅 노드 배열이며, 비어 있으면 []이고 pageInfo를 포함하지 않습니다. |
| content[].uuid | string | regn_노드 UUID이며, 일반 작업 regions를 생성할 때 이 값을 사용합니다. |
| content[].keycode | string | 노드 배포/식별 코드이며 regions UUID로 사용하지 않습니다. |
| content[].owner | string | 자체 호스팅 노드 custom. |
| content[].name | string | 현재 요청 언어에 따라 선택된 이름입니다. |
| content[].nameEn | string | 영어 호환 표시 이름입니다. |
| content[].name_en | string | 업스트림의 이전 영어 이름이며 조건부로 유지됩니다. |
| content[].nameI18n | object | 표준 언어 이름 매핑입니다. |
| content[].nameI18n.언어 코드 | string | 해당 언어 표시 이름입니다. |
| content[].internal | boolean | true는 중국 국내, false는 해외이며 네트워크 사설 여부가 아닙니다. |
| content[].country | string | 국가. |
| content[].province | string | 성/도. |
| content[].city | string | 도시. |
| content[].isp | string | 통신사/제공업체. |
| content[].status | string | 노드 서비스 상태(예: OK/disabled)이며 작업 실행 상태가 아닙니다. |
| content[].heartbeat | integer | 노드의 최근 하트비트 Unix 초이며 업스트림 정의를 기준으로 합니다. |
| content[].region | string | 업스트림 리전 식별자. |
| content[].company | string | 기업 정보. |
| content[].external_id | string | 자체 호스팅 소속 등 업스트림 필드이며 기본 노드는 일반적으로 비어 있습니다. |
| content[].parent_ak | string | 업스트림 호환 소속 필드이며 비어 있을 수 있습니다. 클라이언트는 이를 OpenAPI Key로 간주하지 않습니다. |
| content[].extend_info | string | 업스트림 확장 JSON 문자열 또는 빈 문자열이며 기본적으로 객체가 아닙니다. |
| content[].create_at | integer | 업스트림 생성 시간 필드이며 이전 데이터는 -1일 수 있습니다. 작업의 createAt과 다릅니다. |
| content[].기타 업스트림 필드 | JSON | 업스트림 호환 추가 필드를 그대로 전달하며, 나열되지 않은 키를 바로 쓰기 가능한 매개변수로 간주하지 마십시오. |
| content[].createAt | integer | extend_info에서 읽은 생성 Unix 초이며 누락 시 -1입니다. |
| content[].creator | string | 확장에서 읽은 생성자 신원이며 누락 시 빈 문자열입니다. |
| content[].updateAt | integer | 확장에서 읽은 업데이트 Unix 초이며 누락 시 -1입니다. |
| content[].updator | string | 확장에서 읽은 업데이트 신원이며 누락 시 빈 문자열입니다. |
| content[].creatorInfo | object | 목록에서만 신원 정보를 보완하며 일치하는 정보가 없으면 {}입니다. |
| content[].creatorInfo.uuid | string | 조건부 반환; 신원 UUID. |
| content[].creatorInfo.name | string | 조건부 반환; 표시 이름. |
| content[].creatorInfo.email | string | 조건부 반환; 이메일. |
| content[].creatorInfo.username | string | 조건부 반환; 로그인 이름. |
| content[].creatorInfo.status | integer | 조건부 반환; 계정 상태. |
| content[].creatorInfo.wsAccountStatus | integer | 조건부 반환; 워크스페이스 관계 상태. |
| content[].creatorInfo.iconUrl | string | 조건부 반환; 아바타 주소. |
| content[].creatorInfo.mobile | string | 조건부 반환; 휴대폰 번호. |
| content[].creatorInfo.countryCode | string | 조건부 반환; 휴대폰 국가 코드. |
| content[].creatorInfo.acntWsNickname | string | 조건부 반환; 워크스페이스 닉네임. |
| content[].updatorInfo | object | 목록에서만 신원 정보를 보완하며 일치하는 정보가 없으면 {}입니다. |
| content[].updatorInfo.uuid | string | 조건부 반환; 신원 UUID. |
| content[].updatorInfo.name | string | 조건부 반환; 표시 이름. |
| content[].updatorInfo.email | string | 조건부 반환; 이메일. |
| content[].updatorInfo.username | string | 조건부 반환; 로그인 이름. |
| content[].updatorInfo.status | integer | 조건부 반환; 계정 상태. |
| content[].updatorInfo.wsAccountStatus | integer | 조건부 반환; 워크스페이스 관계 상태. |
| content[].updatorInfo.iconUrl | string | 조건부 반환; 아바타 주소. |
| content[].updatorInfo.mobile | string | 조건부 반환; 휴대폰 번호. |
| content[].updatorInfo.countryCode | string | 조건부 반환; 휴대폰 국가 코드. |
| content[].updatorInfo.acntWsNickname | string | 조건부 반환; 워크스페이스 닉네임. |
| content[].declaration | object | 비어 있지 않은 각 객체의 공통 선언입니다. |
{
"code": 200,
"content": [
{
"uuid": "regn_example",
"keycode": "example-self-node",
"owner": "custom",
"name": "生产自建节点",
"nameEn": "Production self node",
"nameI18n": {
"zh": "生产自建节点",
"en": "Production self node"
},
"internal": true,
"country": "China",
"province": "Zhejiang",
"city": "Hangzhou",
"isp": "example",
"status": "OK",
"heartbeat": 1785427200,
"region": "example-region",
"company": "",
"external_id": "wksp_example",
"parent_ak": "",
"extend_info": "",
"create_at": 1785427200,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427200,
"creatorInfo": {},
"updatorInfo": {},
"declaration": {}
}
],
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
일반 신서틱 테스트 SDK는 다운스트림 error_code=dialtesting.invalidRegion을 ft.DialingRegionError로 일괄 매핑하고 실제 HTTP 상태(400에 국한되지 않음)를 유지합니다. 기타 다운스트림 4xx는 실제 HTTP 상태와 error_code/message(ft 접두사가 없는 업스트림 코드 포함)를 유지하며, 나열되지 않은 코드도 반환될 수 있습니다. >=500은 공개 진입점에서 500 ft.InternalServerError로 일괄 래핑합니다. SDK는 업스트림 content를 반환하며, 이 컨트롤러는 이를 특정 고정 regionInfo/ak 구조로 일괄 재포장하지 않으므로 실제 배포 버전에 따라 평면 또는 호환 래핑 구조를 식별해야 하며, 알 수 없는 추가 필드는 호환성을 위해 유지됩니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 매개변수 파싱 실패 | 매개변수 위치, 필드명, 유형 및 값을 확인하십시오. |
| 406 | ft.DialingBrandNoSetError | 워크스페이스에 해당하는 신서틱 테스트 서비스 브랜드 구성이 누락됨 | {} 브랜드의 신서틱 테스트 구성이 설정되지 않았습니다. |
관리자가 현재 워크스페이스의 신서틱 테스트 서비스를 확인하도록 하십시오. |
| 400 | ft.DialingAKNoSetError | 신서틱 테스트 서비스 서명 자격 증명이 구성되지 않음 | 신서틱 테스트 AK 정보가 구성되지 않았습니다. Launcher 활성화 구성을 확인하십시오 | 관리자가 서비스 활성화 정보를 확인하도록 하십시오. 클라이언트는 이 Body에서 해당 자격 증명을 제출하지 않습니다. |
| 400 | ft.DialingServerError | 다운스트림 신서틱 테스트 노드 인터페이스가 400 비즈니스 실패를 반환하거나 응답 미디어를 파싱할 수 없음 | 신서틱 테스트 서비스 인터페이스 호출 실패 | message/traceId를 확인하고 관리자가 노드 서비스를 점검하도록 하십시오. 실패를 노드 없음으로 간주해서는 안 됩니다. |
| 500 | ft.InternalServerError | 일반 다운스트림 5xx/연결 이상 또는 레거시 노드/연관 필드 형식, 이름 및 응답 조립 이상 | 내부 오류 | 구체적인 노드/필터로 범위를 좁혀 업스트림 응답 형식과 서비스 가용성을 확인하십시오. 지속적으로 실패하면 traceId를 보관하십시오. |
| 400 | ft.DialingRegionError | 다운스트림 HTTP 400이고 error_code=dialtesting.invalidRegion임. 기타 4xx도 동일한 코드로 매핑되고 실제 HTTP 상태를 유지함 | 현재 작업에 일부 신서틱 테스트 노드가 유효하지 않으므로 구성을 업데이트한 후 다시 저장하십시오. | 유효한 자체 호스팅 노드 및 노드 서비스 상태를 확인하고 원래 dialtesting 코드로 고정 매칭하지 마십시오. |