S3 연결 구성

type: s3는 AWS S3 또는 s3a 프로토콜을 구현한 S3 호환 외부 시스템에 연결합니다. bucketUrl 끝에는 /가 필요합니다. 공개 AWS S3 버킷에는 인증 방식을 지정하지 않아도 됩니다.

이 API에서 connectionTimeoutMillis를 생략하면 10,000ms를 사용합니다. S3 소스 UI의 초기 설정값 50,000ms와 구분합니다. 다른 제한 시간과 연결 수의 기본값도 API 필드의 생략 조건을 따릅니다.

생성 입력의 필드

이름	자료형	필수 여부	의미와 조건	예시 값
`type`	`enum`	필수	분기를 구분하는 `type` 값입니다. 허용값: `s3`.	`s3`
`connectionTimeoutMillis`	`long`	선택	처음 연결을 맺을 때 기다리는 제한 시간이며 단위는 밀리초입니다. API에서 생략하면 10,000을 사용합니다.
`maxErrorRetry`	`integer`	선택	실패한 S3 요청의 최대 재시도 횟수입니다. 생략하면 3을 사용합니다.
`bucketUrl`	`string`	필수	S3 버킷 URL입니다. 끝에 `/`를 붙입니다.	`s3://my-test-bucket/`
`clientKmsConfiguration`	`object`	선택	S3 데이터를 암호화하고 복호화할 클라이언트 측 KMS 키입니다. KMS 구성을 생략하면 버킷의 기본 KMS 키를 사용합니다.
`matchSubfolderExactly`	`boolean`	선택	`true`이면 버킷 URL에 지정한 하위 폴더의 파일만 동기화합니다. 기본값은 `false`입니다. `false`에서는 지정한 하위 폴더 밖의 파일도 대상에 포함될 수 있으므로 동기화 전에 실제 선택 파일 범위를 확인합니다. 하위 폴더로 범위를 제한해야 한다면 `true`를 사용합니다.
`stsRoleConfiguration`	`object`	선택	S3에 연결하기 위해 역할을 맡는 STS 구성입니다.
`s3Endpoint`	`string`	선택	S3 서비스 엔드포인트입니다. AWS가 아닌 S3 호환 서비스의 사용자 지정 엔드포인트에도 사용합니다. 생략하면 AWS S3 엔드포인트를 사용합니다. `region`과 리전을 포함한 사용자 지정 엔드포인트를 함께 설정하면 예상과 다르게 동작할 수 있습니다.	`https://my-custom-s3-endpoint.com`
`socketTimeoutMillis`	`long`	선택	연결이 열린 뒤 데이터 전송을 기다리는 제한 시간이며 단위는 밀리초입니다. 생략하면 50,000을 사용합니다.
`enableRequesterPays`	`boolean`	선택	기본값은 `false`입니다. `true`이면 요청자 지불(Requester Pays) 헤더를 추가하여 해당 방식의 버킷을 읽을 수 있게 합니다.
`s3EndpointSigningRegion`	`string`	선택	사용자 지정 엔드포인트로 S3 클라이언트를 구성할 때 사용할 서명 리전입니다. 보통 필요하지 않지만 기본 리전과 다른 값을 요구하는 타사 S3 호환 API와 사용자 지정 엔드포인트를 사용할 때 지정할 수 있습니다.	`us-west-1`
`region`	`string`	선택	S3 버킷의 리전입니다. 리전을 포함한 사용자 지정 엔드포인트와 동시에 지정할 때는 조합을 확인합니다.	`us-west-1`
`authenticationMode`	`S3AuthenticationMode`	선택	S3 인증 방식입니다. 공개 접근이 가능한 AWS S3 버킷에는 인증 방식을 지정하지 않아도 됩니다.
`proxyConfiguration`	`object`	선택	프록시를 통해 S3에 연결하기 위한 구성입니다.
`maxConnections`	`integer`	선택	동기화 한 건에서 S3에 열 수 있는 최대 HTTP 연결 수입니다. 생략하면 50을 사용합니다.

