本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 將資料從 Amazon S3 匯入 Aurora PostgreSQL 資料庫叢集 將資料從 Amazon S3 匯入 Aurora PostgreSQL 您可以將使用 Amazon Simple Storage Service 儲存的資料匯入 Aurora PostgreSQL 資料庫叢集。要執行此操作，您首先安裝 Aurora PostgreSQL `aws_s3` 擴充功能。此擴充功能提供可用於從 Amazon S3 儲存貯體匯入資料的函數。*儲存貯體*是物件或檔案的 Amazon S3 容器。資料可以是逗號分隔值 (CSV) 檔案、文字檔案或壓縮 (gzip) 檔案。從下文中，您可以了解如何安裝擴充功能，以及如何將資料從 Amazon S3 匯入資料表。 您的資料庫必須執行 PostgreSQL 10.7 版或更高版本，才能從 Simple Storage Service (Amazon S3) 匯入 。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)。 **注意** Aurora Serverless v1 不支援從 Amazon S3 匯入資料。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 資料庫叢集 ](USER_PostgreSQL.S3Import.FileFormats.md) + [ # 函數參考 ](USER_PostgreSQL.S3Import.Reference.md) # 安裝 aws\$1s3 擴充功能 安裝擴充功能 您需要先安裝 `aws_s3` 擴充功能，才能將 Amazon S3 與 Aurora PostgreSQL 資料庫叢集 搭配使用。此擴充功能提供從 Amazon S3 匯入資料的函數。它還提供了從 Aurora PostgreSQL 資料庫叢集執行個體中匯出資料到 Amazon S3 儲存貯體的功能。如需更多詳細資訊，請參閱 [將資料從 Aurora PostgreSQL 資料庫叢集匯出至 Amazon S3](postgresql-s3-export.md)。`aws_s3` 擴充功能取決於 `aws_commons` 擴充功能中的一些輔助函數，需要時會自動安裝。 **安裝 `aws_s3` 擴充功能** 1. 使用 psql (或 pgAdmin) 以具有 `rds_superuser` 權限的使用者身分連接到 Aurora PostgreSQL 資料庫叢集的寫入器執行個體 。若您在安裝程序期間保留預設名稱，則連接為 `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 資料庫叢集執行個體上的資料表名稱、以及儲存貯體名稱、檔案路徑、檔案類型，以及 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 儲存貯體以及要匯入資料的詳細資料。要執行此操作，請在以下網址開啟 Amazon S3 主控台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)，然後選擇 **Buckets** (儲存貯體)。在清單中尋找包含您資料的儲存貯體。選擇儲存貯體，開啟其物件概觀頁面，然後選擇 Properties (屬性)。 請記下儲存貯體名稱、路徑 AWS 區域、 和 檔案類型。您稍後需要 Amazon Resource Name (ARN)，以設定透過 IAM 角色對 Amazon S3 的存取權限。如需詳細資訊，請參閱 [設定對 Amazon S3 儲存貯體的存取權](USER_PostgreSQL.S3Import.AccessPermission.md)。下圖顯示範例。 ![\[Amazon S3 儲存貯體中檔案物件的影像。\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/AuroraUserGuide/images/aws_s3_import-export_s3_bucket-info.png) 1. 您可以使用 AWS CLI 命令 來驗證 Amazon S3 儲存貯體上資料的路徑`aws s3 cp`。如果資訊正確，此命令會下載 Amazon S3 檔案的副本。 ``` aws s3 cp s3://amzn-s3-demo-bucket/sample_file_path ./ ``` 1. 設定 Aurora PostgreSQL 資料庫叢集 的許可，以允許存取 Amazon S3 儲存貯體上的檔案。若要這樣做，您可以使用 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 資料庫叢集 ](USER_PostgreSQL.S3Import.FileFormats.md)。 # 設定對 Amazon S3 儲存貯體的存取權 若要從 Amazon S3 檔案匯入資料，請為 Aurora PostgreSQL 資料庫叢集提供許可，以便存取檔案所在的 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 資料庫叢集 提供許可，以便存取檔案所在的 Amazon S3 儲存貯體。這樣您就不必管理額外的登入資料資訊或在 [aws\$1s3.table\$1import\$1from\$1s3](USER_PostgreSQL.S3Import.Reference.md#aws_s3.table_import_from_s3) 函數呼叫中提供它。 若要執行此動作，請建立可提供 Amazon S3 儲存貯體存取的 IAM 政策。建立 IAM 角色，並將政策連接到該角色。然後將 IAM 角色指派到您的資料庫叢集。 **注意** 您無法建立 IAM 角色與 Aurora Serverless v1 資料庫叢集的關聯，因此以下步驟不適用。 **透過 IAM 角色將 Aurora PostgreSQL 資料庫叢集 的存取權授予 Amazon S3** 1. 建立 IAM 政策。 此政策可提供儲存貯體及物件許可，讓 Aurora PostgreSQL 資料庫叢集 能夠存取 Amazon S3。 在政策中納入下列必要動作，以允許由 Amazon S3 儲存貯體傳輸檔案至 Aurora PostgreSQL： + `s3:GetObject` + `s3:ListBucket` 在政策中包含下列資源，以識別 Amazon S3 儲存貯體和儲存貯體中的物件。這會顯示用於存取 Amazon S3 的 Amazon Resource Name (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 Resource Name (ARN)。在後續步驟中將政策連接至 IAM 角色時，您會需要此 ARN。 **Example** 針對 Linux、macOS 或 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)最有效的方式。 如果同時使用這兩個全域條件內容索引鍵，且 `aws:SourceArn` 值包含帳戶 ID，則在相同政策陳述式中使用 `aws:SourceAccount` 值和 `aws:SourceArn` 值中的帳戶時，必須使用相同的帳戶 ID。 + 如果您想要跨服務存取單一資源，請使用 `aws:SourceArn`。 + 如果您想要允許該帳戶中的任何資源與跨服務使用相關聯，請使用 `aws:SourceAccount`。 在政策中，請務必搭配資源的完整 ARN 來使用 `aws:SourceArn` 全域條件內容金鑰。下列範例示範如何使用 AWS CLI 命令來建立名為 的角色`rds-s3-import-role`。 **Example** 針對 Linux、macOS 或 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` Replace `your-policy-arn` with the policy ARN 的角色，該角色是您在先前步驟中記下的政策 ARN。 **Example** 針對 Linux、macOS 或 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 角色新增至資料庫叢集。 您可以使用 AWS 管理主控台 或 來執行此操作 AWS CLI，如下所述。 ### 主控台 **使用主控台為 PostgreSQL 資料庫叢集新增 IAM 角色** 1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/)：// 開啟 Amazon RDS 主控台。 1. 選擇 PostgreSQL 資料庫叢集名稱以顯示其詳細資訊。 1. 在 **Connectivity & security (連線能力與安全)** 標籤上，在 **Manage IAM roles (管理 IAM 角色)** 區段中，在 **Add IAM roles to this cluster (將 IAM 角色新增到此叢集執行個體)** 下方，選擇要新增的角色。 1. 請在 **Feature** (功能) 下，選擇 **s3Import**。 1. 選擇 **Add role (新增角色)**。 ### AWS CLI **使用 CLI 為 PostgreSQL 資料庫叢集新增 IAM 角色** + 使用下列命令將角色新增至名為 `my-db-cluster` 的 PostgreSQL 資料庫叢集。將 *`your-role-arn`* 替換為您前個步驟記下的角色 ARN。使用 `s3Import` 作為 `--feature-name` 選項的值。 **Example** 針對 Linux、macOS 或 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 資料庫叢集新增 IAM 角色，請呼叫 [AddRoleToDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_AddRoleToDBCluster.html) 操作。 ## 使用安全登入資料存取 Amazon S3 儲存貯體 如果想要，可以使用安全登入資料來提供 Amazon S3 儲存貯體的存取，而非使用 IAM 角色提供存取。要執行此操作，您可以指定 [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 使用者指南*》中的[針對 Amazon S3 進行故障診斷](https://docs.aws.amazon.com/AmazonS3/latest/userguide/troubleshooting.html)。 + 《*IAM 使用者指南*》中的[針對 Amazon S3 和 IAM 進行故障診斷](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_iam-s3.html) # 將資料從 Amazon S3 匯入 Aurora PostgreSQL 資料庫叢集 您可以使用 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)。 **注意** 下列範例使用 IAM 角色方法，允許對 Amazon S3 儲存貯體的存取。因此，`aws_s3.table_import_from_s3` 函數呼叫不包含登入資料參數。 以下顯示一個典型範例。 ``` postgres=> SELECT aws_s3.table_import_from_s3( 't1', '', '(format csv)', :'s3_uri' ); ``` 參數如下： + `t1` – PostgreSQL 資料庫叢集的表格名稱，資料會複製到此表格。 + `''` – 資料庫表格之中選用的欄清單。您可使用此參數指出哪些 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 管理主控台，系統通常會套用中繼資料。如需有關使用 AWS 管理主控台、 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 檔案匯入 Aurora PostgreSQL 資料庫叢集 。 ``` 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 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 角色會將 Amazon S3 存取權提供給 PostgreSQL 資料庫叢集。 ``` 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 ) ``` ### Parameters *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* `aws_commons._s3_uri_1` 複合類型，含有下列 S3 物件相關資訊： + `bucket` – 含有檔案的 Amazon S3 儲存貯體名稱。 + `file_path` – 包括檔案路徑的 Amazon S3 檔案名稱。 + `region` – 檔案所在的 AWS 區域。如需 AWS 區域名稱和相關值的清單，請參閱 [區域和可用區域](Concepts.RegionsAndAvailabilityZones.md)。 *登入資料* `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` 參數組合進行。使用這種形式的函數，Amazon S3 存取權會由 IAM 角色在 PostgreSQL 資料庫執行個體提供。 ``` 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 ) ``` ### 替代參數 *bucket* 文字字串，其中含有包含檔案的 Amazon S3 儲存貯體名稱。 *file\$1path* 包含 Amazon S3 檔案名稱 (包括檔案路徑) 的文字字串。 *region* 識別檔案 AWS 區域 位置的文字字串。如需 AWS 區域 名稱和相關值的清單，請參閱 [區域和可用區域](Concepts.RegionsAndAvailabilityZones.md)。 *access\$1key* 文字字串，其中含有用於匯入作業的存取金鑰。預設值為 NULL。 *secret\$1key* 文字字串，其中含有用於匯入作業的秘密金鑰。預設值為 NULL。 *session\$1token* (選用) 文字字串，其中含有用於匯入作業的工作階段金鑰。預設值為 NULL。 ## aws\$1commons.create\$1s3\$1uri aws\$1commons.create\$1s3\$1uri 建立 `aws_commons._s3_uri_1` 結構以保留 Amazon S3 檔案資訊。使用 `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 ) ``` ### Parameters *bucket* 必要的文字字串，其中含有檔案的 Amazon S3 儲存貯體名稱。 *file\$1path* 包含 Amazon S3 檔案名稱 (包括檔案路徑) 的必要文字字串。 *region* 必要的文字字串 AWS 區域 ，其中包含 檔案所在的 。如需 AWS 區域 名稱和相關值的清單，請參閱 [區域和可用區域](Concepts.RegionsAndAvailabilityZones.md)。 ## aws\$1commons.create\$1aws\$1credentials 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 ) ``` ### Parameters *access\$1key* 必要的文字字串，其中含有用於匯入 Amazon S3 檔案的存取金鑰。預設值為 NULL。 *secret\$1key* 必要的文字字串，其中含有用於匯入 Amazon S3 檔案的秘密金鑰。預設值為 NULL。 *session\$1token* 選用的文字字串，其中含有用於匯入 Amazon S3 檔案的工作階段字符。預設值為 NULL。如果您提供選用的 `session_token`，就可以使用臨時登入資料。