콘텐츠로 이동

통합 카탈로그 엔터티 생성



POST /api/v1/unified_catalog/entity/create

개요

유형과 이름을 기준으로 카탈로그 엔터티 및 해당 관계, 태그, 텔레메트리 연결을 생성하거나 업데이트합니다.

호출 전 및 사용 단계

먼저 유형 목록에서 엔터티 유형 코드를 가져오고, 해당 DataSchema에 따라 속성을 작성합니다. 현재 진입점은 ingest/upsert이며, '이미 존재하면 거부'하는 생성 보장은 제공하지 않습니다. 동일한 아이덴티티로 중복 제출하면 업데이트될 수 있습니다. 생성 후에는 반환된 URN을 사용해 읽어서 확인합니다.

관계는 attributes.depends_on/component_of/components에만 넣으며, 이 페이지의 방향에 따라 links/contains를 생성합니다. 관계 URN은 짧게 작성할 수 있고 정규화되며, components 객체의 추가 키는 유지됩니다. 관계를 비우려면 명시적으로 []를 지정해야 하며, 생략으로 비우기를 표현해서는 안 됩니다. owner는 활성 팀 이름으로 해석되며, 존재하지 않는 태그는 자동으로 생성됩니다. 속성/텔레메트리 구조는 비즈니스 Schema에 따라 항목별로 검증되지 않습니다. 임의의 확장 설정이 저장에 성공한 것을 실행 성공으로 간주하지 마십시오. telemetrySelectors는 비어 있지 않은 경우에만 전달되며, []로 기존 값을 비울 수 있다고 보장하지 않습니다.

반환된 urn은 이번 쓰기 호출에서 획득한 식별자만 의미하며, 완전한 엔터티나 비동기 처리 전체 완료를 의미하지 않습니다. 공개 체인에는 AI API 전용 어댑터의 읽기 병합/다운스트림 완료 검증 보장이 없으므로 반드시 get/list로 다시 읽어야 합니다. 태그 데이터베이스, 엔터티/관계 쓰기 및 헬스 재설정은 서비스 간 원자적 트랜잭션이 아니므로, 실패 시 부분 성공이 남을 수 있습니다. 헬스가 disabled인 쓰기 후에는 동기적으로 결과 재설정을 시도하며, 실패하면 보상 작업을 전달하고 오류를 반환합니다. 계산 함수는 이 API에서 즉시 실행되지 않습니다.

모든 엔터티 유형은 유효한 헬스 설정에 따라 처리되며, 백그라운드의 과거 데이터 정리 진행 상황에 의존하지 않습니다. system에 유형 정책이 구성되지 않은 경우 기본값은 default이고, 다른 유형에 구성되지 않은 경우 기본값은 disabled입니다. 엔터티는 inherit로 유형을 상속하고, custom으로 Func를 지정하며, disabled로 비활성화합니다. 유형이 비활성화되면 healthScore=null, healthStatus=unknown, healthUpdateAt=null을 반환하며, 헬스 필터링/통계도 과거 결과가 아닌 비활성화 상태를 기준으로 합니다. 필터링/정렬/통계의 최상위 헬스 필드를 사용할 때는 entityType을 반드시 명시해야 합니다.

요청 헤더

매개변수명 타입 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예시: <DF-API-KEY>
획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다.

Body 요청 파라미터