`clientKmsConfiguration`의 구조

이름	자료형	필수 여부	의미와 조건	예시 값
`kmsKey`	`string`	필수	S3 데이터를 암호화하고 복호화할 클라이언트 측 KMS 키입니다. KMS 구성을 생략하면 버킷의 기본 KMS 키를 사용합니다.	`arn:aws:kms:us-west-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab`
`kmsRegion`	`string`	선택	클라이언트 측 KMS 키의 리전입니다. 생략하면 버킷의 기본 KMS 키 리전을 사용합니다.	`us-west-1`

`stsRoleConfiguration`의 구조

이름	자료형	필수 여부	의미와 조건	예시 값
`roleArn`	`string`	필수	맡을 역할의 Amazon Resource Name(ARN)입니다.	`arn:aws:iam::123456789012:role/my-role`
`roleSessionName`	`string`	필수	역할 세션의 식별자입니다. AWS 계정 안에서 고유하다고 판단할 수 있는 문자열을 사용합니다.
`roleSessionDuration`	`object`	선택	역할 세션의 수명입니다. 900초(15분) 이상이며 해당 역할에 설정한 최대 세션 수명 이하여야 합니다. 역할의 최대 세션 수명 설정은 1시간부터 12시간 사이입니다.
`externalId`	`string`	선택	타사 서비스가 고객 계정의 역할을 맡을 때 사용하는 고유한 외부 식별자입니다.
`stsEndpoint`	`string`	선택	기본 전역 STS 엔드포인트는 `https://sts.amazonaws.com`입니다. AWS는 지연 감소와 이중화, 세션 토큰 유효성 개선을 위해 리전별 STS 엔드포인트 사용을 권장합니다.	`https://sts.us-west-1.amazonaws.com`

`roleSessionDuration`의 구조

이름	자료형	필수 여부	의미와 조건	예시 값
`value`	`integer`	필수	기간의 수치입니다.	`900`
`unit`	`enum`	필수	기간의 단위입니다. 허용값: `MILLISECONDS`, `SECONDS`, `MINUTES`, `HOURS`, `DAYS`, `WEEKS`, `MONTHS`, `YEARS`.	`SECONDS`

`authenticationMode`의 구조

분기 `awsAccessKey`

IAM 사용자 또는 AWS 계정 루트 사용자의 장기 액세스 키입니다. 액세스 키 ID와 비밀 액세스 키를 함께 사용해야 합니다.

이름	자료형	필수 여부	의미와 조건	예시 값
`type`	`enum`	필수	분기를 구분하는 `type` 값입니다. 허용값: `awsAccessKey`.	`awsAccessKey`
`accessKeyId`	`string`	필수		`AKIAIOSFODNN7EXAMPLE`
`secretAccessKey`	`EncryptedProperty`	필수	조회 시에는 암호화된 값 대신 비밀 이름을 반환합니다. 쓸 때 평문 값을 전달하면 암호화하여 저장합니다. 비밀 이름을 전달하면 해당 속성의 기존 비밀 이름과 같아야 하며 기존 암호화 값을 유지합니다.

`secretAccessKey`의 구조

입력과 조회에서 사용하는 값의 차이 및 두 분기의 전체 구조는 암호화 속성을 따릅니다.

분기 `cloudIdentity`

클라우드 신원은 정적 자격 증명 없이 클라우드 제공자 리소스에 인증하는 방식입니다.

이름	자료형	필수 여부	의미와 조건	예시 값
`type`	`enum`	필수	분기를 구분하는 `type` 값입니다. 허용값: `cloudIdentity`.	`cloudIdentity`
`cloudIdentityRid`	`string`	필수	클라우드 신원의 RID입니다.	`ri.resource-policy-manager.global.cloud-identity.9dfdc25e-c506-4757-96d5-d22be70d596d`

분기 `oidc`

