목록 조회¶
GET /api/v1/objc_cfg/list
개요¶
리소스 카탈로그 분류 설정을 읽고 현재 보고되는 분류 및 수량을 병합합니다.
호출 전 및 사용 단계¶
라우트 권한은 routine.defaultAccess, anonymous.shared, anonymous.snapshotShared 중 하나에 해당해야 합니다. 목록의 실제 집계에는 O/CO 데이터 조회 권한 infrastructure.Query도 필요합니다. 리소스 카탈로그 읽기 권한은 데이터 조회 권한을 대체하지 않습니다.
원시 content 배열을 반환하며 페이지네이션하지 않고 name 기준 대소문자를 무시한 오름차순으로 정렬합니다. 설정은 현재 워크스페이스에서 삭제되지 않은 카탈로그에서 가져옵니다. 설정은 없지만 데이터가 있는 분류는 현재 언어의 시스템 템플릿으로 보완할 수 있으며, 그렇지 않으면 기본 빈 표시 설정을 사용합니다. uuid는 null일 수 있습니다. docCount는 이번 집계 분류에만 존재하며, 보고되지 않은 설정도 나열되지만 docCount=0이라고 단정할 수는 없습니다.
sourceType은 공개 API에서 object/custom_object만 허용하며, 공유 내부 레거시 데이터 유형을 적용하지 않습니다. 수량 통계는 최대 1000개 분류를 대상으로 하며 조회 권한/접근 규칙을 거치므로 절대적으로 완전한 자산 목록은 아닙니다. search는 로컬 설정 매칭과 다운스트림 소스 정규식에 동시에 영향을 줍니다. timeRange는 데이터 통계에만 영향을 주며 데이터가 없는 모든 설정을 숨기지는 않습니다. Query objcGroupUUID는 현재 필터링에 사용되지 않습니다.
targetWorkspaceUUIDs는 통계 소스만 전환하며, 설정/템플릿/그룹은 여전히 현재 워크스페이스에서 가져옵니다. 유효한 권한이 있어야 하고 동일 사이트여야 하며, 교차 워크스페이스 docCount를 근거로 해당 대상 워크스페이스가 현재 표시 설정을 사용한다고 오판해서는 안 됩니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| objcGroupUUID | string | 선택 사항입니다. 생성/수정 시 명시적 빈 문자열은 그룹을 비웁니다. 생략하면 템플릿 groupCfg.name을 시도하고, 이름이 없으면 빈 문자열이 되며, 수정 시 원래 그룹을 유지하지 않습니다. 비어 있지 않은 경우 현재 워크스페이스에 그룹이 존재해야 합니다. 목록 API는 이 필드를 선언하지만 현재 구현에서는 이 필드로 필터링하지 않으므로, 이를 사용해 결과를 좁히지 마십시오. 빈 문자열 허용: True null 허용: False 최대 길이: 64 예시: 획득 또는 입력 방법: 현재 워크스페이스의 리소스 카탈로그 그룹 관리 또는 목록 항목의 objcGroupUUID에서 objcg_ 식별자를 가져옵니다. |
|
| search | string | 목록 조회 시 선택 사항이며 앞뒤 공백은 제거됩니다. 로컬 설정은 name/alias로 퍼지 매칭하고, 다운스트림 분류 통계에서는 이를 정규식 소스 표현식에 결합합니다. 특수 정규식/백틱은 범위를 변경하거나 파싱 오류를 일으킬 수 있습니다. 일반 키워드를 사용하는 것이 좋으며, 결과의 모든 항목에 docCount가 있다고 보장하지 않습니다. null 허용: False 예시: example획득 또는 입력 방법: 호출자가 분류명/별칭 키워드를 입력합니다. |
|
| sourceType | string | Y | 공개 API에서 필수이며 object/custom_object만 허용합니다. 공유 내부 함수의 *_history는 지원하지 않습니다. 생성 시 실제로는 templateInfo.main[0].class를 사용하므로 반드시 이 필드와 일치해야 합니다. 수정/읽기에서는 설정 유형을 선택하는 데 사용됩니다. 삭제는 공개 API에서 custom_object만 허용하며 컨트롤러가 이 유형으로 고정합니다. null 허용: False 선택 가능한 값: ['object', 'custom_object'] 예시: custom_object획득 또는 입력 방법: 시스템 객체는 object, 사용자 정의 리소스 객체는 custom_object를 선택하며, 실제 보고 데이터 소스를 기준으로 합니다. |
| targetWorkspaceUUIDs | commaArray | 목록 조회 시 선택 사항이며 영문 쉼표로 구분합니다. 전달하지 않으면 현재 워크스페이스의 엔터티 수량을 조회합니다. 다운스트림 수량 통계에만 영향을 주며, 설정/템플릿/그룹은 여전히 현재 워크스페이스에서 가져옵니다. 대상은 유효한 권한이 있어야 하고 단일 사이트에서 와야 합니다. 서로 다른 워크스페이스의 설정을 혼합해 반환하지 않습니다. 빈 문자열 허용: False null 허용: False 예시: wksp_example획득 또는 입력 방법: 권한이 부여된 워크스페이스 목록의 content[].data[].workspaceUUID에서 대상을 가져오거나 현재 워크스페이스 UUID를 사용합니다. |
|
| timeRange | string | 선택 사항이며 기본값은 문자열 []이고, 기본 조회 기간은 쿼리 서비스가 결정합니다. 수량 통계에만 영향을 주며 로컬 설정을 자르지 않습니다. --data-urlencode로 인코딩해야 하며, JSON이 아닌 문자열은 컨트롤러에서 파싱 실패 500이 발생합니다. 이는 요청 Body의 JSON 문법 오류가 아닙니다. null 허용: False 예시: [1785427200000,1785430800000]획득 또는 입력 방법: 클라이언트가 시작/종료 Unix 밀리초 타임스탬프를 두 요소의 JSON 배열로 구성한 뒤 Query 문자열로 직렬화합니다. |
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/objc_cfg/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode sourceType=custom_object \
--data-urlencode 'timeRange=[1785427200000,1785430800000]'
응답¶
HTTP 200, application/json입니다. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | 객체 배열 | 분류 배열이며 비어 있으면 []입니다. |
| content[].uuid | string 또는 null | 로컬 설정 UUID입니다. 보고/시스템 템플릿에만 있고 로컬 설정이 없으면 null입니다. |
| content[].name | string | 분류 코드이며 이후 내보내기/수정/삭제에 사용합니다. uuid는 사용하지 않습니다. |
| content[].alias | string 또는 null | 표시 별칭입니다. |
| content[].fields | 객체 배열 | 설정 필드 정의입니다. |
| content[].fields[].name | string | 실제 보고 필드명입니다. name을 반드시 포함하고 중복되지 않아야 하며, 필드 명명 규칙을 따릅니다. |
| content[].fields[].alias | string | 선택적 표시 별칭입니다. |
| content[].filters | 객체 배열 | 빠른 필터 항목입니다. |
| content[].filters[].key | string | 필터 필드입니다. |
| content[].tableColumns | 객체 배열 | 목록 열 설정입니다. |
| content[].tableColumns[].key | string | 열 필드입니다. |
| content[].tableDetailViews | 객체 배열 또는 object | 상세 설정입니다. 템플릿이 없는 분기에서는 {}일 수 있습니다. |
| content[].iconSet | object | 조건부 아이콘 설정입니다. 설정이 없는 분기에서는 생략할 수 있습니다. |
| content[].iconSet.icon | string | 조건부 아이콘 식별자입니다. |
| content[].iconSet.url | string | 조건부 이미지 URL입니다. |
| content[].objcGroupUUID | string | 로컬 그룹 UUID이며 값이 없으면 빈 문자열입니다. |
| content[].objcGroupInfo | object | 선택적 그룹 정보이며 로컬/템플릿 소스에 따라 다릅니다. |
| content[].objcGroupInfo.id | integer | 로컬 그룹 레코드 번호이며 생략할 수 있습니다. |
| content[].objcGroupInfo.uuid | string | 그룹 UUID입니다. |
| content[].objcGroupInfo.workspaceUUID | string | 소속 워크스페이스이며 생략할 수 있습니다. |
| content[].objcGroupInfo.name | string | 그룹 이름입니다. |
| content[].objcGroupInfo.creator | string | 조건부 생성자입니다. |
| content[].objcGroupInfo.updator | string | 조건부 수정자입니다. |
| content[].objcGroupInfo.createAt | integer | 조건부 생성 Unix 초입니다. |
| content[].objcGroupInfo.updateAt | integer | 조건부 수정 Unix 초입니다. |
| content[].objcGroupInfo.deleteAt | integer | 조건부 삭제 Unix 초이며 삭제되지 않았으면 -1입니다. |
| content[].objcGroupInfo.status | integer | 조건부 그룹 상태입니다. |
| content[].bindSet | array | 설정이 없는 분기에서만 사용하는 레거시 자리 표시자 필드입니다. |
| content[].docCount | integer 또는 number | 이번 엔터티 집계와 일치하는 분류에만 이 필드가 있습니다. 설정은 있지만 일치하는 데이터가 없으면 생략될 수 있으며, 일괄적으로 0을 채우지 않습니다. |
| content[].declaration | object | 비어 있지 않은 각 배열 항목의 공통 선언입니다. |
| content[].tableDetailViews[].title | string | 탭 제목입니다. |
| content[].tableDetailViews[].viewType | string | component/dashboard입니다. |
| content[].tableDetailViews[].viewName | string | 내장 페이지 경로 또는 내장 뷰 이름입니다. |
| content[].tableDetailViews[].required | boolean | keys에 따라 표시할지 여부입니다. |
| content[].tableDetailViews[].keys | object | 동적으로 매칭할 필드/값입니다. |
| content[].tableDetailViews[].keys.字段名 | JSON | 매칭 값/존재 표시 *입니다. |
| content[].tableDetailViews[].timerange | string 또는 문자열 배열 | default/상대 기간/앞뒤 오프셋 배열입니다. |
| content[].tableDetailViews[].timerange[] | string | 단일 앞/뒤 오프셋 기간입니다. |
{
"code": 200,
"content": [
{
"uuid": "objc_example",
"name": "example_resources",
"alias": "示例资源目录",
"fields": [
{
"name": "name",
"alias": "资源名称"
}
],
"filters": [
{
"key": "env"
}
],
"tableColumns": [
{
"key": "name"
}
],
"tableDetailViews": [],
"iconSet": {},
"objcGroupUUID": "",
"docCount": 2,
"declaration": {}
}
],
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
현재 API Key 워크스페이스의 설정만 수정/내보내기할 수 있습니다. 목록은 권한이 부여된 대상 워크스페이스에 대해 집계할 수 있지만, 표시 설정은 여전히 현재 워크스페이스의 것입니다. 인터페이스에는 freeEdition 버전 선언이 있지만, 공통 OpenAPI 인증은 이 라우트에서 해당 버전 검사를 수행하지 않으므로 버전 자체를 고정 403으로 기재하지 않습니다. 업스트림 조회 4xx는 실제 Kodo/권한 매핑에 따릅니다. 일반 5xx는 최종적으로 500 ft.InternalServerError가 됩니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방식 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 유형 및 값을 확인하십시오. |
| 406 | ft.workspaceUnauthorized | 명시적 대상 워크스페이스가 현재 워크스페이스에 권한 부여되지 않음 | 워크스페이스[{}] 권한 없음 | 권한이 부여된 워크스페이스 목록에서 유효한 대상을 다시 선택하십시오. |
| 406 | ft.UnsupportMultiSiteQuery | 대상 권한이 여러 사이트에 걸쳐 있거나 외부 조직 주소가 고유하지 않음 | 다중 사이트 워크스페이스 조회는 지원되지 않음 | 사이트별로 각각 요청하고 권한 부여 소스 주소를 확인하십시오. |
| 404 | ft.NoInitOtherNodeCfg | 외부 조직 교차 사이트 권한에 소스 사이트 주소가 누락됨 | 다른 노드 설정이 초기화되지 않음 | 관리자에게 연락하여 권한 부여 사이트 정보를 수정하십시오. |
| 400 | ft.InvalidWorkspace | 대상 현재 사이트의 워크스페이스가 존재하지 않거나 비활성 상태임 | 유효하지 않은 워크스페이스: {} | 권한이 부여된 워크스페이스의 현재 상태를 확인하십시오. |
| 403 | ft.ForbiddenQuery | 현재 Key에 대상 데이터 유형 조회 권한이 없음 | {} 권한이 없습니다 | 카탈로그 읽기 권한은 객체 데이터 조회 권한을 대체하지 않으므로 해당 namespace 권한을 보완하십시오. |
| 406 | ft.DqlParseError | search의 특수 문자 등으로 생성 표현식 파싱이 실패함 | dql parser 파싱 실패: {} | 먼저 특수 정규식/백틱을 제거하고 일반 분류 키워드를 사용하십시오. |
| 503 | ft.QueryServiceUnavailable | 업스트림 조회 503이 일시적 사용 불가로 정규화됨 | 조회 서비스를 일시적으로 사용할 수 없습니다. 잠시 후 다시 시도하십시오. | content.retryable 및 traceId에 따라 제한적으로 백오프 재시도하십시오. |
| 500 | ft.InternalServerError | 레거시 설정/시스템 템플릿 구조 이상, 시간 문자열이 JSON이 아님, 조회/데이터 포맷팅에서 포착되지 않은 오류 | 내부 오류 | 파라미터와 레거시 템플릿을 확인하고 읽기 범위를 좁힌 뒤 제한적으로 재시도하며 traceId를 보존하십시오. 읽기는 이번 설정 쓰기를 수행하지 않습니다. |