설정

새 커넥터의 연결 정보와 사용 권한을 설정합니다. 기존 커넥터에서는 값을 수정하고 연결 테스트로 접속 상태를 확인합니다.

등록 흐름

1. 데이터 연결 목록 페이지 오른쪽 위에서 커넥터 등록을 클릭합니다.
2. 편집 페이지(/connectors/new)로 이동합니다.
3. 지원 기술·관리형 또는 커스텀 연결 방식을 고릅니다. 선택한 방식에서 기술이나 유형을 정하고 기본 정보와 연결 설정을 채운 뒤 생성합니다.

커넥터는 관리자(admin) 또는 매니저(manager) 권한이 있는 사용자만 만듭니다. 권한이 없으면 화면 상단에 안내 배너가 표시되고 입력이 읽기 전용으로 잠깁니다.

편집 화면 구성

편집 화면은 탭으로 나뉩니다.

탭	내용
기본 정보	연결 방식과 기술·유형 선택(생성 시), 이름·별칭·컬렉션·설명·태그
구성	연결 설정(접속 정보), 커스텀 커넥터의 스크립트와 필수 패키지
사용 권한	(편집 시에만) 이 커넥터를 실행할 수 있는 사용자·그룹 관리

화면 하단에는 연결 테스트 / 취소 / 저장(또는 생성) 버튼이 있습니다.

기본 정보 탭

연결 방식과 기술 선택 (생성 시)

새 커넥터를 만들 때는 먼저 연결 방식을 고릅니다.

1. 지원 기술·관리형을 선택하면 드라이버 카탈로그에서 PostgreSQL 같은 기술을 고릅니다. 선택한 기술에 맞는 연결 폼이 표시되며 Python 스크립트는 작성하지 않습니다.
2. 커스텀을 선택하면 데이터베이스, 그래프, REST API, S3 스토리지, 벡터 DB 중 유형을 고릅니다. 연결 옵션과 Python 커넥터 스크립트를 직접 작성합니다.

사용자가 만든 관리형 연결은 생성 후 편집할 수 있습니다. 시스템이 설치하고 기본 제공 배지를 표시하는 읽기 전용 항목과는 다릅니다.

공통 정보

유형/템플릿을 선택하면 다음 메타데이터를 입력합니다.

필드	설명
커넥터 이름	시스템 식별자. 소문자로 시작하고 소문자·숫자·밑줄(_)만 사용(최대 128자). 생성 후에는 변경할 수 없습니다.
별칭	화면에 표시할 이름(선택). 비워 두면 이름과 동일하게 설정됩니다.
컬렉션	커넥터를 실행할 컬렉션 맥락(필수).
설명	연결 대상·용도·운영 주의사항 등 자유 텍스트.
태그	검색·분류용 태그.

이름을 먼저 입력하면 별칭·설명·태그 필드 오른쪽의 반짝임(✨) 아이콘이 활성화됩니다. 아이콘을 누르면 AI가 값을 제안합니다.

구성 탭 — 연결 설정

선택한 유형/템플릿에 맞는 연결 설정 폼이 표시됩니다.

데이터베이스 (온톨로지 저장소 · 데이터 허브)

• 호스트 / 포트: 접속 호스트와 포트(온톨로지 저장소 기본 5432, 데이터 허브 기본 8123)
• 데이터베이스: 데이터베이스 이름
• 사용자 이름 / 비밀번호: 인증 정보
• 보안 연결: (데이터 허브) 보안 연결 사용 여부 스위치

그래프 (그래프 저장소)

