콘텐츠로 이동

생성



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 코드로 고정 매칭하지 않습니다.

문서 평가

이 페이지가 도움이 되었나요?