매개변수명 타입 필수 설명
attributes.사용자 정의 필드 JSON 동적 비즈니스 필드로, 유형 정의에 따라 제출합니다. Studio는 DataSchema 검증을 항목별로 수행하지 않으며, HTTP 200으로 임의의 확장 필드가 올바르게 수집되었거나 조회 가능함을 보장하지 않습니다.
예시: prod
획득 또는 입력 방법: 필드 이름, 타입, 출처는 해당 유형의 DataSchema 및 기존 엔터티 원본 속성을 참고합니다.
attributes.depends_on array<string> 선택 사항입니다. 현재 엔터티에서 대상으로 향하는 links 관계를 기록합니다. 전체 URN 또는 유형:이름(default 네임스페이스 보완)을 지원합니다. 명시적 []는 해당 관계 그룹을 비우도록 요구하며, 생략은 다른 기존 관계를 덮어쓰지 않음을 보장하지 않습니다.
예시: ["service:api"]
획득 또는 입력 방법: 현재 워크스페이스의 엔터티 목록에서 의존 대상 URN을 가져옵니다.
attributes.depends_on[*] string 앞뒤 공백을 제거하고 urn:유형:default:이름으로 정규화합니다. 표시 이름이나 워크스페이스 간 UUID를 사용하지 마십시오.
예시: service:api
획득 또는 입력 방법: 단일 의존 대상 URN/유형:이름.
attributes.component_of array<string> 선택 사항입니다. 상위 엔터티에서 현재 엔터티로 향하는 contains 관계를 기록합니다. []는 비우기를 요청하며, 여러 상위 항목은 관계 기준으로 중복 제거됩니다.
예시: ["system:payments"]
획득 또는 입력 방법: 현재 워크스페이스의 시스템/상위 엔터티 목록에서 URN을 가져옵니다.
attributes.component_of[*] string 방향은 상위 → 현재이며, 짧게 작성하면 default 네임스페이스가 보완됩니다.
예시: system:payments
획득 또는 입력 방법: 단일 상위 엔터티/시스템 URN.
attributes.components array<string 또는 object> 선택 사항입니다. 방향은 현재 → 하위 엔터티의 contains입니다. []는 비우기를 요청합니다. 문자열 항목 또는 entity를 포함한 객체입니다. 객체의 추가 필드는 attributes에 유지되며, 상세 관련 contains 관계에 이러한 설정을 첨부할 수 있습니다.
예시: ["database:demo"]
획득 또는 입력 방법: 현재 엔터티의 구성 멤버 목록에서 하위 엔터티 URN을 가져옵니다. 원본 상세 속성에서 객체 확장 설정을 다시 채울 수 있습니다.
attributes.components[*] string 또는 object 객체 항목은 entity로 대상을 지정하며, 기타 설정은 고객이 정의하고 해당 계산 기능에서 사용합니다. 임의의 필드를 이미 강하게 검증된 것으로 간주하지 않습니다.
예시: {"entity": "database:demo", "required": true}
획득 또는 입력 방법: 단일 구성 엔터티 URN 또는 원본 컴포넌트 설정 객체.
attributes.components[*].entity string 객체 형식에서는 비즈니스상 필수입니다. 짧게 작성하면 속성 및 관계 저장 시 정규화됩니다.
예시: database:demo
획득 또는 입력 방법: 단일 하위 엔터티 URN.
attributes.components[*].확장 설정 JSON 동적 추가 설정은 유지됩니다. 통일된 서버 측 기본값/열거형은 없으며, 의존 가중치 등의 필드를 임의로 만들어내지 마십시오.
예시: true
획득 또는 입력 방법: 원본 컴포넌트 설정 또는 실제 헬스 계산/뷰 요구 사항에서 가져옵니다.
attributes.custom_tags array<string> 문자열 이름 배열을 권장합니다. 쉼표로 구분된 문자열/객체 키와 호환됩니다. 공백을 제거하고 중복을 제거합니다. 존재하지 않는 태그는 자동으로 생성되며, 단순 조회만 수행하지 않습니다. []는 이번에 생성할 태그가 없음을 의미합니다. 엔터티 속성 보존 로직을 적용하려면 먼저 원본 값을 백업해야 합니다.
예시: ["mysql"]
획득 또는 입력 방법: 태그 목록에서 이름을 선택하거나 비즈니스 담당자가 새 이름을 제공합니다.
attributes.custom_tags[*] string 새 이름으로 해당 태그를 생성할 수 있으며, 태그 이름 및 범위 규칙의 제약을 받습니다.
예시: mysql
획득 또는 입력 방법: 현재 워크스페이스의 단일 태그 이름이며, tag_ UUID가 아닙니다.
attributes.owner string 또는 array<string> 쓰기 시 팀 이름으로 정확히 해석합니다. 모든 비어 있지 않은 이름은 존재해야 하며, 그렇지 않으면 404 팀이 존재하지 않음이 발생합니다. 팀을 자동으로 생성하지 않습니다. 빈 문자열/[]는 비웁니다. 개인 이메일/계정 UUID가 아니며, 기존 읽기에서는 group_ 참조와 호환될 수 있습니다.
예시: ["DBA"]
획득 또는 입력 방법: 팀 목록에서 현재 워크스페이스의 활성 팀 name을 가져옵니다.
attributes.owner[*] string 이름은 공백을 제거하고 처음 나타난 순서로 중복을 제거하며, 대소문자는 실제 이름 비교를 따릅니다.
예시: DBA
획득 또는 입력 방법: 단일 기존 활성 팀 이름.
attributes.health_calculation string 선택 사항이며 inherit/custom/disabled 중 하나입니다. inherit는 유형을 상속하고, custom은 func_id를 함께 지정해야 하며, disabled는 이 엔터티를 비활성화합니다. func_id만 제공하면 custom으로 호환 처리됩니다. 헬스 필드 중 하나라도 있으면 비즈니스 검증/잠금을 수행하며, 둘 다 전달하지 않으면 새로운 필수 제약을 추가하지 않습니다. 유형이 disabled이면 엔터티의 활성화 상태를 덮어씁니다.
예시: inherit
획득 또는 입력 방법: 호출자가 엔터티 재정의 정책을 선택합니다. 유형 기본 정책은 유형 상세의 healthConfig에서 확인합니다.
attributes.func_id string custom일 때 필수이며 삭제되지 않은 함수가 존재해야 합니다. inherit/disabled일 때는 빈 문자열을 기록합니다. 함수 표시 이름, 스크립트 소스 코드 또는 원격 URL이 아닙니다. 이 API는 함수를 즉시 실행해 출력을 검증하지 않습니다.
예시: func_example
획득 또는 입력 방법: 현재 워크스페이스의 Func 함수 관리에서 활성 함수 UUID를 가져오고, 해당 함수가 헬스 점수 입력/출력 규약을 충족하는지 확인합니다.
telemetrySelectors[*] JSON 동적 연결 항목이며, 공개 진입점에는 통일된 강한 검증 하위 구조가 정의되어 있지 않습니다. source/query는 기존 사용 예시일 뿐이며, 유일한 필수 기준으로 간주할 수 없습니다.
예시: {"source": "logging", "query": "service:api"}
획득 또는 입력 방법: 검증된 텔레메트리 연결 원본 설정에서 전체를 복사하며, 필드는 사용하는 쪽에 따라 달라집니다.
telemetrySelectors[*].source string 예시용 확장 키이며, 공개적으로 통일된 필수 항목이 아닙니다. 실제 연결을 사용하는 기능이 지원하는 값을 따릅니다.
예시: logging
획득 또는 입력 방법: 기존 설정의 텔레메트리 범주/출처.
telemetrySelectors[*].query string 예시용 확장 키이며 형식은 사용하는 쪽에 따릅니다. 저장 시 쿼리를 실행하거나 실행 가능 여부를 검증하지 않습니다.
예시: service:api
획득 또는 입력 방법: 기존 설정의 쿼리/선택 표현식.
attributes json 선택적 동적 객체입니다. 생략하면 ingest에 {}를 전달합니다. 공개 흐름은 현재 객체를 직접 제출하며, 원본 속성을 읽은 후 안전하게 깊은 병합을 수행한다는 보장이 없습니다. 수정 시에는 먼저 get한 뒤 보존해야 할 속성을 다시 채워야 합니다. healthScore 등 읽기 전용 계산 결과를 다시 채우지 마십시오.
null 허용: False
예시: {"project": "demo", "env": "prod", "custom_tags": ["mysql"]}
획득 또는 입력 방법: 엔터티 유형 schemaDefine/effectiveSchemaDefine에 따라 실제 속성 값을 제공하거나 원본 상세 attributes에서 백업합니다.
entityType string Y 목록/통계에서는 선택 사항입니다. 최상위 헬스 필드로 필터링, 통계 또는 정렬할 때는 비즈니스상 필수입니다. 생성/수정 시 필수이며 공백 제거 후 비어 있지 않아야 합니다. 내보내기에서는 필수입니다.
null 허용: False
예시: database
획득 또는 입력 방법: 엔터티 유형 목록 items[].entityType에서 코드를 가져오며, 유형 UUID/표시 이름이 아닙니다.
name string Y 생성/수정 시 필수이며 앞뒤 공백 제거 후 비어 있지 않아야 합니다. URN이 아닙니다. 이름을 변경할 때는 기존 urn도 함께 다시 채우며, urn을 전달하지 않은 쓰기는 다운스트림에서 아이덴티티 기준으로 위치를 생성합니다.
null 허용: False
예시: demo
획득 또는 입력 방법: 호출자가 엔터티 비즈니스 이름을 제공하며, 기존 상세의 name에서 다시 채워 수정합니다.
telemetrySelectors array 선택적 배열이며, 요소는 연결을 사용하는 쪽의 설정 규약에 따라 유지됩니다. 비어 있지 않은 경우에만 ingest로 전달됩니다. 생략과 [] 모두 telemetry_selectors를 전달하지 않으므로, []로 기존 연결이 비워진다고 보장할 수 없습니다.
null 허용: False
예시: []
획득 또는 입력 방법: 현재 엔터티의 텔레메트리 연결 설정 또는 관련 유형 extraConfig의 기존 설정에서 가져옵니다. 이 API에서 DQL을 임의로 생성하지 않습니다.

