조회¶
GET /api/v1/dialing_region/{region_uuid}/info
개요¶
현재 워크스페이스의 자체 호스팅 노드 및 배포 서비스 주소를 읽습니다.
호출 전 및 사용 단계¶
먼저 이 워크스페이스의 자체 호스팅 노드 소속을 조회한 후 다운스트림 상세를 가져옵니다. 기본 공용 노드/다른 워크스페이스 노드이거나 존재하지 않는 UUID는 유효하지 않은 자체 호스팅 노드로 간주되어 403이 됩니다. 이 API에는 Query 비즈니스 파라미터가 없으며 작업 실행이나 설치를 트리거하지 않습니다. server는 현재 배포 서비스의 프로토콜/호스트/포트로 구성되며 노드 연결에 사용됩니다. 자체 호스팅 노드 관리의 region_id/ak/sk 설정과 함께 사용해야 하며, server를 이번 OpenAPI Endpoint로 간주해서는 안 됩니다.
다운스트림 content는 그대로 전달되며, 외부에 server와 표준 표시 이름을 추가합니다. 현재 평면 노드 예시와 이전 ak/regionInfo 래핑이 모두 나타날 수 있고, 중첩 래핑의 이름은 재귀적으로 정규화하지 않으며, credentials는 업스트림에서 실제로 반환된 경우에만 존재합니다. 노드 자격 증명이 포함된 응답은 안전하게 보관해야 합니다. 이 응답에서 전체 배포 자격 증명을 얻을 수 없는 경우 제품의 “구성 조회”를 사용하고, AK/SK를 임의로 만들어서는 안 됩니다.
경로 파라미터¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| region_uuid | string | Y | 기본 공용 노드, 모바일 노드 ID, keycode 또는 작업 UUID가 아닙니다. 예시: regn_example조회 또는 입력 방법: 자체 호스팅 노드 목록에서 현재 워크스페이스의 owner=custom 노드의 uuid를 가져옵니다. |
요청 헤더¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>조회 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/dialing_region/regn_example/info' \
-H 'DF-API-KEY: <DF-API-KEY>'
응답¶
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.server | string | 현재 노드 서비스의 전체 기본 주소, 배포 노드에서 사용하며 이 OpenAPI 주소가 아닙니다. |
| 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,
"server": "https://dialing-service.example.com",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
업스트림 호환 래핑 예시(자격 증명은 모두 자리 표시자이며, regionInfo는 업스트림 구조를 유지합니다. 최외곽 이름이 내부 노드를 나타내지 않을 수 있습니다):
{
"code": 200,
"content": {
"ak": {
"ak": "NODE-AK-PLACEHOLDER",
"sk": "NODE-SK-PLACEHOLDER",
"external_id": "wksp_example",
"owner": "",
"parent_ak": "PARENT-AK-ID",
"status": "",
"update_at": 0
},
"regionInfo": {
"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
},
"server": "https://dialing-service.example.com",
"name": "",
"nameEn": "",
"nameI18n": {
"zh": "",
"en": "",
"zh-hant": "",
"id": "",
"ja": "",
"ko": ""
},
"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 | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 403 | ft.ForbiddenInvalidSelfBuiltNode | UUID가 현재 워크스페이스의 자체 호스팅 노드 집합에 없음(기본/다른 워크스페이스/존재하지 않음 포함) | 잘못된 작업, 유효하지 않은 자체 호스팅 노드 ID | 이 워크스페이스의 자체 호스팅 목록에서 uuid를 다시 가져오고, keycode로 대체하지 않습니다. |
| 406 | ft.DialingBrandNoSetError | 워크스페이스에 대응하는 신서틱 서비스 브랜드 구성 누락 | {} 브랜드의 신서틱 테스트 구성이 설정되지 않았습니다. |
관리자가 현재 워크스페이스의 신서틱 서비스를 확인합니다. |
| 400 | ft.DialingAKNoSetError | 신서틱 서비스 서명 자격 증명 미구성 | 신서틱 테스트 AK 정보가 구성되지 않았습니다. Launcher 활성화 구성을 확인하십시오. | 관리자가 서비스 활성화 정보를 확인하며, 클라이언트는 이 Body에 해당 자격 증명을 제출하지 않습니다. |
| 400 | ft.DialingServerError | 다운스트림 신서틱 노드 API가 400 비즈니스 실패를 반환하거나 응답 미디어를 파싱할 수 없음 | 신서틱 서비스 API 호출 실패 | message/traceId를 확인하고 관리자가 노드 서비스를 점검해야 하며, 실패를 노드 없음으로 간주해서는 안 됩니다. |
| 500 | ft.InternalServerError | 일반 다운스트림 5xx/연결 예외, 또는 이력 노드/연관 필드 형식, 이름 및 응답 조립 예외 | 내부 오류 | 특정 노드/필터로 좁혀 업스트림 응답 형식과 서비스 가용성을 확인하고, 지속 실패 시 traceId를 보관합니다. |
| 400 | ft.DialingRegionError | 다운스트림 HTTP 400이고 error_code=dialtesting.invalidRegion인 경우; 기타 4xx도 동일 코드로 매핑되고 실제 HTTP를 유지 | 현재 작업에 일부 신서틱 노드가 유효하지 않습니다. 구성을 업데이트한 후 다시 저장하십시오. | 유효한 자체 호스팅 노드 및 노드 서비스 상태를 확인하고, 원시 dialtesting 코드를 기준으로 고정 매칭하지 않습니다. |