생성¶
POST /api/v1/dialing_region/regist
개요¶
현재 워크스페이스의 자체 호스팅 신서틱 테스트 노드 설정을 등록합니다.
호출 전 확인 및 사용 단계¶
먼저 노드 플랜, 네트워크 위치, 고유한 keycode/표시 이름을 확인합니다. 서버는 소유권을 현재 Key 워크스페이스에 바인딩하고 서버 측 생성/업데이트 ID와 Unix 초를 함께 부여하며, 외부 공간의 external_id나 사용자 정의 extend_info는 받지 않습니다. 등록은 노드 설정일 뿐이며, DataKit을 설치하거나 하트비트가 온라인 상태임을 보장하지 않습니다. 성공 후에는 실제 응답의 content.uuid 또는 content.regionInfo.uuid에서 노드 UUID를 얻고, 노드 상세/제품의 "구성 가져오기"를 통해 배포 자료를 얻은 뒤, 자체 호스팅 노드 관리를 참고하여 설치를 완료하고 isAlive=true를 조회해 검수합니다.
응답은 노드 자체일 수도 있고 업스트림 ak/regionInfo 래핑을 유지할 수도 있습니다. 노드 AK/SK를 OpenAPI Key로 간주하지 마세요. 실제 값은 노드에 안전하게 설정하는 용도로만 사용합니다. 현재 컨트롤러는 최상위 이름만 정규화하며, 래핑 내부의 regionInfo는 자동으로 재귀 변환하지 않습니다. 표시는 실제 노드 객체와 nameI18n을 기준으로 읽습니다. 이름 중복은 먼저 자체 호스팅 노드에서 확인하세요. 이는 공간 간 전역 유일성을 보장하지 않습니다. 다운스트림 등록은 성공했지만 응답/후속 처리가 실패한 경우 먼저 목록에서 keycode를 조회하고, 무작정 재등록하지 마세요.
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| nameI18n.zh | string | 선택적 언어 구성원으로, 생략하면 비어 있거나 대체되며 노드 식별자는 변경되지 않습니다. 예시: 生产自建节点가져오기 또는 입력 방법: 고객이 해당 언어의 표시 이름을 제공합니다. |
|
| nameI18n.en | string | 선택적 언어 구성원으로, 생략하면 비어 있거나 대체되며 노드 식별자는 변경되지 않습니다. 예시: Production self node가져오기 또는 입력 방법: 고객이 해당 언어의 표시 이름을 제공합니다. |
|
| nameI18n.zh-hant | string | 선택적 언어 구성원으로, 생략하면 비어 있거나 대체되며 노드 식별자는 변경되지 않습니다. 예시: Production self node가져오기 또는 입력 방법: 고객이 해당 언어의 표시 이름을 제공합니다. |
|
| nameI18n.id | string | 선택적 언어 구성원으로, 생략하면 비어 있거나 대체되며 노드 식별자는 변경되지 않습니다. 예시: Production self node가져오기 또는 입력 방법: 고객이 해당 언어의 표시 이름을 제공합니다. |
|
| nameI18n.ja | string | 선택적 언어 구성원으로, 생략하면 비어 있거나 대체되며 노드 식별자는 변경되지 않습니다. 예시: Production self node가져오기 또는 입력 방법: 고객이 해당 언어의 표시 이름을 제공합니다. |
|
| nameI18n.ko | string | 선택적 언어 구성원으로, 생략하면 비어 있거나 대체되며 노드 식별자는 변경되지 않습니다. 예시: Production self node가져오기 또는 입력 방법: 고객이 해당 언어의 표시 이름을 제공합니다. |
|
| city | string | 선택 사항이며 null이 될 수 있습니다. null 허용: True 예시: Hangzhou가져오기 또는 입력 방법: 실제 도시에 맞게 입력합니다. |
|
| company | string | 선택 사항이며 null이 될 수 있고, 워크스페이스 소유권을 결정하지 않습니다. null 허용: True 예시: example가져오기 또는 입력 방법: 노드가 속한 기업에 맞게 입력합니다. |
|
| country | string | Y | 필수 문자열이며, 공개 계층에서는 국가 열거형을 고정하지 않고 노드 관리와 일관성을 유지합니다. null 허용: False 예시: China가져오기 또는 입력 방법: 노드의 실제 국가에 맞게 입력합니다. |
| internal | boolean | Y | 필수 불리언이며, 노드가 내부망에서 접근 가능한지 또는 활성화되었는지를 나타내는 값이 아닙니다. null 허용: False 예시: true가져오기 또는 입력 방법: true는 중국 국내, false는 해외를 의미하며 노드의 실제 소재지에 맞게 입력합니다. |
| isp | string | Y | 필수 문자열이며, 현재 Studio는 통신사 열거형을 고정하지 않고 업스트림 검증을 대신하지도 않습니다. null 허용: False 예시: example-isp가져오기 또는 입력 방법: 실제 노드 네트워크 통신사/제공자에서 식별자를 가져옵니다. |
| keycode | string | Y | 필수 문자열이며, 이 공간에서 정확한 중복 이름 사전 검사를 수행하고 자동 trim/대소문자 통일을 하지 않습니다. 업스트림에 별도 제약이 있을 수 있으며 대소문자로 우회할 수 없습니다. 등록 후 반환되는 uuid가 아닙니다. null 허용: False 예시: example-self-node가져오기 또는 입력 방법: 노드에 안정적인 배포 식별자를 설정하고, 먼저 이 공간의 노드 keycode를 조회해 중복을 피합니다. |
| name | string | 선택 사항이며 null/빈 문자열이 될 수 있습니다. 비어 있지 않은 명시적 name은 nameI18n.zh를 덮어씁니다. 유효한 표시 이름이 없으면 중복 검사 시 keycode로 대체합니다. trim 통일을 수행하지 않으므로 클라이언트에서 먼저 정규화하세요. 빈 문자열 허용: True null 허용: True 예시: 生产自建节点가져오기 또는 입력 방법: 비즈니스 표시 이름이며 비어 있지 않게 지정하는 것을 권장합니다. 현재 공간 노드의 기존 표시 이름/이름 없는 노드의 keycode와 충돌하지 않도록 하세요. |
|
| nameI18n | json | 선택 사항이며 null이 될 수 있습니다. 명시적 name이 있으면 zh를 우선하고 나머지 언어는 정규화되며, 알 수 없는 언어는 무시되고 누락된 언어는 빈 문자열로 처리되어 표시 시 대체됩니다. 각 값은 문자열로 지정하는 것을 권장합니다. 노드 등록에 필요한 JSON 직렬화 문자열이 아닙니다. null 허용: True 예시: {"zh": "生产自建节点", "en": "Production self node"}가져오기 또는 입력 방법: 제품이 지원하는 언어별로 이름 매핑을 작성합니다. 현재 zh/en/zh-hant/id/ja/ko를 지원합니다. |
|
| province | string | 선택 사항이며 null이 될 수 있습니다. 생략하면 해당 지역 정보를 제공하지 않습니다. null 허용: True 예시: Zhejiang가져오기 또는 입력 방법: 노드의 실제 성(도)에 맞게 입력합니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/dialing_region/regist' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"internal":true,"isp":"example-isp","country":"China","province":"Zhejiang","city":"Hangzhou","name":"生产自建节点","nameI18n":{"zh":"生产自建节点","en":"Production self node"},"company":"example","keycode":"example-self-node"}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| 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.ak | object | 일부 업스트림 등록/상세 응답에 포함되는 노드 배포 자격 증명 객체입니다. 이 객체가 없으면 제품에서 구성을 가져오며, 필드가 항상 존재한다고 가정하지 않습니다. |
| content.ak.ak | string | 노드 AK 식별자이며 본 요청의 DF-API-KEY가 아닙니다. |
| content.ak.sk | string | 노드 SK로, 안전한 배포 구성에만 사용하며 실제 값을 공개하거나 기록하지 않습니다. |
| content.ak.external_id | string | 자격 증명 소속 워크스페이스 식별자입니다. |
| content.ak.owner | string | 업스트림 자격 증명 owner 필드입니다. |
| content.ak.parent_ak | string | 업스트림 상위 자격 증명 식별자이며 직접 인증 가능한 시크릿으로 간주하지 않습니다. |
| content.ak.status | string | 업스트림 자격 증명 상태입니다. |
| content.ak.update_at | integer | 업스트림 업데이트 시간이며 실제 단위/과거 0 값을 유지하고 Studio의 updateAt과 혼동하지 않습니다. |
| content.regionInfo | object | 일부 업스트림의 래핑 노드 객체로, 평면 노드 필드와 의미가 동일합니다. 이 컨트롤러는 해당 객체의 이름을 재귀적으로 정규화하지 않습니다. |
| content.regionInfo.uuid | string | regn_노드 UUID로, 일반 작업 regions 생성 시 이 값을 사용합니다. |
| content.regionInfo.keycode | string | 노드 배포/식별 코드이며 regions UUID로 사용하지 않습니다. |
| content.regionInfo.owner | string | 자체 호스팅 노드인 custom입니다. |
| content.regionInfo.name | string | 현재 요청 언어에 따라 선택된 이름입니다. |
| content.regionInfo.nameEn | string | 영어 호환 표시 이름입니다. |
| content.regionInfo.name_en | string | 업스트림의 구 영어 이름으로, 조건부로 유지됩니다. |
| content.regionInfo.nameI18n | object | 정규화된 언어 이름 매핑입니다. |
| content.regionInfo.nameI18n.언어 코드 | string | 해당 언어의 표시 이름입니다. |
| content.regionInfo.internal | boolean | true는 중국 국내, false는 해외이며 네트워크 사설성과는 무관합니다. |
| content.regionInfo.country | string | 국가입니다. |
| content.regionInfo.province | string | 성(도)입니다. |
| content.regionInfo.city | string | 도시입니다. |
| content.regionInfo.isp | string | 통신사/제공자입니다. |
| content.regionInfo.status | string | OK/disabled 등 노드 서비스 상태이며 작업 실행 상태가 아닙니다. |
| content.regionInfo.heartbeat | integer | 노드의 최근 하트비트 Unix 초이며 업스트림 정의를 기준으로 합니다. |
| content.regionInfo.region | string | 업스트림 리전 식별자입니다. |
| content.regionInfo.company | string | 기업 정보입니다. |
| content.regionInfo.external_id | string | 자체 호스팅 소속 등 업스트림 필드이며 기본 노드에서는 보통 비어 있습니다. |
| content.regionInfo.parent_ak | string | 업스트림 호환 소속 필드로 비어 있을 수 있습니다. 클라이언트는 이를 OpenAPI Key로 간주하지 않습니다. |
| content.regionInfo.extend_info | string | 업스트림 확장 JSON 문자열 또는 빈 문자열이며 기본값이 객체가 아닙니다. |
| content.regionInfo.create_at | integer | 업스트림 생성 시간 필드로 과거 값이 -1일 수 있습니다. 작업의 createAt과 구분합니다. |
| content.regionInfo.기타 업스트림 필드 | JSON | 업스트림 호환 추가 필드를 그대로 전달받은 것이며, 나열되지 않은 키를 곧바로 쓰기 가능한 파라미터로 간주하지 마세요. |
| 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,
"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 | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 타입과 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | Body 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 이 페이지의 등록 객체를 제출합니다. |
| 400 | RegionRepeatNameKeycode | 이 공간의 자체 호스팅 노드에 동일한 keycode가 이미 존재함 | 노드 Code{}이(가) 이미 존재합니다 |
고유한 keycode로 변경하거나 기존 노드를 사용합니다. 실제 errorCode에는 ft 접두사가 없습니다. |
| 400 | RegionRepeatKeycode | 표시 이름 또는 대체 keycode가 이 공간 기존 노드의 표시 이름과 충돌함 | 노드 이름 중복 | 고유한 표시 이름으로 변경합니다. 이 레거시 오류 코드의 명칭은 검사 내용과 다르며 실제 코드에는 ft 접두사가 없습니다. |
| 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 코드로 고정 매칭하지 않습니다. |