파라미터 추가 설명

요청 파라미터 설명

매개변수명 type 필수 설명
entityType string 예 엔터티 유형 코드
name string 예 엔터티 이름
attributes json 아니요 엔터티 속성 객체
telemetrySelectors array 아니요 엔터티 연결 조회 설정

attributes 자주 사용하는 확장 필드 설명

필드명 type 설명
depends_on array[string] 의존 관계이며, 기록 시 links로 변환됩니다.
component_of array[string] 소속 관계이며, 기록 시 contains로 변환됩니다. 방향은 parent/system -> 현재 엔터티입니다.
components array[json/string] 구성 엔터티 목록이며, 기록 시에도 contains로 변환됩니다. 방향은 현재 엔터티 -> component입니다.
custom_tags array/string 사용자 정의 태그이며, 태그가 존재하지 않으면 자동으로 생성됩니다.
owner string/array 팀 이름이며, 백엔드에서 팀 이름으로 팀 정보를 해석합니다.

호출 시 유의 사항

  • 관계 필드는 일괄적으로 attributes에 담아 전달하며, relations를 별도로 전달할 필요가 없습니다.
  • attributes.components는 문자열 배열 또는 entity를 포함한 객체 배열을 전달할 수 있습니다. 객체의 다른 필드는 엔터티 attributes에 유지됩니다.
  • custom_tags를 전달하는 경우 태그 이름 배열을 사용하는 것이 좋습니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity/create' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"entityType":"database","name":"demo","attributes":{"env":"prod","project":"demo","custom_tags":["mysql"]}}'

