카탈로그 엔터티 생성 및 수정¶

CLI와 MCP에서 owl.catalog.entity_create, owl.catalog.entity_modify를 호출할 수 있습니다. 해당 CLI, Registry 및 쓰기 API를 제공하는 AIAPI / Backend를 업그레이드하고 카탈로그를 동기화하세요. 기능과 권한은 대상 사이트에 따라 다릅니다. 쓰기 전에 정확한 대상과 변경 내용을 확인합니다.

유형, 팀 및 엔터티 확인¶

owl sync
owl exec owl.catalog.entity_type_query -p '{"page_size":20,"page_index":1}'
owl exec owl.workspace.member.group_list -p '{"search":"Platform"}'
owl exec owl.catalog.entity_query -p '{"entity_type":"service","name":"checkout-api"}'

선택한 유형의 schemaDefine과 customProperties를 읽고 필수 속성을 모두 채웁니다. 최상위 name은 별도의 필수 속성을 대신하지 않습니다. 동적 속성과 관계는 백엔드에서 검증합니다.

entity_query에는 entity_type이 필수입니다. name은 정확한 이름, search는 이름·표시 이름·URN의 유사 검색이며 함께 지정할 수 없습니다. urn과 filters로 결과를 좁힐 수 있습니다. filters는 카탈로그 필드 문법이며 SQL/DQL이 아닙니다. name과 filters.name을 함께 사용하면 이름이 같아야 합니다.

팀 조회는 group_uuid, name, member_count를 반환하며 페이지 구분이 없습니다. owl.member.group_list는 호환 별칭입니다. attributes.owner에는 팀 UUID나 개인 이름이 아닌 반환된 팀 이름을 사용합니다. 값의 형식은 유형 정의를 따릅니다. 무료 버전 워크스페이스에서는 팀 조회를 사용할 수 없습니다.

생성 및 부분 수정¶

생성에는 request_id(UUID), entity_type, name이 필수이며 display_name, attributes, relation_modes는 선택 사항입니다. name은 최대 1024자, 비어 있지 않은 display_name은 최대 256자이며 생략하면 name을 사용합니다. 기존 식별자나 같은 유형·이름의 엔터티를 덮어쓰지 않습니다.

수정에는 request_id와 조회에서 반환된 완전한 urn이 필요합니다. 변경할 display_name, attributes, relation_modes만 전송합니다. name 변경, 유형 변경, 워크스페이스 간 쓰기는 지원하지 않습니다. 조회 item 전체를 되돌려 보내지 말고 표시 이름은 최상위 display_name에 지정하세요.

생략한 필드는 유지합니다. 객체는 재귀 병합하고 일반 배열은 전체 교체합니다. 빈 객체는 비우기 명령이 아니며 null은 삭제 명령이 아닙니다. 수동 쓰기는 provider와 수명 주기를 변경할 수 있습니다.

실제 유형에 정의된 관계만 제출합니다. 수정하는 depends_on, component_of, components마다 relation_modes를 지정합니다. add는 추가 및 중복 제거, replace는 전체 교체이며 빈 배열과 replace는 비우기입니다. 생성의 기본값은 replace입니다. 대상은 현재 워크스페이스에 존재하는 URN이어야 하고 자기 자신을 참조할 수 없습니다. 모든 유형이 components를 지원하지는 않습니다.

쓰기 결과 및 확인¶

새 작업마다 UUID 하나를 생성하고 도구, 정확한 매개변수와 사용자·워크스페이스 맥락을 영구 기록합니다. 자격 증명 값은 저장하지 않습니다. CLI -f json으로 업무 결과를 확인하세요. 종료 코드 0, HTTP 200 또는 외부 success만으로 완료를 판단하지 마세요.

성공 결과에는 data.write_state=confirmed, 일치하는 request_id 및 엔터티 URN이 필요합니다. changed=false는 변경 없는 성공일 수 있습니다. replayed=true는 또 쓰기했다는 의미가 아닙니다. confirmed는 엔터티 재조회와 감사 작업 제출까지 완료되었다는 뜻이며 최종 감사 저장을 증명하지 않습니다.

can_retry_write=true일 때만 후속 호출이 업무 쓰기를 재시도할 수 있습니다. retry_after_ms(최대 30000밀리초)와 총 6회 제출 제한을 따르고, 원래 UUID와 매개변수를 재사용합니다. 다른 pending은 확인만 합니다. audit_unknown을 자동 재시도하지 마세요.

백엔드 상태는 워크스페이스, 실제 계정, request_id별로 7일간 유지합니다. 만료, 상태 소실 또는 사용자·워크스페이스 변경 후에는 먼저 조회하여 대조합니다. 이전 UUID는 영구 중복 방지 수단이 아닙니다. 한 번의 도구 호출은 자동 폴링이나 업무 쓰기 재전송을 하지 않습니다.