Connection 구성과 관리 API (V2)
Connection은 Foundry와 외부 시스템 또는 API 사이의 연결을 정의하는 리소스이며, Data Connection에서는 소스라고도 부릅니다. 연결은 외부 시스템의 주소와 인증, 연산을 수행할 워커, 내보내기 설정을 담습니다. 원천 데이터의 가져오기 작업과 연결 자체의 구성은 구분합니다.
연결 관리 작업
| 작업 | API |
|---|---|
| 직접 연결 런타임의 새 소스 생성 | Create Connection |
| 연결 메타데이터와 구성 조회 | Get Connection |
| 외부 시스템 구성만 조회 | Get Configuration |
| 최대 200개 연결의 구성 조회 | Get Configuration Connections Batch |
| 내보내기 허용과 표지 검증 설정 변경 | Update Export Settings For Connection |
| 기존 비밀값 변경 | Update Secrets For Connection |
| 기존 JDBC 연결에 JAR 업로드 | Upload Custom JDBC Drivers Connection |
조회에는 api:connectivity-connection-read, 생성과 변경에는 api:connectivity-connection-write OAuth 권한 범위를 사용합니다. 내보내기 설정 변경에는 Information Security Officer 역할 조건도 적용됩니다. 배치 조회는 POST이지만 연결을 변경하지 않습니다.
Connection 자료형
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
rid | string | 필수 | 소스라고도 부르는 Connection의 RID입니다. | ri.magritte..source.c078b71b-92f9-41b6-b0df-3760f411120b |
parentFolderRid | string | 필수 | 폴더의 고유 리소스 식별자(RID)입니다. | ri.compass.main.folder.c410f510-2937-420e-8ea3-8c9bcb3c1791 |
displayName | string | 필수 | 연결의 표시 이름이며 비워 둘 수 없습니다. | Connection to my external system |
exportSettings | object | 필수 | 연결의 내보내기 설정입니다. | 응답 예시 참조 |
worker | union<unknownWorker, foundryWorker> | 필수 | 연결 기능의 연산을 실행할 위치를 정하는 워커입니다. | |
configuration | union<s3, rest, snowflake, databricks, smb, jdbc> | 필수 | 응답 예시 참조 |
exportSettings의 구조
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
exportsEnabled | boolean | 필수 | Foundry 데이터셋을 이 연결로 내보낼 수 있게 합니다. | true |
exportEnabledWithoutMarkingsValidation | boolean | 필수 | 일부 대화형 작업에서는 내보낼 데이터의 보안 표지를 검증할 수 없습니다. 표지 검증 없이 내보내기를 허용하면 내보내는 데이터가 조직 정책을 준수하는지 확인할 책임을 수용하는 조건이 적용됩니다. | false |
worker의 구조
분기 unknownWorker
Platform API에서 지원하지 않는 워커입니다. 구성이 잘못되었거나 Legacy 워커인 경우에 나타날 수 있습니다. 직접 연결 정책 또는 에이전트 프록시 정책을 사용하는 Foundry 워커로 전환합니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
type | enum | 필수 | 분기를 구분하는 type 값입니다. 허용값: unknownWorker. | unknownWorker |
분기 foundryWorker
Foundry의 컨테이너화된 확장 가능한 실행 환경에서 연결 기능을 수행하는 권장 워커입니다. 별도의 연산 에이전트를 유지관리하지 않고 Foundry의 실행 인프라를 사용합니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
type | enum | 필수 | 분기를 구분하는 type 값입니다. 허용값: foundryWorker. | foundryWorker |
networkEgressPolicyRids | list<NetworkEgressPolicyRid> | 선택 |
networkEgressPolicyRids의 구조
배열 항목은 NetworkEgressPolicyRid이며 자료형은 string입니다.
외부 통신 정책의 RID입니다.
configuration의 구조
연결 유형별 생성 입력과 조회 결과의 전체 필드는 연결 구성 자료형을 따릅니다. 암호화 속성은 조회 시 비밀 이름을 반환하며, 생성 입력과 조회 결과가 다른 필드는 해당 연결 유형에서 구분합니다.
워커와 외부 통신
워커는 연결 기능을 실행할 위치입니다. 새 연결을 만들 때는 foundryWorker를 사용합니다. networkEgressPolicyRids로 대상 시스템에 맞는 외부 통신 정책을 지정하며 실제 네트워크와 원천 시스템의 접근 조건도 갖추어야 합니다.
조회 결과의 unknownWorker는 Platform API가 지원하지 않는 워커 구성을 나타냅니다. 잘못된 구성이나 Legacy 워커가 원인일 수 있으므로 이 값만으로 워커 종류를 단정하지 않습니다. 생성이나 갱신 요청의 워커 값으로는 사용할 수 없습니다. 기존 에이전트 워커의 지원과 전환 경로는 워커 구분을 따릅니다.
비밀값의 조회와 변경
암호화 속성을 읽으면 평문 대신 비밀 이름이 반환됩니다. 이름으로 값을 유지할 때는 해당 속성의 기존 이름과 같아야 하며, 새 값을 저장하려면 평문 입력 형태를 사용합니다. 전체 구조와 일시적 서버 메모리 처리 조건은 암호화 속성에 있습니다.
Update Secrets는 이미 존재하는 이름의 값만 바꿉니다. 요청에서 빠진 비밀은 유지합니다. REST의 추가 비밀 입력, 생성 요청의 암호화 속성과 비밀 갱신 본문은 서로 다른 JSON 형태이므로 구분합니다.
연결 예시
가상 JDBC 연결입니다. 아래 내보내기 값은 예시 구성으로, 새 연결의 기본 허용값을 나타내지 않습니다.
{
"parentFolderRid": "ri.compass.main.folder.c410f510-2937-420e-8ea3-8c9bcb3c1791",
"configuration": {
"type": "jdbc",
"url": "jdbc:postgresql://db.example.com:5432/example",
"driverClass": "org.postgresql.Driver"
},
"displayName": "Connection to my external system",
"exportSettings": {
"exportsEnabled": true,
"exportEnabledWithoutMarkingsValidation": false
},
"rid": "ri.magritte..source.c078b71b-92f9-41b6-b0df-3760f411120b",
"worker": {
"type": "foundryWorker"
}
}