使用 Amazon S3 Tables Iceberg REST 端點存取資料表 - Amazon Simple Storage Service
設定端點驗證和授權對端點的存取權字首和路徑參數支援的 Iceberg REST API 操作考量和限制

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

您可以將 Iceberg REST 用戶端連線至 Amazon S3 Tables Iceberg REST 端點，並進行 REST API 呼叫，以在 S3 資料表儲存貯體中建立、更新或查詢資料表。端點實作了一組在 Apache Iceberg REST Catalog Open API 規格中指定的標準化 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

設定端點

您可以使用服務端點連線至 Amazon S3 Tables Iceberg 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 Tables Iceberg REST 端點。

PyIceberg

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

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

若要搭配 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.<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) 進行驗證。如需進一步了解 SigVAWS 4 的 API 請求，請參閱簽章版本 4。 AWS SigV4

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

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

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

字首和路徑參數

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 操作來刪除資料表。

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

限制

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

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

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

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

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