콘텐츠로 이동

통합 카탈로그 엔터티 수정



POST /api/v1/unified_catalog/entity/modify

개요

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

호출 전 및 사용 단계

수정하려면 먼저 get으로 백업하고 원래 urn, entityType, name 및 보존해야 하는 전체 속성을 다시 채워야 합니다. 이 엔드포인트와 생성은 모두 ingest/upsert를 호출하며, 엄격한 존재 여부 기반 업데이트가 아닙니다. 찾지 못해도 생성될 수 있고, urn을 생략한 채 이름을 변경하면 새 엔터티가 형성될 수 있습니다.

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

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

모든 엔터티 유형은 유효한 상태 구성에 따라 처리되며, 백그라운드 기록 정리 진행 상황에 의존하지 않습니다. 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 검증을 항목별로 수행하지 않으며, 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이 아닙니다. 이 인터페이스는 함수를 즉시 실행하여 출력을 검증하지 않습니다.
예: 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을 전달하지 않은 쓰기는 다운스트림에서 ID에 따라 위치를 생성합니다.
null 허용: False
예: demo
가져오기 또는 입력 방법: 호출자가 엔터티 비즈니스 이름을 제공하며, 기존 상세 name에서 다시 채워 수정합니다.
telemetrySelectors array 선택적 배열이며, 요소는 연관 소비자의 구성 규약에 따라 유지됩니다. 비어 있지 않은 경우에만 ingest로 전달됩니다. 생략과 [] 모두 telemetry_selectors를 전달하지 않으므로, []로 기존 연관을 비우겠다고 약속할 수 없습니다.
null 허용: False
예: []
가져오기 또는 입력 방법: 현재 엔터티의 텔레메트리 연관 구성 또는 관련 유형 extraConfig의 기존 구성에서 가져옵니다. 이 인터페이스에서 DQL을 임의로 생성하지 않습니다.
urn string 읽기/삭제 시 필수이며 앞뒤 공백 제거 후 비어 있지 않아야 합니다. 목록/통계에서는 선택적 정확 필터입니다. 수정 시 원래 URN을 명확히 입력하여 이름 변경 시 다른 엔터티가 생성되는 것을 방지하는 것이 좋습니다.
null 허용: False
예: urn:database:default:demo
가져오기 또는 입력 방법: 현재 워크스페이스의 엔터티 목록 items[].urn에서 가져오며, 가능하면 전체 URN을 그대로 사용합니다.

파라미터 추가 설명

요청 파라미터 설명

파라미터 이름 유형 필수 설명
urn string 아니요 엔터티 URN이며, 엔터티를 정확히 지정하려면 전달하는 것이 좋습니다
entityType string 예 엔터티 유형 코드
name string 예 엔터티 이름
attributes json 아니요 업데이트할 엔터티 속성 객체
telemetrySelectors array 아니요 업데이트할 엔터티 연관 쿼리 구성

관계 필드 사용 설명

  • attributes.depends_on는 links로 기록됩니다.
  • attributes.component_of는 contains로 기록되며, 방향은 parent/system -> 현재 엔터티입니다.
  • attributes.components도 contains로 기록되며, 방향은 현재 엔터티 -> component입니다.
  • 관계를 비우려면 빈 배열을 명시적으로 전달하십시오. 예: {"component_of":[]} 또는 {"components":[]}.

호출 시 유의 사항

  • urn, entityType, name을 함께 전달하는 것이 좋습니다.
  • 수정 성공 후 대상 엔터티의 urn을 반환합니다.
  • 태그 필드에 새 태그 이름을 전달하면 해당 태그도 자동으로 생성됩니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity/modify' \
  -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"]},"urn":"urn:database:default:demo"}'

응답

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으로 속성과 관계를 다시 읽고, 태그 및 유효 상태를 확인한 후 재시도 여부를 결정하며, 무작정 이름을 바꿔 재생성하지 마십시오.

문서 평가

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