• URI: 접속 주소(예: bolt://graph.example.com:7687)
• 사용자 이름 / 비밀번호: 인증 정보

REST API

• 기본 URL에는 호출 대상 엔드포인트의 URL을 입력합니다. 이 항목은 필수이며 URL 형식을 검사합니다.
• 인증 쿼리 파라미터: 인증키를 실어 보낼 쿼리 파라미터 이름(선택). 공공 오픈데이터처럼 URL 쿼리로 인증키를 전달하는 API에 사용합니다(예: 공공데이터포털은 serviceKey, 기상청은 authKey). 커넥터 스크립트에서 직접 지정한다면 비워 둡니다.
• 서비스 키(인증키): 위 쿼리 파라미터로 전달할 인증키 값입니다. 비밀번호·키와 같은 시크릿으로 보관하며 저장 후에는 참조만 남고 값은 다시 표시하지 않습니다. 입력 방법은 시크릿 입력 방식에서 확인합니다.
• 타임아웃에는 호출 제한 시간을 밀리초 단위로 입력합니다.
• SSL 검증에서 SSL 인증서 검증 여부를 선택합니다.
• 콘솔 쓰기 허용은 기본으로 꺼져 있습니다. REST API 쿼리 콘솔에서 POST, PUT, PATCH, DELETE 요청을 실행해야 할 때만 켭니다.

S3 스토리지

• 엔드포인트 URL: S3 엔드포인트(예: https://s3.amazonaws.com)
• 액세스 키 / 시크릿 키: 자격 증명
• 리전 / 기본 버킷: 리전과 기본 버킷(선택)

벡터 DB (벡터 저장소)

• URL: 접속 주소(예: http://qdrant.example.com:6333, 필수·URL 형식 검증)
• API 키: 접근 인증 키(선택). 비밀번호·키처럼 시크릿으로 보관하며 저장 후에는 참조만 남고 값은 다시 표시하지 않습니다.
• 타임아웃 (ms): 호출 제한 시간(밀리초)

커스텀 데이터베이스·그래프는 JSON으로 입력

REST API·S3·벡터와 관리형 기술은 위와 같은 입력 폼을 제공합니다. 반면 커스텀 데이터베이스/그래프 커넥터는 정해진 폼이 없어, 연결 옵션을 JSON 에디터로 직접 입력합니다.

시크릿 입력 방식

비밀번호·액세스 키·시크릿 키·API 키·서비스 키 같은 시크릿은 두 가지 방식으로 입력합니다.

• 새 시크릿 입력: 값을 직접 입력합니다. 저장하면 커넥터 화면에는 참조 정보만 남고 값은 다시 표시하지 않습니다.
• 시크릿 참조 사용: 첫 번째 선택기에서 접근 가능한 시크릿을 고르고, 두 번째 선택기에서 그 시크릿의 키를 고릅니다. 화면이 선택 결과를 참조로 구성하므로 secret://... 경로를 직접 입력하지 않습니다. 커넥터에 컬렉션이 지정돼 있으면 그 컬렉션에서 사용할 수 있는 시크릿만 표시됩니다.

독립된 시크릿의 생성·키 교체·사용 권한 관리는 시크릿에서 확인합니다.

구성 탭 — 커스텀 커넥터 스크립트

커스텀 커넥터를 만들거나 편집할 때는, 연결 방법과 동작을 직접 코드로 작성하는 영역이 함께 나타납니다.

• 커넥터 스크립트: Python 코드를 에디터에서 작성합니다. 반드시 작성해야 하는 필수 함수 목록이 에디터 위에 안내되며, 필요한 함수는 커넥터 타입에 따라 달라집니다.
• 필수 패키지 (접힌 상태로 제공): 스크립트에서 사용하는 Python 패키지를 버전과 함께 추가합니다(예: psycopg2-binary>=3.0). 단, 여기 적은 패키지는 Docker 이미지를 만들 때 참고하는 목록일 뿐, 실행할 때 자동으로 설치되지는 않습니다.

저장과 연결 테스트

• 기존 자격 증명 유지: 편집 화면은 서버가 알려 준 설정 완료 상태와 기존 *_ref 참조 키를 기준으로 비밀번호·키 필드를 복원합니다. **이미 설정되어 있습니다. 비워두면 기존 시크릿이 유지되고, 새 값을 입력하면 교체됩니다.**라는 안내가 표시된 필드는 비워 둔 채 저장해도 기존 값이 유지됩니다.
• 자격 증명 교체: 새 시크릿 입력에서 새 값을 입력하거나 시크릿 참조 사용에서 다른 시크릿·키를 고르면 해당 자격 증명을 교체합니다. 저장된 원문은 편집 화면이나 API 응답에 다시 표시되지 않습니다.
• 연결 테스트: 현재 편집 화면에 입력한 연결 정보로 대상 시스템에 접속합니다. 기존 커넥터에 저장된 시크릿 참조를 유지한 경우에는 해당 참조를 사용합니다. 결과에는 성공 여부와 소요 시간이 표시됩니다.
• 읽기 전용·기본 제공 커넥터에서도 테스트: 연결 테스트는 편집·저장이 아닌 실행 권한을 따릅니다. 따라서 읽기 전용·기본 제공 커넥터의 편집 화면에서도 실행합니다. 기본 제공 커넥터는 관리자만, 사용자가 만든 관리형·커스텀 커넥터는 관리자 또는 매니저만 연결을 테스트할 수 있습니다.
• 저장 / 생성: 입력 검증을 통과하면 커넥터가 저장되고 목록으로 돌아갑니다. 검증 오류가 있으면 해당 항목이 있는 탭으로 자동 전환됩니다.

REST API 쿼리 콘솔

REST API 커넥터 카드의 작업 메뉴에서 쿼리 콘솔을 선택하거나 상세 화면의 쿼리 콘솔 탭을 엽니다. 관리자·매니저 역할과 해당 커넥터의 사용 권한이 모두 필요합니다.

스크린샷 TODO

영역: 메서드·상대 경로·파라미터·본문과 테이블/원문/헤더 결과 탭이 표시된 REST 쿼리 콘솔.

콘솔은 편집 화면의 저장하지 않은 값이 아니라 마지막으로 저장한 커넥터 설정과 자격 증명을 사용합니다. 설정을 바꿨다면 먼저 저장합니다.

읽기 요청 실행

1. GET 메서드를 선택하고 기본 URL 기준의 상대 경로를 입력합니다.
2. :name 형식의 경로 파라미터와 필요한 쿼리 파라미터를 입력합니다.
3. 행 제한을 1~10,000 사이로 입력합니다.
4. 완성된 요청 URL을 확인하거나 복사한 뒤 실행합니다.

쓰기 요청 실행

POST, PUT, PATCH, DELETE는 커넥터 설정에서 콘솔 쓰기 허용을 켠 경우에만 활성화됩니다. POST, PUT, PATCH에는 JSON 요청 본문을 입력할 수 있습니다. DELETE에는 본문 입력 절차를 적용하지 않습니다.

실행 전에 확인 창에 메서드와 전체 URL이 표시됩니다. 변경·삭제 영향을 확인한 뒤 실행합니다. 서버에서도 쓰기 허용 설정을 다시 검사합니다.

결과와 요청 기록 확인

• 상태 코드, 소요 시간, 행 수와 결과 잘림 여부를 확인합니다.
• 테이블 / 원문 / 헤더 탭을 전환합니다.
• HTTP 오류도 상태 코드·헤더·본문이 결과 영역에 표시됩니다.
• 성공한 요청의 메서드·경로·파라미터·본문·행 제한은 브라우저의 커넥터별 기록에 저장되며 다시 불러올 수 있습니다.

요청 기록에 민감한 값을 남기지 않습니다

인증 값은 저장된 시크릿을 사용합니다. 경로·쿼리 파라미터·JSON 본문에 비밀번호나 API 키를 직접 입력하면 브라우저 요청 기록에 남을 수 있습니다.

사용 권한 탭 (편집 시)

기존 커넥터의 사용 권한 탭에서 커넥터를 실행할 사용자·그룹을 관리합니다. 사용 권한과 소유자·편집자·뷰어 역할의 차이는 공유 권한의 사용 권한에서 확인합니다.

• 사용 권한 부여: 사용자나 그룹을 검색해 실행 권한을 추가합니다.
• 컬렉션 전제 조건: 컬렉션에 속한 커넥터를 실행하려면 대상이 해당 컬렉션의 소유자이거나 사용 권한을 가지고 있어야 합니다. 현재 계정이 컬렉션 권한을 관리할 수 있으면 포털이 상위 컬렉션의 사용 권한을 먼저 자동으로 부여합니다. 관리할 수 없으면 전제 조건이 충족된 대상에게만 커넥터 사용 권한을 부여합니다.

삭제

사용자가 만든 관리형·커스텀 커넥터는 목록 카드의 메뉴(⋮) → 삭제로 제거합니다. 삭제 메뉴는 관리자 또는 매니저에게만 표시됩니다. 기본 제공 커넥터는 삭제할 수 없습니다. 삭제를 선택하면 확인 창이 나타납니다.

커넥터 설정을 이전 상태로 되돌릴 때는 버전 기록에서 미리보기·복원 범위와 소비 화면 영향을 먼저 확인합니다.