# PostgreSQL DB 인스턴스용 Aurora PostgreSQL DB 클러스터
Amazon Simple Storage Service를 사용하여 저장된 데이터를 RDS for PostgreSQL DB 인스턴스의 테이블로 가져올 수 있습니다. 이 작업을 수행하려면 먼저 Aurora PostgreSQL `aws_s3` 확장을 설치해야 합니다. 이 확장은 Amazon S3 버킷에서 데이터를 가져오는 데 사용하는 기능을 제공합니다. *버킷*은 객체 또는 파일에 대한 Amazon S3 컨테이너입니다. 데이터는 쉼표로 구분된 값 (CSV) 파일, 텍스트 파일 또는 압축 (gzip) 파일에 있을 수 있습니다. 다음에서는 확장 프로그램을 설치하는 방법과 Amazon S3에서 테이블로 데이터를 가져오는 방법을 알아볼 수 있습니다.
Amazon S3를 로 가져오려면 데이터베이스에서 PostgreSQL 버전 10.7 이상을 실행 중이어야 합니다. Aurora PostgreSQL.
Amazon S3 데이터가 저장되지 않은 경우 먼저 버킷을 생성하고 데이터를 저장해야 합니다. 자세한 내용은 *Amazon Simple Storage Service 사용 설명서*의 다음 주제를 참조하세요.
+ [버킷 생성](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html#creating-bucket)
+ [버킷에 객체 추가](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html#uploading-an-object-bucket)
Amazon S3에서 계정 간 가져오기가 지원됩니다. 자세한 내용은 **Amazon Simple Storage Service 사용 설명서의 [계정 간 권한 부여](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-walkthroughs-managing-access-example2.html)를 참조하세요.
S3에서 데이터를 가져오는 동안 고객 관리형 키를 암호화에 사용할 수 있습니다. 자세한 내용은 **Amazon Simple Storage Service 사용 설명서의 [AWS KMS에 저장된 KMS 키](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html)를 참조하세요.
**참고**
Amazon S3에서 데이터를 가져오는 작업은 Aurora Serverless v1에서 지원되지 않습니다. Aurora Serverless v2에서는 지원됩니다.
**Topics**
+ [aws\$1s3 확장 설치](USER_PostgreSQL.S3Import.InstallExtension.md)
+ [Amazon S3 데이터에서 데이터 가져오기 개요](USER_PostgreSQL.S3Import.Overview.md)
+ [Amazon S3 버킷에 대한 액세스 권한 설정](USER_PostgreSQL.S3Import.AccessPermission.md)
+ [Amazon S3에서 Aurora PostgreSQL DB 클러스터 로 데이터 가져오기](USER_PostgreSQL.S3Import.FileFormats.md)
+ [함수 참조](USER_PostgreSQL.S3Import.Reference.md)
# aws\$1s3 확장 설치
Amazon S3를 Aurora PostgreSQL DB 클러스터 와 함께 사용하려면 먼저 `aws_s3` 확장을 설치해야 합니다. 이 확장은 Amazon S3에서 데이터를 가져오기 위한 함수도 제공합니다. 또한 Aurora PostgreSQL DB 클러스터의 인스턴스에서 Amazon S3 버킷으로 데이터를 내보내는 기능도 제공합니다. 자세한 내용은 [Aurora PostgreSQL DB 클러스터에서 Amazon S3로 데이터 내보내기](postgresql-s3-export.md) 단원을 참조하세요. `aws_s3` 확장은 필요할 때 자동으로 설치되는 `aws_commons` 확장의 일부 도우미 기능에 따라 다릅니다.
**`aws_s3` 확장을 설치하려면**
1. psql(또는 PGAdmin)을 사용하여 Aurora PostgreSQL DB 클러스터의 라이터 인스턴스에 `rds_superuser` 권한을 가진 사용자로 연결합니다. 설정 과정에서 기본 이름을 계속 사용했다면 `postgres`로 연결합니다.
```
psql --host=111122223333.aws-region.rds.amazonaws.com --port=5432 --username=postgres --password
```
1. 다음 명령을 실행하여 확장을 생성합니다.
```
postgres=> CREATE EXTENSION aws_s3 CASCADE;
NOTICE: installing required extension "aws_commons"
CREATE EXTENSION
```
1. 확장 프로그램이 설치되었는지 확인하려면 psql `\dx` 메타 명령을 사용하면 됩니다.
```
postgres=> \dx
List of installed extensions
Name | Version | Schema | Description
-------------+---------+------------+---------------------------------------------
aws_commons | 1.2 | public | Common data types across AWS services
aws_s3 | 1.1 | public | AWS S3 extension for importing data from S3
plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
(3 rows)
```
이제 Amazon S3에서 데이터를 가져오고 Amazon S3로 데이터를 내보내는 기능을 사용할 수 있습니다.
# Amazon S3 데이터에서 데이터 가져오기 개요
**S3 데이터를 Aurora PostgreSQL 로 가져오려면**
먼저 함수에 제공해야 하는 세부 정보를 수집합니다. 여기에는 Aurora PostgreSQL DB 클러스터 인스턴스의 테이블 이름과 버킷 이름, 파일 경로, 파일 유형 및 Amazon S3 데이터가 저장된 AWS 리전이 포함됩니다. 자세한 내용은 *Amazon Simple Storage Service 사용 설명서*의 [객체 보기](https://docs.aws.amazon.com/AmazonS3/latest/userguide/OpeningAnObject.html)를 참조하세요.
**참고**
Amazon S3에서 멀티 파트 데이터 가져오기는 현재 지원되지 않습니다.
1. `aws_s3.table_import_from_s3` 함수가 데이터를 가져올 테이블의 이름을 가져옵니다. 예를 들어 다음 명령은 이후 단계에서 사용할 수 있는 테이블 `t1`을 만듭니다.
```
postgres=> CREATE TABLE t1
(col1 varchar(80),
col2 varchar(80),
col3 varchar(80));
```
1. Amazon S3 버킷 및 가져올 데이터에 대한 세부 정보를 가져옵니다. 이 작업을 수행하려면 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)에서 Amazon S3 콘손을 열고 **버킷**을 선택합니다. 목록에서 데이터가 포함된 버킷을 찾습니다. 버킷을 선택하고 객체 개요 페이지를 연 다음 속성을 선택합니다.
버킷 이름, 경로, AWS 리전, 파일 형식을 적어 둡니다. IAM 역할을 통해 Amazon S3에 대한 액세스를 설정하는 Amazon 리소스 이름(ARN) 이 나중에 필요합니다. 자세한 내용은 [Amazon S3 버킷에 대한 액세스 권한 설정](USER_PostgreSQL.S3Import.AccessPermission.md) 단원을 참조하세요. 다음 그림에 예가 나와 있습니다.
![\[Amazon S3 버킷에 있는 파일 객체의 이미지입니다.\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/images/aws_s3_import-export_s3_bucket-info.png)
1. AWS CLI 명령 `aws s3 cp`를 사용하여 Amazon S3 버킷의 데이터 경로를 확인할 수 있습니다. 정보가 정확하면 이 명령이 Amazon S3 파일의 복사본을 다운로드합니다.
```
aws s3 cp s3://amzn-s3-demo-bucket/sample_file_path ./
```
1. Amazon S3 버킷의 파일에 대한 액세스를 허용하도록 Aurora PostgreSQL DB 클러스터에 대한 권한을 설정합니다. 이렇게 하려면 AWS Identity and Access Management(IAM) 역할 또는 보안 자격 증명을 사용합니다. 자세한 내용은 [Amazon S3 버킷에 대한 액세스 권한 설정](USER_PostgreSQL.S3Import.AccessPermission.md) 단원을 참조하세요.
1. 경로 및 수집된 기타 Amazon S3 객체 세부 정보(2단계 참조)를 `create_s3_uri` 함수에 제공하여 Amazon S3 URI 객체를 생성합니다. 이 함수에 대한 자세한 내용은 [aws\$1commons.create\$1s3\$1uri](USER_PostgreSQL.S3Import.Reference.md#USER_PostgreSQL.S3Import.create_s3_uri) 단원을 참조하세요. 다음은 psql 세션 중에 이 객체를 구성하는 예입니다.
```
postgres=> SELECT aws_commons.create_s3_uri(
'docs-lab-store-for-rpg',
'versions_and_jdks_listing.csv',
'us-west-1'
) AS s3_uri \gset
```
다음 단계에서는 이 객체(`aws_commons._s3_uri_1`)를 `aws_s3.table_import_from_s3` 함수에 전달하여 데이터를 테이블로 가져옵니다.
1. `aws_s3.table_import_from_s3` 함수를 호출하여 Amazon S3에서 테이블로 데이터를 가져옵니다. 참조 정보는 [aws\$1s3.table\$1import\$1from\$1s3](USER_PostgreSQL.S3Import.Reference.md#aws_s3.table_import_from_s3) 단원을 참조하세요. 예시는 [Amazon S3에서 Aurora PostgreSQL DB 클러스터 로 데이터 가져오기](USER_PostgreSQL.S3Import.FileFormats.md) 섹션을 참조하세요.
# Amazon S3 버킷에 대한 액세스 권한 설정
Amazon S3 파일에서 데이터를 가져오려면 Aurora PostgreSQL DB 클러스터에 파일이 저장된 Amazon S3 버킷에 액세스할 수 있는 권한을 부여합니다. 다음 항목에서 설명하는 두 방법 중 하나를 사용하여 Amazon S3 버킷에 대한 액세스 권한을 부여합니다.
**Topics**
+ [IAM 역할을 사용해 Amazon S3 버킷에 액세스](#USER_PostgreSQL.S3Import.ARNRole)
+ [보안 자격 증명을 사용해 Amazon S3 버킷에 액세스](#USER_PostgreSQL.S3Import.Credentials)
+ [Amazon S3 액세스 문제 해결](#USER_PostgreSQL.S3Import.troubleshooting)
## IAM 역할을 사용해 Amazon S3 버킷에 액세스
Amazon S3 파일에서 데이터를 로드하기 전에 Aurora PostgreSQL DB 클러스터DB 클러스터에 파일이 저장된 Amazon S3 버킷에 액세스할 수 있는 권한을 부여합니다. 그러면 추가 자격 증명 정보를 관리하거나 [aws\$1s3.table\$1import\$1from\$1s3](USER_PostgreSQL.S3Import.Reference.md#aws_s3.table_import_from_s3) 함수 호출에서 제공할 필요가 없습니다.
이렇게 하려면 Amazon S3 버킷에 대한 액세스 권한을 부여하는 IAM 정책을 생성합니다. IAM 역할을 생성하여 정책을 역할에 연결합니다. 그런 다음 IAM 역할을 DB 클러스터에 할당합니다.
**참고**
IAM 역할을 Aurora Serverless v1 DB 클러스터와 연결할 수 없으므로 다음 단계에 적용되지 않습니다.
**IAM 역할을 통해 Amazon S3에 액세스할 수 있는 권한을 PostgreSQL DB 인스턴스용 Aurora PostgreSQL DB 클러스터 에 부여하려면**
1. IAM 정책을 생성합니다.
이 정책은 Aurora PostgreSQL DB 클러스터 가 Amazon S3에 액세스할 수 있도록 허용하는 버킷 및 객체 권한을 부여합니다.
정책에 다음과 같은 필수 작업을 포함하여 Amazon S3 버킷에서 Aurora PostgreSQL로의 파일 전송을 허용합니다.
+ `s3:GetObject`
+ `s3:ListBucket`
정책에 다음 리소스를 포함하여 Amazon S3 버킷 및 그 안의 객체를 식별합니다. 다음은 Amazon S3에 액세스하기 위한 Amazon 리소스 이름(ARN) 형색입니다.
+ arn:aws:s3:::*amzn-s3-demo-bucket*
+ arn:aws:s3:::*amzn-s3-demo-bucket*/\$1
Aurora PostgreSQL용 IAM 정책 생성에 대한 자세한 내용은 [IAM 데이터베이스 액세스를 위한 IAM 정책 생성 및 사용](UsingWithRDS.IAMDBAuth.IAMPolicy.md) 섹션을 참조하세요. *IAM 사용 설명서*의 [자습서: 첫 번째 고객 관리형 정책 생성 및 연결](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_managed-policies.html)도 참조하세요.
다음 AWS CLI 명령은 이 옵션으로 `rds-s3-import-policy`라는 IAM 정책을 만듭니다. *amzn-s3-demo-bucket*이라는 버킷에 대한 액세스 권한을 부여합니다.
**참고**
이 명령에서 반환되는 정책 Amazon 리소스 이름(ARN)을 적어 둡니다. IAM 역할에 정책을 연결할 때 이후 단계에 ARN이 필요합니다.
**Example**
대상 LinuxmacOS, 또는Unix:
```
aws iam create-policy \
--policy-name rds-s3-import-policy \
--policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "s3import",
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
}
]
}'
```
Windows의 경우:
```
aws iam create-policy ^
--policy-name rds-s3-import-policy ^
--policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "s3import",
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
}
]
}'
```
1. IAM 역할을 생성합니다.
이렇게 하면, Aurora PostgreSQL에서 IAM 역할을 수임하여 사용자 대신 Amazon S3 버킷에 액세스할 수 있도록 역할을 생성할 수 있습니다. 자세한 내용은 *IAM 사용 설명서*의 [IAM 사용자에게 권한을 위임하기 위한 역할 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html)을 참조하세요.
서비스 권한을 특정 리소스로 제한하는 리소스 기반 정책의 `[aws:SourceArn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn)` 및 `[aws:SourceAccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount)` 전역 조건 컨텍스트 키를 사용하는 것이 좋습니다. 이는 [혼동된 대리자 문제](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)를 방지하는 가장 효과적인 방법입니다.
두 전역 조건 컨텍스트 키와 계정 ID를 포함한 `aws:SourceArn` 값을 모두 사용하는 경우, `aws:SourceAccount` 값 및 `aws:SourceArn` 값의 계정은 동일한 정책 문에서 사용될 경우 반드시 같은 계정 ID를 사용해야 합니다.
+ 단일 리소스에 대한 교차 서비스 액세스를 원하는 경우 `aws:SourceArn`을 사용하세요.
+ 해당 계정의 모든 리소스가 교차 서비스 사용과 연결되도록 허용하려는 경우 `aws:SourceAccount`를 사용하세요.
정책에서는 리소스의 전체 ARN이 포함된 `aws:SourceArn` 전역 조건 컨텍스트 키를 사용해야 합니다. 다음 예제에서는 AWS CLI 명령을 사용하여 `rds-s3-import-role`이라는 역할을 생성하는 방법을 보여줍니다.
**Example**
대상 LinuxmacOS, 또는Unix:
```
aws iam create-role \
--role-name rds-s3-import-role \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "rds.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333",
"aws:SourceArn": "arn:aws:rds:us-east-1:111122223333:cluster:clustername"
}
}
}
]
}'
```
Windows의 경우:
```
aws iam create-role ^
--role-name rds-s3-import-role ^
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "rds.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333",
"aws:SourceArn": "arn:aws:rds:us-east-1:111122223333:cluster:clustername"
}
}
}
]
}'
```
1. 생성한 IAM 역할에 생성한 IAM 정책을 연결합니다.
다음 AWS CLI 명령은 앞서 생성한 정책을 `rds-s3-import-role`이라는 역할에 연결합니다. `your-policy-arn`을 이전 단계에서 기록한 정책 ARN으로 바꿉니다.
**Example**
대상 LinuxmacOS, 또는Unix:
```
aws iam attach-role-policy \
--policy-arn your-policy-arn \
--role-name rds-s3-import-role
```
Windows의 경우:
```
aws iam attach-role-policy ^
--policy-arn your-policy-arn ^
--role-name rds-s3-import-role
```
1. IAM 역할을 DB 클러스터에 추가합니다.
이렇게 하려면 다음에 설명한 대로 AWS Management Console 또는 AWS CLI를 사용합니다.
### 콘솔
**콘솔을 사용하여 PostgreSQL DB 클러스터에 대해 IAM 역할을 추가하려면**
1. AWS Management Console에 로그인한 후 [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/)에서 Amazon RDS 콘솔을 엽니다.
1. 세부 정보를 표시하고자 하는 PostgreSQL DB 클러스터 이름을 선택합니다.
1. **연결성 및 보안(Connectivity & security)** 탭에 있는 **IAM 역할 관리(Manage IAM roles)** 섹션의 **이 클러스터에 IAM 역할 추가(Add IAM roles to this cluster/instance)**에서 추가할 역할을 선택합니다.
1. **기능**에서 **s3Import**를 선택합니다.
1. [**Add role**]을 선택합니다.
### AWS CLI
**CLI를 사용하여 PostgreSQL DB 클러스터에 대해 IAM 역할을 추가하려면**
+ 다음 명령을 사용해 `my-db-cluster`라는 PostgreSQL DB 클러스터에 역할을 추가합니다. *`your-role-arn`*을 이전 단계에서 기록한 정책 ARN으로 교체합니다. `s3Import` 옵션의 값에 대해 `--feature-name`를 사용합니다.
**Example**
대상 LinuxmacOS, 또는Unix:
```
aws rds add-role-to-db-cluster \
--db-cluster-identifier my-db-cluster \
--feature-name s3Import \
--role-arn your-role-arn \
--region your-region
```
Windows의 경우:
```
aws rds add-role-to-db-cluster ^
--db-cluster-identifier my-db-cluster ^
--feature-name s3Import ^
--role-arn your-role-arn ^
--region your-region
```
### RDS API
Amazon RDS API를 사용하여 PostgreSQL DB 클러스터에 대한 IAM 역할을 추가하려면 [AddRoleToDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_AddRoleToDBCluster.html) 작업을 직접적으로 호출합니다.
## 보안 자격 증명을 사용해 Amazon S3 버킷에 액세스
원할 경우 IAM 역할을 사용하는 대신 보안 자격 증명을 사용해 Amazon S3 버킷에 대한 액세스 권한을 부여여할 수 있습니다. [aws\$1s3.table\$1import\$1from\$1s3](USER_PostgreSQL.S3Import.Reference.md#aws_s3.table_import_from_s3) 함수 호출에서 `credentials` 파라미터를 지정하면 됩니다.
`credentials` 파라미터는 `aws_commons._aws_credentials_1` 자격 증명을 포함하는 AWS 유형의 구조입니다. 다음과 같이 [aws\$1commons.create\$1aws\$1credentials](USER_PostgreSQL.S3Import.Reference.md#USER_PostgreSQL.S3Import.create_aws_credentials) 함수를 사용해 `aws_commons._aws_credentials_1` 구조에서 액세스 키와 비밀 키를 설정하십시오.
```
postgres=> SELECT aws_commons.create_aws_credentials(
'sample_access_key', 'sample_secret_key', '')
AS creds \gset
```
다음과 같이 `aws_commons._aws_credentials_1 ` 구조를 생성한 후 [aws\$1s3.table\$1import\$1from\$1s3](USER_PostgreSQL.S3Import.Reference.md#aws_s3.table_import_from_s3) 함수를 `credentials` 파라미터와 함께 사용해 데이터를 가져옵니다.
```
postgres=> SELECT aws_s3.table_import_from_s3(
't', '', '(format csv)',
:'s3_uri',
:'creds'
);
```
또는 [aws\$1commons.create\$1aws\$1credentials](USER_PostgreSQL.S3Import.Reference.md#USER_PostgreSQL.S3Import.create_aws_credentials) 함수 호출 인라인을 `aws_s3.table_import_from_s3` 함수 호출에 포함할 수 있습니다.
```
postgres=> SELECT aws_s3.table_import_from_s3(
't', '', '(format csv)',
:'s3_uri',
aws_commons.create_aws_credentials('sample_access_key', 'sample_secret_key', '')
);
```
## Amazon S3 액세스 문제 해결
Amazon S3 파일 데이터를 가져오려 할 때 연결 문제가 발생할 경우 다음 권장 사항을 참조하세요.
+ [Amazon Aurora 자격 증명 및 액세스 문제 해결](security_iam_troubleshoot.md)
+ [Amazon Simple Storage Service 사용 설명서](https://docs.aws.amazon.com/AmazonS3/latest/userguide/troubleshooting.html)의 *Amazon S3 문제 해결*
+ *IAM 사용 설명서*의 [Amazon S3 문제 해결 및 IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_iam-s3.html)
# Amazon S3에서 Aurora PostgreSQL DB 클러스터 로 데이터 가져오기
aws\$1s3 확장의 `table_import_from_s3` 함수를 사용하여 Amazon S3 버킷에서 데이터를 가져옵니다. 참조 정보는 [aws\$1s3.table\$1import\$1from\$1s3](USER_PostgreSQL.S3Import.Reference.md#aws_s3.table_import_from_s3) 단원을 참조하세요.
**참고**
다음 예에서는 Amazon S3 버킷에 대한 액세스 권한을 허용하기 위해 IAM 역할 메서드를 사용합니다. 따라서 `aws_s3.table_import_from_s3` 함수 호출에는 자격 증명 파라미터가 포함되지 않습니다.
다음은 대표적인 예를 보여줍니다.
```
postgres=> SELECT aws_s3.table_import_from_s3(
't1',
'',
'(format csv)',
:'s3_uri'
);
```
파라미터는 다음과 같습니다.
+ `t1` – 데이터를 복사할 PostgreSQL DB 클러스터의 테이블에 지정된 이름입니다.
+ `''` – 데이터베이스 테이블의 열 목록입니다(선택 사항). 이 파라미터를 사용해 S3 데이터 중 어떤 열이 어떤 테이블 열에 들어가는지 표시할 수 있습니다. 열을 지정하지 않으면 모든 열이 테이블에 복사됩니다. 열 목록 사용에 대한 예시는 [사용자 지정 구분 기호를 사용하는 Amazon S3 파일 가져오기](#USER_PostgreSQL.S3Import.FileFormats.CustomDelimiter) 단원을 참조하십시오.
+ `(format csv)` – PostgreSQL COPY 인수입니다. 복사 프로세스에서는 [PostgreSQL COPY](https://www.postgresql.org/docs/current/sql-copy.html) 명령의 인수와 형식을 사용하여 데이터를 가져옵니다. 형식에 대한 선택 사항에는 이 예에 표시된 대로 쉼표로 구분된 값(CSV), 텍스트 및 이진법이 있습니다. 기본값은 텍스트입니다.
+ `s3_uri` – Amazon S3 파일을 식별하는 정보가 포함된 구조입니다. [aws\$1commons.create\$1s3\$1uri](USER_PostgreSQL.S3Import.Reference.md#USER_PostgreSQL.S3Import.create_s3_uri) 함수를 사용하여 `s3_uri` 구조를 생성하는 예제는 [Amazon S3 데이터에서 데이터 가져오기 개요](USER_PostgreSQL.S3Import.Overview.md) 단원을 참조하세요.
이 함수에 대한 자세한 내용은 [aws\$1s3.table\$1import\$1from\$1s3](USER_PostgreSQL.S3Import.Reference.md#aws_s3.table_import_from_s3) 단원을 참조하세요.
이 `aws_s3.table_import_from_s3` 함수는 문자를 반환합니다. Amazon S3 버킷에서 가져올 다른 파일 종류를 지정하려면 다음 예 중 하나를 참조하세요.
**참고**
0바이트 파일을 가져오면 오류가 발생합니다.
**Topics**
+ [사용자 지정 구분 기호를 사용하는 Amazon S3 파일 가져오기](#USER_PostgreSQL.S3Import.FileFormats.CustomDelimiter)
+ [Amazon S3 압축(gzip) 파일 가져오기](#USER_PostgreSQL.S3Import.FileFormats.gzip)
+ [인코딩된 Amazon S3 파일 가져오기](#USER_PostgreSQL.S3Import.FileFormats.Encoded)
## 사용자 지정 구분 기호를 사용하는 Amazon S3 파일 가져오기
다음 예제에서는 사용자 지정 구분 기호를 사용하는 파일을 가져오는 방법을 보여줍니다. 또한 `column_list` 함수의 [aws\$1s3.table\$1import\$1from\$1s3](USER_PostgreSQL.S3Import.Reference.md#aws_s3.table_import_from_s3) 파라미터를 사용해 데이터베이스 테이블에서 데이터를 배치할 곳을 제어하는 방법을 보여줍니다.
이 예에서는 다음 정보가 Amazon S3 파일의 파이프로 구분된 열에 정리되어 있다고 가정합니다.
```
1|foo1|bar1|elephant1
2|foo2|bar2|elephant2
3|foo3|bar3|elephant3
4|foo4|bar4|elephant4
...
```
**사용자 지정 구분 기호를 사용하는 파일을 가져오려면**
1. 가져온 데이터에 대해 데이터베이스에서 테이블을 생성합니다.
```
postgres=> CREATE TABLE test (a text, b text, c text, d text, e text);
```
1. [aws\$1s3.table\$1import\$1from\$1s3](USER_PostgreSQL.S3Import.Reference.md#aws_s3.table_import_from_s3) 함수의 다음과 같은 형식을 사용해 Amazon S3 파일에서 데이터를 가져옵니다.
[aws\$1commons.create\$1s3\$1uri](USER_PostgreSQL.S3Import.Reference.md#USER_PostgreSQL.S3Import.create_s3_uri) 함수 호출 인라인을 `aws_s3.table_import_from_s3` 함수 호출에 포함하여 파일을 지정할 수 있습니다.
```
postgres=> SELECT aws_s3.table_import_from_s3(
'test',
'a,b,d,e',
'DELIMITER ''|''',
aws_commons.create_s3_uri('amzn-s3-demo-bucket', 'pipeDelimitedSampleFile', 'us-east-2')
);
```
이제 데이터는 다음 열의 테이블에 있습니다.
```
postgres=> SELECT * FROM test;
a | b | c | d | e
---+------+---+---+------+-----------
1 | foo1 | | bar1 | elephant1
2 | foo2 | | bar2 | elephant2
3 | foo3 | | bar3 | elephant3
4 | foo4 | | bar4 | elephant4
```
## Amazon S3 압축(gzip) 파일 가져오기
다음 예에서는 gzip으로 압축된 Amazon S3에서 파일을 가져오는 방법을 보여줍니다. 가져오는 파일에 다음과 같은 Amazon S3 메타데이터가 있어야 합니다.
+ 키: `Content-Encoding`
+ 값: `gzip`
AWS Management Console을 사용하여 파일을 업로드하는 경우 일반적으로 시스템에서 메타데이터를 적용합니다. AWS Management Console, AWS CLI 또는 API를 사용하여 Amazon S3에 파일을 업로드하는 방법에 대한 자세한 내용은 *Amazon Simple Storage Service 사용 설명서*의 [객체 업로드](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html)를 참조하세요.
Amazon S3 메타데이터에 대한 자세한 내용과 시스템 제공 메타데이터에 대한 세부 정보는 *Amazon Simple Storage Service 사용 설명서*의 [Amazon S3 콘솔에서 객체 메타데이터 편집](https://docs.aws.amazon.com/AmazonS3/latest/userguide/add-object-metadata.html)을 참조하세요.
아래와 같이 gzip 파일을 PostgreSQL DB 인스턴스용 Aurora PostgreSQL DB 클러스터로 가져옵니다.
```
postgres=> CREATE TABLE test_gzip(id int, a text, b text, c text, d text);
postgres=> SELECT aws_s3.table_import_from_s3(
'test_gzip', '', '(format csv)',
'amzn-s3-demo-bucket', 'test-data.gz', 'us-east-2'
);
```
## 인코딩된 Amazon S3 파일 가져오기
다음 예에서는 Windows-1252 인코딩이 있는 Amazon S3에서 파일을 가져오는 방법을 보여줍니다.
```
postgres=> SELECT aws_s3.table_import_from_s3(
'test_table', '', 'encoding ''WIN1252''',
aws_commons.create_s3_uri('amzn-s3-demo-bucket', 'SampleFile', 'us-east-2')
);
```
# 함수 참조
**Topics**
+ [aws\$1s3.table\$1import\$1from\$1s3](#aws_s3.table_import_from_s3)
+ [aws\$1commons.create\$1s3\$1uri](#USER_PostgreSQL.S3Import.create_s3_uri)
+ [aws\$1commons.create\$1aws\$1credentials](#USER_PostgreSQL.S3Import.create_aws_credentials)
## aws\$1s3.table\$1import\$1from\$1s3
Amazon S3 데이터를 Aurora PostgreSQL 테이블로 가져옵니다. `aws_s3` 확장은 `aws_s3.table_import_from_s3` 함수를 제공합니다. 반환 값은 텍스트입니다.
### 구문
필수 파라미터는 `table_name`, `column_list` 및 `options`입니다. 이 파라미터에서는 데이터베이스 테이블을 식별하고 데이터가 테이블로 복사되는 방식을 지정합니다.
다음 파라미터를 사용할 수도 있습니다.
+ `s3_info` 파라미터는 가져올 Amazon S3 파일을 지정합니다. 이 파라미터를 사용하는 경우 IAM 역할에서 PostgreSQL DB 클러스터에 대해 Amazon S3에 액세스할 수 있는 권한을 제공합니다.
```
aws_s3.table_import_from_s3 (
table_name text,
column_list text,
options text,
s3_info aws_commons._s3_uri_1
)
```
+ `credentials` 파라미터에서는 Amazon S3에 액세스할 수 있는 자격 증명을 지정합니다. 이 파라미터를 사용할 때는 IAM 역할을 사용하지 마십시오.
```
aws_s3.table_import_from_s3 (
table_name text,
column_list text,
options text,
s3_info aws_commons._s3_uri_1,
credentials aws_commons._aws_credentials_1
)
```
### 파라미터
*table\$1name*
데이터를 가져올 필수 텍스트 문자열로서, PostgreSQL 데이터베이스 테이블의 이름을 포함합니다.
*column\$1list*
데이터를 복사할 PostgreSQL 데이터베이스 테이블 열의 목록(선택 사항)을 포함하는 필수 텍스트 문자열입니다. 문자열이 비어 있는 경우 테이블의 모든 열이 사용됩니다. 관련 예시는 [사용자 지정 구분 기호를 사용하는 Amazon S3 파일 가져오기](USER_PostgreSQL.S3Import.FileFormats.md#USER_PostgreSQL.S3Import.FileFormats.CustomDelimiter) 단원을 참조하십시오.
*options*
PostgreSQL `COPY` 명령에 대한 인수를 포함하는 필수 텍스트 스트링입니다. 이 인수에서는 데이터가 PostgreSQL 테이블에 복사되는 방식을 지정합니다. 자세한 내용은 [PostgreSQL COPY 설명서](https://www.postgresql.org/docs/current/sql-copy.html)를 참조하십시오.
*s3\$1info*
S3 객체에 대한 다음 정보를 포함하는 `aws_commons._s3_uri_1` 복합 키입니다.
+ `bucket` – 파일이 포함된 Amazon S3 버킷의 이름입니다.
+ `file_path` – 파일 경로를 포함한 Amazon S3 파일 이름입니다.
+ `region` - 파일이 위치한 AWS 리전입니다. AWS 리전 이름 및 연결된 값의 목록은 [리전 및 가용 영역](Concepts.RegionsAndAvailabilityZones.md) 섹션을 참조하십시오.
*credentials*
가져오기 작업에 사용할 다음 자격 증명을 포함하는 `aws_commons._aws_credentials_1` 복합 유형입니다.
+ 액세스 키
+ 비밀 키
+ 세션 토큰
`aws_commons._aws_credentials_1` 복합 구조 생성에 대한 자세한 내용은 [aws\$1commons.create\$1aws\$1credentials](#USER_PostgreSQL.S3Import.create_aws_credentials) 단원을 참조하십시오.
### 대체 구문
`s3_info` 및 `credentials` 파라미터 대신에 확장 파라미터 집합을 사용하면 테스트에 도움이 됩니다. 다음은 `aws_s3.table_import_from_s3` 함수에 대한 추가 구문 변형입니다.
+ `s3_info` 파라미터를 사용해 Amazon S3 파일을 식별하는 대신 `bucket`, `file_path` 및 `region` 파라미터의 조합을 사용하십시오. IAM 역할은 이러한 형식의 함수를 통해 PostgreSQL DB 인스턴스에 대해 Amazon S3에 액세스할 수 있는 권한을 제공합니다.
```
aws_s3.table_import_from_s3 (
table_name text,
column_list text,
options text,
bucket text,
file_path text,
region text
)
```
+ `credentials` 파라미터를 사용해 Amazon S3 액세스를 지정하는 대신 `access_key`, `session_key` 및 `session_token` 파라미터의 조합을 사용하십시오.
```
aws_s3.table_import_from_s3 (
table_name text,
column_list text,
options text,
bucket text,
file_path text,
region text,
access_key text,
secret_key text,
session_token text
)
```
### 대체 파라미터
*버킷*
파일이 들어 있는 Amazon S3 버킷의 이름이 포함된 텍스트 문자열입니다.
*file\$1path*
파일 경로를 포함한 Amazon S3 파일 이름이 포함된 텍스트 문자열입니다.
*리전*
파일의 AWS 리전 위치를 식별하는 텍스트 문자열입니다. AWS 리전 이름 및 연결된 값의 목록은 [리전 및 가용 영역](Concepts.RegionsAndAvailabilityZones.md) 섹션을 참조하세요.
*access\$1key*
가져오기 작업에 사용할 액세스 키가 포함된 텍스트 문자열입니다. 기본값은 NULL입니다.
*secret\$1key*
가져오기 작업에 사용할 비밀 키가 포함된 텍스트 문자열입니다. 기본값은 NULL입니다.
*session\$1token*
(선택 사항) 가져오기 작업에 사용할 세션 키가 포함된 텍스트 문자열입니다. 기본값은 NULL입니다.
## aws\$1commons.create\$1s3\$1uri
Amazon S3 파일 정보를 저장할 `aws_commons._s3_uri_1` 구조를 생성합니다. `aws_commons.create_s3_uri` 함수의 `s3_info` 파라미터에서 [aws\$1s3.table\$1import\$1from\$1s3](#aws_s3.table_import_from_s3) 함수의 결과를 사용합니다.
### 구문
```
aws_commons.create_s3_uri(
bucket text,
file_path text,
region text
)
```
### 파라미터
*버킷*
파일의 Amazon S3 버킷 이름이 포함된 필수 텍스트 문자열입니다.
*file\$1path*
파일 경로를 포함한 Amazon S3 파일 이름이 포함된 필수 텍스트 문자열입니다.
*리전*
파일이 위치한 AWS 리전이 포함된 필수 텍스트 문자열입니다. AWS 리전 이름 및 연결된 값의 목록은 [리전 및 가용 영역](Concepts.RegionsAndAvailabilityZones.md) 섹션을 참조하세요.
## aws\$1commons.create\$1aws\$1credentials
`aws_commons._aws_credentials_1` 구조에서 액세스 키와 비밀 키를 설정합니다. `aws_commons.create_aws_credentials` 함수의 `credentials` 파라미터에서 [aws\$1s3.table\$1import\$1from\$1s3](#aws_s3.table_import_from_s3) 함수의 결과를 사용합니다.
### 구문
```
aws_commons.create_aws_credentials(
access_key text,
secret_key text,
session_token text
)
```
### 파라미터
*access\$1key*
Amazon S3 파일 가져오기에 사용할 액세스 키가 포함된 필수 텍스트 문자열입니다. 기본값은 NULL입니다.
*secret\$1key*
Amazon S3 파일 가져오기에 사용할 비밀 키가 포함된 필수 텍스트 문자열입니다. 기본값은 NULL입니다.
*session\$1token*
Amazon S3 파일 가져오기에 사용할 세션 토큰이 포함된 텍스트 문자열(선택 사항)입니다. 기본값은 NULL입니다. 선택 사항인 `session_token`을 제공하는 경우 임시 자격 증명을 사용할 수 있습니다.