本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 Amazon S3 Tables Iceberg REST 端點存取資料表 您可以將 Iceberg REST 用戶端連線至 Amazon S3 Tables Iceberg REST 端點，並進行 REST API 呼叫，以在 S3 資料表儲存貯體中建立、更新或查詢資料表。端點實作了一組在 [Apache Iceberg REST Catalog Open API 規格](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml)中指定的標準化 Iceberg REST API。端點的運作方式是將 Iceberg REST API 操作轉換為對應的 S3 Tables 操作。 **注意** Amazon S3 Tables Iceberg REST 端點可用來存取 AWS Partner Network (APN) 目錄實作或自訂目錄實作中的資料表。如果您只需要單一資料表儲存貯體的基本讀取/寫入存取權，也可以使用此項。對於其他存取案例， AWS Glue Iceberg REST我們建議您使用端點連接到資料表，以提供統一的資料表管理、集中式控管和精細存取控制。如需詳細資訊，請參閱[使用 AWS GlueIceberg REST 端點存取 Amazon S3 Tables](s3-tables-integrating-glue-endpoint.md) ## 設定端點 您可以使用服務端點連線至 Amazon S3 Tables Iceberg REST 端點。S3 Tables Iceberg REST 端點具有下列格式： ``` https://s3tables..amazonaws.com/iceberg ``` 如需特定的區域端點，請參閱 [S3 資料表 AWS 區域 和端點](s3-tables-regions-quotas.md#s3-tables-regions)。 **目錄組態屬性** 使用 Iceberg 用戶端將分析引擎連接到服務端點時，您必須在初始化目錄時指定下列組態屬性。將*預留位置值*取代為您的區域和資料表儲存貯體的資訊。 + 做為端點 URI 的特定區域端點：`https://s3tables..amazonaws.com/iceberg` + 做為倉儲位置的資料表儲存貯體 ARN：`arn:aws:s3tables:::bucket/` + 用於身分驗證的 Sigv4 屬性。服務端點請求的 SigV4 簽署名稱為：`s3tables` 下列範例示範如何設定不同的用戶端以使用 Amazon S3 Tables Iceberg REST 端點。 ------ #### [ PyIceberg ] 若要搭配 PyIceberg 使用 Amazon S3 Tables Iceberg REST 端點，請指定下列應用程式組態屬性： ``` rest_catalog = load_catalog( catalog_name, **{ "type": "rest", "warehouse":"arn:aws:s3tables:::bucket/", "uri": "https://s3tables..amazonaws.com/iceberg", "rest.sigv4-enabled": "true", "rest.signing-name": "s3tables", "rest.signing-region": "" } ) ``` ------ #### [ Apache Spark ] 若要搭配 Spark 使用 Amazon S3 Tables Iceberg REST 端點，請指定下列應用程式組態屬性，將*預留位置值*取代為區域和資料表儲存貯體的資訊。 ``` spark-shell \ --packages "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,software.amazon.awssdk:bundle:2.20.160,software.amazon.awssdk:url-connection-client:2.20.160" \ --master "local[*]" \ --conf "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" \ --conf "spark.sql.defaultCatalog=spark_catalog" \ --conf "spark.sql.catalog.spark_catalog=org.apache.iceberg.spark.SparkCatalog" \ --conf "spark.sql.catalog.spark_catalog.type=rest" \ --conf "spark.sql.catalog.spark_catalog.uri=https://s3tables..amazonaws.com/iceberg" \ --conf "spark.sql.catalog.spark_catalog.warehouse=arn:aws:s3tables:::bucket/" \ --conf "spark.sql.catalog.spark_catalog.rest.sigv4-enabled=true" \ --conf "spark.sql.catalog.spark_catalog.rest.signing-name=s3tables" \ --conf "spark.sql.catalog.spark_catalog.rest.signing-region=" \ --conf "spark.sql.catalog.spark_catalog.io-impl=org.apache.iceberg.aws.s3.S3FileIO" \ --conf "spark.hadoop.fs.s3a.aws.credentials.provider=org.apache.hadoop.fs.s3a.SimpleAWSCredentialProvider" \ --conf "spark.sql.catalog.spark_catalog.rest-metrics-reporting-enabled=false" ``` ------ ## 驗證和授權對端點的存取權 對 S3 Tables 服務端點的 API 請求會使用 AWS Signature 第 4 版 (SigV4) 進行驗證。如需進一步了解 SigV[AWS 4 的 API 請求，請參閱簽章版本](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 4。 AWS SigV4 Amazon S3 Tables Iceberg REST 端點請求的 SigV4 簽署名稱為：`s3tables` Amazon S3 Tables Iceberg REST 端點的請求會使用與 REST API 操作對應的 `s3tables` IAM 動作進行授權。這些權限可以在連接到資料表和資料表儲存貯體的 IAM 身分型政策或資源型政策中定義。如需詳細資訊，請參閱[S3 Tables 的存取管理](s3-tables-setting-up.md)。 您可以使用 AWS CloudTrail追蹤透過 REST 端點對資料表提出的請求。請求會記錄為其對應 S3 IAM 動作。例如，`LoadTable` API 會為 `GetTableMetadataLocation` 操作產生管理事件，並為 `GetTableData` 操作產生資料事件。如需詳細資訊，請參閱[使用 AWS CloudTrail 適用於 S3 資料表的 進行記錄](s3-tables-logging.md)。 ## 字首和路徑參數 Iceberg REST 型錄 API 在其請求 URL 中具有自由格式字首。例如，`ListNamespaces` API 呼叫使用 `GET/v1/{prefix}/namespaces` URL 格式。對於 S3 資料表，REST 路徑 `{prefix}` 始終是您的 url 編碼的資料表儲存貯體 ARN。 例如，對於下列資料表儲存貯體 ARN：`arn:aws:s3tables:us-east-1:111122223333:bucket/bucketname` 字首為：`arn%3Aaws%3As3tables%3Aus-east-1%3A111122223333%3Abucket%2Fbucketname` ### 命名空間路徑參數 Iceberg REST 型錄 API 路徑中的命名空間可以具有多個層級。但是，S3 Tables 僅支援單一層級命名空間。若要存取多層型錄階層中的命名空間，您可以在參考命名空間時連線到命名空間上方的多層型錄。與使用多層命名空間相比，這可讓任何支援 `catalog.namespace.table` 的三部分表示法的查詢引擎存取 S3 Tables 的型錄階層結構中的物件，而不會出現相容性問題。 ## 支援的 Iceberg REST API 操作 下表資料表包含支援的 Iceberg REST API，以及它們如何對應至 S3 Tables 動作。 | Iceberg REST 操作 | REST 路徑 | S3 Tables IAM 動作 | CloudTrail EventName | | --- | --- | --- | --- | | `getConfig` | `GET /v1/config` | `s3tables:GetTableBucket` | `s3tables:GetTableBucket` | | `listNamespaces` | `GET /v1/{prefix}/namespaces` | `s3tables:ListNamespaces` | `s3tables:ListNamespaces` | | `createNamespace` | `POST /v1/{prefix}/namespaces` | `s3tables:CreateNamespace` | `s3tables:CreateNamespace` | | `loadNamespaceMetadata` | `GET /v1/{prefix}/namespaces/{namespace}` | `s3tables:GetNamespace` | `s3tables:GetNamespace` | | `dropNamespace` | `DELETE /v1/{prefix}/namespaces/{namespace}` | `s3tables:DeleteNamespace` | `s3tables:DeleteNamespace` | | `listTables` | `GET /v1/{prefix}/namespaces/{namespace}/tables` | `s3tables:ListTables` | `s3tables:ListTables` | | `createTable` | `POST /v1/{prefix}/namespaces/{namespace}/tables` | `s3tables:CreateTable`, `s3tables:PutTableData` | `s3tables:CreateTable`, `s3tables:PutObject` | | `loadTable` | `GET /v1/{prefix}/namespaces/{namespace}/tables/{table}` | `s3tables:GetTableMetadataLocation`, `s3tables:GetTableData` | `s3tables:GetTableMetadataLocation`, `s3tables:GetObject` | | `updateTable` | `POST /v1/{prefix}/namespaces/{namespace}/tables/{table}` | `s3tables:UpdateTableMetadataLocation`, `s3tables:PutTableData`, `s3tables:GetTableData` | `s3tables:UpdateTableMetadataLocation`, `s3tables:PutObject`, `s3tables:GetObject` | | `dropTable` | `DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}` | `s3tables:DeleteTable` | `s3tables:DeleteTable` | | `renameTable` | `POST /v1/{prefix}/tables/rename` | `s3tables:RenameTable` | `s3tables:RenameTable` | | `tableExists` | `HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}` | `s3tables:GetTable` | `s3tables:GetTable` | | `namespaceExists` | `HEAD /v1/{prefix}/namespaces/{namespace}` | `s3tables:GetNamespace` | `s3tables:GetNamespace` | ## 考量和限制 以下是使用 Amazon S3 Tables Iceberg REST 端點時的考量和限制。 ****考量**** + **CreateTable API 行為** – 此操作不支援 `stage-create` 選項，因而導致 `400 Bad Request` 錯誤。這表示您無法使用 `CREATE TABLE AS SELECT` (CTAS) 從查詢結果建立資料表。 + **DeleteTable API 行為** – 您只能捨棄已啟用清除的資料表。不支援捨棄具有 `purge=false` 的資料表，因而導致 `400 Bad Request` 錯誤。即使執行 `DROP TABLE PURGE` 命令，部分版本的 Spark 仍會一律將此旗標設定為 false。您可以嘗試 `DROP TABLE PURGE`，或使用 S3 Tables [DeleteTable](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTable.html) 操作來刪除資料表。 + 該端點僅支援標準資料表中繼資料操作。對於快照管理和壓縮等資料表維護，請使用 S3 Tables 維護 API 操作。如需詳細資訊，請參閱[S3 Tables 維護](s3-tables-maintenance-overview.md)。 ****限制**** + 不支援多層級命名空間。 + 不支援以 OAuth 為基礎的驗證。 + 命名空間僅支援 `owner` 屬性。 + 不支援在 [Apache Iceberg REST Open API 規格](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml)中定義的檢視相關 API。 + 不支援在`metadata.json`檔案超過 50MB 的資料表上執行操作，並會傳回`400 Bad Request`錯誤。若要控制 `metadata.json` 檔案大小，請使用資料表維護操作。如需詳細資訊，請參閱[S3 Tables 維護](s3-tables-maintenance-overview.md)。