使用 Amazon S3 TablesIceberg REST 端點存取資料表

您可以將Iceberg REST用戶端連線至 Amazon S3 TablesIceberg REST 端點，並REST API呼叫 以在 S3 資料表儲存貯體中建立、更新或查詢資料表。端點實作目錄開放 Iceberg REST APIs 規格 中指定的一組標準化 API。 Apache Iceberg REST端點的運作方式是將 Iceberg REST API 操作轉換為對應的 S3 Tables 操作。

注意

Amazon S3 TablesIceberg REST 端點可用來存取 AWS Partner Network (APN) 目錄實作或自訂目錄實作中的資料表。如果您只需要對單一資料表儲存貯體的基本讀取/寫入存取權，也可以使用它。對於其他存取案例， AWS Glue Iceberg REST我們建議使用端點來連線至資料表，以提供統一的資料表管理、集中式控管和精細存取控制。如需詳細資訊，請參閱 使用 AWS GlueIceberg REST端點存取 Amazon S3 資料表

設定端點

您可以使用 服務端點連線至 Amazon S3 TablesIceberg REST 端點。S3 Tables Iceberg REST端點的格式如下：

https://s3tables.<REGION>.amazonaws.com/iceberg

如需區域特定的端點S3 資料表 AWS 區域 和端點，請參閱 。

目錄組態屬性

使用 Iceberg 用戶端將分析引擎連接到服務端點時，您必須在初始化目錄時指定下列組態屬性。將預留位置值取代為區域和資料表儲存貯體的資訊。

• 做為端點 URI 的區域特定端點： https://s3tables.<REGION>.amazonaws.com/iceberg

• 資料表儲存貯體 ARN 做為倉儲位置： arn:aws:s3tables:<region>:<accountID>:bucket/<bucketname>

• 用於身分驗證的 Sigv4 屬性。服務端點請求的 SigV4 簽署名稱為： s3tables

下列範例示範如何設定不同的用戶端以使用 Amazon S3 TablesIceberg REST 端點。

PyIceberg

若要搭配 使用 Amazon S3 TablesIceberg REST 端點PyIceberg，請指定下列應用程式組態屬性：

rest_catalog = load_catalog(
  catalog_name,
  **{
    "type": "rest",    
    "warehouse":"arn:aws:s3tables:<Region>:<accountID>:bucket/<bucketname>",
    "uri": "https://s3tables.<Region>.amazonaws.com/iceberg",
    "rest.sigv4-enabled": "true",
    "rest.signing-name": "s3tables",
    "rest.signing-region": "<Region>"
  }
)                

Apache Spark

若要將 Amazon S3 TablesIceberg REST 端點與 搭配使用Spark，請指定下列應用程式組態屬性，將預留位置值取代為區域和資料表儲存貯體的資訊。

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.<Region>.amazonaws.com/iceberg" \
  --conf "spark.sql.catalog.spark_catalog.warehouse=arn:aws:s3tables:<Region>:<accountID>:bucket/<bucketname>" \
  --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=<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) 進行身分驗證。如需 AWS API 請求的詳細資訊，請參閱簽章版本 4 AWS SigV4。

Amazon S3 Tables 端點請求的 SigV4 簽署名稱為：Iceberg REST s3tables

對 Amazon S3 TablesIceberg REST 端點的請求會使用對應於 REST API 操作的 s3tables IAM 動作進行授權。這些許可可以在連接到資料表和資料表儲存貯體的 IAM 身分型政策或資源型政策中定義。如需詳細資訊，請參閱S3 Tables 的存取管理。

您可以使用 REST 端點追蹤對資料表提出的請求 AWS CloudTrail。請求將記錄為對應的 S3 IAM 動作。例如，LoadTableAPI 將為 GetTableMetadataLocation操作產生管理事件，並為 GetTableData操作產生資料事件。如需詳細資訊，請參閱使用 AWS CloudTrail 適用於 S3 資料表的 記錄。

字首和路徑參數

Iceberg REST 目錄 APIs請求 URLs 中具有自由格式字首。例如，ListNamespacesAPI 呼叫使用 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 僅支援單一層級命名空間。若要存取多層目錄階層中的命名空間，您可以在參考命名空間時連線到命名空間上方的多層目錄。這允許支援 的 3 部分表示法的任何查詢引擎catalog.namespace.table存取 S3 Tables 目錄階層中的物件，與使用多層命名空間相比，沒有相容性問題。

支援的 Iceberg REST API 操作

下表包含支援的 Iceberg REST APIs以及它們如何對應至 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 TablesIceberg 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 操作來刪除資料表。

• 端點僅支援標準資料表中繼資料操作。對於快照管理和壓縮等資料表維護，請使用 S3 Tables 維護 API 操作。如需詳細資訊，請參閱S3 Tables 維護。

限制

• 不支援多層級命名空間。

• 不支援以 OAuth 為基礎的身分驗證。

• 命名空間僅支援 owner 屬性。

• 不支援 Open APIs 規格中定義的檢視相關 API。 Apache Iceberg REST

• 不支援在metadata.json檔案超過 5MB 的資料表上執行操作，並會傳回400 Bad Request錯誤。若要控制metadata.json檔案大小，請使用資料表維護操作。如需詳細資訊，請參閱S3 Tables 維護。