OIDC는 정적 자격 증명 없이 외부 시스템 리소스에 인증할 수 있는 개방형 인증 프로토콜입니다.

이름	자료형	필수 여부	의미와 조건	예시 값
`type`	`enum`	필수	분기를 구분하는 `type` 값입니다. 허용값: `oidc`.	`oidc`
`audience`	`string`	필수	외부 시스템을 식별하도록 구성한 audience입니다.	`sts.amazonaws.com`
`issuerUrl`	`string`	필수	Foundry를 OIDC 신원 제공자로 식별하는 URL입니다.	`https://pltroidcpublicexample.blob.store.com/foundry`
`subject`	`string`	필수	외부 시스템에 연결하는 Connection의 RID입니다.	`ri.magritte..source.c078b71b-92f9-41b6-b0df-3760f411120b`

`proxyConfiguration`의 구조

이름	자료형	필수 여부	의미와 조건	예시 값
`host`	`string`	필수	도메인 이름, IPv4 또는 IPv6 주소입니다. `protocol`과 `port`는 별도로 지정합니다.
`port`	`integer`	필수
`nonProxyHosts`	`list<string>`	선택	프록시를 우회할 호스트 목록입니다. STS 역할에 사용하는 호스트 등을 지정할 수 있으며 `*` 와일드카드도 지원합니다.
`protocol`	`enum`	선택	`HTTP` 또는 `HTTPS`를 사용하며 기본값은 `HTTPS`입니다. 허용값: `HTTP`, `HTTPS`.	`HTTP`
`credentials`	`object`	선택

`credentials`의 구조

이름	자료형	필수 여부	의미와 조건	예시 값
`username`	`string`	필수
`password`	`EncryptedProperty`	필수	조회 시에는 암호화된 값 대신 비밀 이름을 반환합니다. 쓸 때 평문 값을 전달하면 암호화하여 저장합니다. 비밀 이름을 전달하면 해당 속성의 기존 비밀 이름과 같아야 하며 기존 암호화 값을 유지합니다.

`password`의 구조

입력과 조회에서 사용하는 값의 차이 및 두 분기의 전체 구조는 암호화 속성을 따릅니다.

STS와 OIDC 설정

stsRoleConfiguration을 제공하면 roleArn과 roleSessionName이 필요합니다. 세션 수명은 900초 이상이며 역할에 설정한 상한 이하여야 합니다. 기간 단위의 enum에 여러 값이 있어도 이 범위 조건을 함께 충족해야 합니다.

OIDC의 audience, issuerUrl, subject는 모두 필수이며 subject는 해당 Connection의 RID입니다. 새 연결의 식별 값이 아직 없다면 S3 소스 화면의 OIDC 설정과 OIDC 신뢰 관계를 따라 구성합니다. Foundry가 제공한 값을 확인한 뒤 원천 시스템의 신뢰 조건에 사용합니다.

필드 값 예시

다음 값은 지정한 필드에 넣는 가상 입력 구조입니다. 전체 연결 생성 요청과 구분하고, 실제 호스트와 역할, 자격 증명 및 드라이버가 지원하는 속성으로 바꿉니다.

`s3.clientKmsConfiguration`

{
  "kmsRegion": "us-west-1",
  "kmsKey": "arn:aws:kms:us-west-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}

`s3.stsRoleConfiguration`

{
  "stsEndpoint": "https://sts.us-west-1.amazonaws.com",
  "roleArn": "arn:aws:iam::123456789012:role/my-role",
  "roleSessionDuration": {
    "unit": "SECONDS",
    "value": 900
  },
  "roleSessionName": "foundry-example-session"
}

`s3.proxyConfiguration`

{
  "protocol": "HTTP",
  "credentials": {
    "password": {
      "type": "asPlaintextValue",
      "value": "myPlaintextSecret"
    },
    "username": "example-user"
  },
  "host": "proxy.example.com",
  "port": 8080
}

Keyboard shortcuts

팔란티어 플랫폼 한국어 해설