응답

HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.

필드 타입 설명
content.urn string ingest가 반환한 엔터티 URN입니다. 비정상적인 성공 형태에서는 빈 문자열일 수 있으므로 반드시 다시 읽어 확인해야 합니다.
content.declaration object 공개 선언입니다.
{
  "code": 200,
  "content": {
    "urn": "urn:database:default:demo",
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.

다운스트림 오류는 Kodo 공유 매핑을 따르며, 4xx는 실제 HTTP와 ft.KodoCommonApiErr 또는 매핑된 비즈니스 코드를 반환할 수 있습니다. 모든 실패가 406으로 변환되는 것은 아닙니다. 전달되지 않은 5xx/연결 예외/성공 결과 구조 불일치는 최종적으로 500 ft.InternalServerError가 됩니다. errorCode/message/traceId를 보존하고 읽기 또는 쓰기 단계에 따라 처리하십시오. 성공 HTTP가 엔터티의 실제 가시성 확인을 대체할 수는 없습니다.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다. 파라미터 파싱 실패 파라미터 위치, 필드 이름, 타입 및 값을 확인합니다.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않습니다. 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정합니다.
400 ft.JsonFormatError Body 최상위가 JSON 객체가 아닙니다. 일부 json 파일 형식 오류 예시와 같이 객체를 제출하고 배열/문자열을 사용하지 않습니다.
406 ft.ExceedMaxCharacterLimit 자동 생성된 태그 이름이 가중치 적용 문자 길이 제한을 초과했습니다. {}이(가) 최대 문자 길이 제한을 초과했습니다. 태그 규범에 맞는 짧은 이름을 사용해 초과 길이 태그를 피하고, 먼저 엔터티가 이미 기록되었는지 확인합니다.
406 ft.InvalidParameter entityType/name이 공백 제거 후 비어 있거나 헬스 재정의 모드/Func가 유효하지 않습니다. 파라미터 {}가 유효하지 않습니다. 기존 유형과 비어 있지 않은 이름을 사용합니다. custom은 현재 워크스페이스의 삭제되지 않은 Func에 바인딩하고, inherit/disabled에는 이전 func_id가 남지 않도록 합니다.
404 ft.NotFound owner에 현재 워크스페이스에 존재하지 않거나 비활성인 팀 이름이 포함되어 있습니다. 팀이 존재하지 않음: {팀 이름} 팀 목록에서 활성 팀 이름을 가져옵니다. 여기서는 개인 이메일/계정 UUID를 허용하지 않습니다.
429 ft.OperationTooFrequently 헬스 재정의 필드가 포함된 동시 쓰기에서 상호 배제 잠금을 획득하지 못했습니다. 작업이 너무 빈번합니다. 잠시 후 다시 시도하십시오. 잠시 후 제한된 백오프로 재시도하고, 먼저 대상을 다시 읽어 중복 생성을 피합니다.
500 ft.InternalServerError 다운스트림 쓰기/쓰기 후 읽기, 태그 영속화, 헬스 재설정/보상, 캐시 잠금 또는 형식 처리에 실패했습니다. 내부 오류 쓰기가 이미 발생했을 수 있습니다. 원래 URN으로 속성과 관계를 다시 읽고, 태그 및 유효 헬스 상태를 확인한 후 재시도 여부를 결정하며, 무작정 이름을 바꿔 재생성하지 마십시오.

문서 평가

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