適用於 Apache Iceberg 規格的 AWS Glue REST API

本節包含 AWS Glue Iceberg REST 型錄和 AWS Glue 延伸模組 API 的規格，以及使用這些 API 時的考量。

對 AWS Glue Data Catalog 端點的 API 請求會使用 AWS 第 4 版簽署程序 (SigV4) 進行驗證。如需進一步了解 AWS SigV4，請參閱適用於 API 請求的 AWS 第 4 版簽署程序。

存取 AWS Glue 服務端點和 AWS Glue 中繼資料時，應用程式會擔任要求 glue:getCatalog IAM 動作的 IAM 角色。

可以使用 IAM、Lake Formation 或 Lake Formation 混合模式權限來管理對 Data Catalog 及其物件的存取。

Data Catalog 中的聯合型錄具有 Lake Formation 註冊的資料位置。Lake Formation 與 Data Catalog 搭配使用，可提供資料庫式許可，以管理使用者對 Data Catalog 物件的存取。

可以使用 IAM、AWS Lake Formation 或 Lake Formation 混合模式許可來管理對預設 Data Catalog 及其物件的存取。

若要在 Lake Formation 受管物件中建立、插入或刪除資料，則必須為 IAM 使用者或角色設定特定許可。

CREATE_CATALOG – 需要建立型錄
CREATE_DATABASE – 需要建立資料庫
CREATE_TABLE – 需要建立資料表
DELETE – 需要從資料表刪除資料
DESCRIBE – 需要讀取中繼資料
DROP – 需要捨棄/刪除資料表或資料庫
INSERT – 當主體需要將資料插入資料表時需要
SELECT – 當主體需要從資料表中選取資料時需要

如需詳細資訊，請參閱《AWS Lake Formation 開發人員指南》中的 Lake Formation 許可參考。

一般資訊
操作名稱	GetConfig
類型	Iceberg REST Catalog API
REST 路徑	GET /iceberg/v1/config
IAM 動作	glue:GetCatalog
Lake Formation 許可	不適用
CloudTrail 事件	glue:GetCatalog
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L67

考量和限制

warehouse 查詢參數必須設定為 AWS Glue 型錄 ID。如果未設定，則會使用目前帳戶中的根型錄來傳回回應。如需更多詳細資訊，請參閱字首和型錄路徑參數。

一般資訊
操作名稱	GetCatalog
類型	AWS Glue 延伸模組 API
REST 路徑	GET/extensions/v1/catalogs/{catalog}
IAM 動作	glue:GetCatalog
Lake Formation 許可	DESCRIBE
CloudTrail 事件	glue:GetCatalog
Open API 定義	https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L40

考量和限制

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。

一般資訊
操作名稱	ListNamespaces
類型	Iceberg REST Catalog API
REST 路徑	GET/iceberg/v1/catalogs/{catalog}/namespaces
IAM 動作	glue:GetDatabase
Lake Formation 許可	ALL, DESCRIBE, SELECT
CloudTrail 事件	glue:GetDatabase
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L205

考量與限制

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只會顯示下一級別的命名空間。要列出更深層的命名空間，請在型錄路徑參數中指定巢狀型錄 ID。

一般資訊
操作名稱	CreateNamespace
類型	Iceberg REST Catalog API
REST 路徑	POST/iceberg/v1/catalogs/{catalog}/namespaces
IAM 動作	glue:CreateDatabase
Lake Formation 許可	ALL, DESCRIBE, SELECT
CloudTrail 事件	glue:CreateDatabase
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L256

考量和限制

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能建立單一層級命名空間。若要建立多層級命名空間，您必須反覆建立每個層級，並使用型錄路徑參數連接至該層級。

一般資訊
操作名稱	StartCreateNamespaceTransaction
類型	AWS Glue Extensions API
REST 路徑	POST/extensions/v1/catalogs/{catalog}/namespaces
IAM 動作	glue:CreateDatabase
Lake Formation 許可	ALL, DESCRIBE, SELECT
CloudTrail 事件	glue:CreateDatabase
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L256

考量與限制

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能建立單一層級命名空間。若要建立多層級命名空間，必須反覆建立每個層級，並使用型錄路徑參數連接至該層級。
API 為非同步，並傳回可用於使用 CheckTransactionStatus API 呼叫進行追蹤的交易 ID。
只有當 GetCatalog API 呼叫在回應中包含參數 use-extensions=true 時，才能呼叫此 API。

一般資訊
操作名稱	LoadNamespaceMetadata
類型	Iceberg REST Catalog API
REST 路徑	GET/iceberg/v1/catalogs/{catalog}/namespaces/{ns}
IAM 動作	glue:GetDatabase
Lake Formation 許可	ALL, DESCRIBE, SELECT
CloudTrail 事件	glue:GetDatabase
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L302

考量與限制

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。

一般資訊
操作名稱	UpdateNamespaceProperties
類型	Iceberg REST Catalog API
REST 路徑	POST /iceberg/v1/catalogs/{catalog}/namespaces/{ns}/properties
IAM 動作	glue:UpdateDatabase
Lake Formation 許可	ALL, ALTER
CloudTrail 事件	glue:UpdateDatabase
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L400

考量與限制

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。

一般資訊
操作名稱	DeleteNamespace
類型	Iceberg REST Catalog API
REST 路徑	DELETE/iceberg/v1/catalogs/{catalog}/namespces/{ns}
IAM 動作	glue:DeleteDatabase
Lake Formation 許可	ALL, DROP
CloudTrail 事件	glue:DeleteDatabase
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L365

考量和限制

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。
如果資料庫中有物件，操作將會失敗。
API 為非同步，並傳回可用於使用 CheckTransactionStatus API 呼叫進行追蹤的交易 ID。
只有 GetCatalog API 呼叫在回應中指示 use-extensions=true 時，才能使用 API。

一般資訊
操作名稱	StartDeleteNamespaceTransaction
類型	AWS Glue Extensions API
REST 路徑	DELETE /extensions/v1/catalogs/{catalog}/namespces/{ns}
IAM 動作	glue:DeleteDatabase
Lake Formation 許可	ALL, DROP
CloudTrail 事件	glue:DeleteDatabase
Open API 定義	https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L85

考量與限制

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。
如果資料庫中有物件，操作將會失敗。
API 為非同步，並傳回可用於使用 CheckTransactionStatus API 呼叫進行追蹤的交易 ID。
只有 GetCatalog API 呼叫在回應中指示 use-extensions=true 時，才能使用 API。

一般資訊
操作名稱	ListTables
類型	Iceberg REST Catalog API
REST 路徑	GET /iceberg/v1/catalogs/{catalog}/namespaces/{ns}/tables
IAM 動作	glue:GetTables
Lake Formation 許可	ALL, SELECT, DESCRIBE
CloudTrail 事件	glue:GetTables
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L463

考量與限制

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。
將列出包括非 Iceberg 資料表在內的所有資料表。若要確定資料表是否可以載入為 Iceberg 資料表，請呼叫 LoadTable操作。

一般資訊
操作名稱	CreateTable
類型	Iceberg REST Catalog API
REST 路徑	GET /iceberg/v1/catalogs/{catalog}/namespaces/{ns}/tables
IAM 動作	glue:CreateTable
Lake Formation 許可	ALL, CREATE_TABLE
CloudTrail 事件	glue:CreateTable
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L497

考量和限制

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。
不支援具有暫存的 CreateTable。如果指定 stageCreate 查詢參數，操作將會失敗。這表示不支援 CREATE TABLE AS SELECT 等操作，您可以使用 CREATE TABLE 和 INSERT INTO 的組合作為解決方法。
CreateTable API 操作不支援選項 state-create = TRUE。

一般資訊
操作名稱	CreateTable
類型	AWS Glue Extensions API
REST 路徑	POST/extensions/v1/catalogs/{catalog}/namespaces/{ns}/tables
IAM 動作	glue:CreateTable
Lake Formation 許可	ALL, CREATE_TABLE
CloudTrail 事件	glue:CreateTable
Open API 定義	https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L107

考量與限制

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。
不支援具有暫存的 CreateTable。如果指定 stageCreate 查詢參數，操作將會失敗。這表示不支援 CREATE TABLE AS SELECT 等操作，使用者應使用 CREATE TABLE 和 INSERT INTO 的組合來解決問題。
API 為非同步，並傳回可用於使用 CheckTransactionStatus API 呼叫進行追蹤的交易 ID。
只有 GetCatalog API 呼叫在回應中指示 use-extensions=true 時，才能使用 API。

一般資訊
操作名稱	LoadTable
Type	Iceberg REST Catalog API
REST 路徑	GET /iceberg/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table}
IAM 動作	glue:GeTTable
Lake Formation 許可	ALL, SELECT, DESCRIBE
CloudTrail 事件	glue:GetTable
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L616

考量事項

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。
不支援具有暫存的 CreateTable。如果指定 stageCreate 查詢參數，操作將會失敗。這表示不支援 CREATE TABLE AS SELECT 等操作，使用者應使用 CREATE TABLE 和 INSERT INTO 的組合來解決問題。
API 為非同步，並傳回可用於使用 CheckTransactionStatus API 呼叫進行追蹤的交易 ID。
只有 GetCatalog API 呼叫在回應中指示 use-extensions=true 時，才能使用 API。

一般資訊
操作名稱	LoadTable
Type	AWS Glue Extensions API
REST 路徑	GET /extensions/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table}
IAM 動作	glue:GetTable
Lake Formation 許可	ALL, SELECT, DESCRIBE
CloudTrail 事件	glue:GetTable
Open API 定義	https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L134

考量事項

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。
快照查詢參數僅支援 all 模式。

與 LoadTable API 相比，ExtendedLoadTable API 有下列不同：

並不嚴格要求所有字段都可用。

在回應的組態欄位中提供下列額外參數：

額外參數
組態鍵	描述
aws.server-side-capabilities.scan-planning	指示是否可以使用 PreparePlan 資料表和 PlanTable API 掃描資料表。
aws.server-side-capabilities.data-commit	指出是否可以使用 StartUpdateTable 交易遞交資料表。
aws.glue.staging.location	用於伺服器端掃描規劃或資料遞交，其是一種服務受管的暫存位置，可用於引擎寫入暫存資料檔案
aws.glue.staging.access-key-id	用於伺服器端掃描規劃或資料遞交，這是存取服務受管暫存位置的暫時 AWS 憑證的一部分
aws.glue.staging.secret-access-key	用於伺服器端掃描規劃或資料遞交，這是存取服務受管暫存位置的暫時 AWS 憑證的一部分。
aws.glue.staging.session-token	用於伺服器端掃描規劃或資料遞交，這是存取服務受管暫存位置的暫時 AWS 憑證的一部分。
aws.glue.staging.expiration-ms	用於伺服器端掃描規劃或資料遞交、憑證過期時間，以存取服務受管暫存位置。
aws.glue.staging.data-transfer-role-arn	用於伺服器端掃描規劃或資料遞交，可擔任此 IAM 角色來存取服務受管暫存位置。

一般資訊
操作名稱	PreplanTable
Type	AWS Glue Extensions API
REST 路徑	POST /extensions/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table}/preplan
IAM 動作	glue:GetTable
Lake Formation 許可	ALL, SELECT, DESCRIBE
CloudTrail 事件	glue:GetTable
Open API 定義	https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L211

考量事項

型錄路徑參數應遵循字首和型錄路徑參數一節中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。
此 API 的呼叫者務必根據頁面字符來判斷是否有要擷取的剩餘結果。如果伺服器端仍在處理中，但在指定的回應時間內無法產生任何結果，則可能產生頁面項空白但具有分頁字符的回應。
只有在 ExtendedLoadTable API 回應包含 aws.server-side-capabilities.scan-planning=true 時，才能使用此 API。

一般資訊
操作名稱	PlanTable
Type	AWS Glue Extensions API
REST 路徑	POST /extensions/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table}/plan
IAM 動作	glue:GetTable
Lake Formation 許可	ALL, SELECT, DESCRIBE
CloudTrail 事件	glue:GetTable
Open API 定義	https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L243

考量事項

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。
此 API 的呼叫者務必根據頁面字符來判斷是否有要擷取的剩餘結果。如果伺服器端仍在處理中，但在指定的回應時間內無法產生任何結果，則可能產生頁面項空白但具有分頁字符的回應。
只有在 ExtendedLoadTable API 回應包含 aws.server-side-capabilities.scan-planning=true 時，才能使用此 API。

一般資訊
操作名稱	TableExists
Type	Iceberg REST Catalog API
REST 路徑	HEAD/iceberg/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table}
IAM 動作	glue:GetTable
Lake Formation 許可	ALL, SELECT, DESCRIBE
CloudTrail 事件	glue:GetTable
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L833

考量事項

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。

一般資訊
操作名稱	UpdateTable
Type	Iceberg REST Catalog API
REST 路徑	POST /iceberg/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table}
IAM 動作	glue:UpdateTable
Lake Formation 許可	ALL, ALTER
CloudTrail 事件	glue:UpdateTable
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L677

考量事項

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。

一般資訊
操作名稱	StartUpdateTableTransaction
Type	AWS Glue 延伸模組 API
REST 路徑	POST/extensions/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table}
IAM 動作	glue:UpdateTable
Lake Formation 許可	ALL, ALTER
CloudTrail 事件	glue:UpdateTable
Open API 定義	https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L154

考量事項

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。
API 為非同步，並傳回可用於使用 CheckTransactionStatus API 呼叫進行追蹤的交易 ID。
也可以透過此 API 執行 RenamTable 操作。發生這種情況時，呼叫者也必須擁有 ahve glue：CreateTable 或 LakeFormation CREATE_TABLE 許可，才能重新命名資料表。
只有在 ExtendedLoadTable API 回應包含 aws.server-side-capabilities.scan-planning=true 時，才能使用此 API。

一般資訊
操作名稱	DeleteTable
Type	Iceberg REST Catalog API
REST 路徑	DELETE/iceberg/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table}
IAM 動作	glue:DeleteTable
Lake Formation 許可	ALL, DROP
CloudTrail 事件	glue:DeleteTable
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L793

考量事項

型錄路徑參數應遵循字首和型錄路徑參數一節中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。
DeleteTable API 操作支援清除選項。在清除設定為 true 時，資料表資料會刪除，否則不會刪除資料。對於 Amazon S3 中的資料表，操作不會刪除資料表資料。當資料表儲存在 Amazon S3 中且 purge = TRUE, 時，操作會失敗。

對於儲存在 Amazon Redshift 受管儲存體中的資料表，操作會刪除資料表資料，類似於 Amazon Redshift 中 DROP TABLE 的行為。當資料表儲存在 Amazon Redshift 中且 purge = FALSE 時，操作會失敗。
不支援 purgeRequest=true。

一般資訊
操作名稱	StartDeleteTableTransaction
Type	AWS Glue Extensions API
REST 路徑	DELETE /extensions/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table}
IAM 動作	glue:DeleteTable
Lake Formation 許可	ALL, DROP
CloudTrail 事件	glue:DeleteTable
Open API 定義	https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L793

考量事項

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。
只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱命名空間路徑參數一節。
不支援 purgeRequest=false。
API 是非同步的，並傳回可透過 CheckTransactionStatus 追蹤的交易 ID。

一般資訊
操作名稱	CheckTransactionStatus
Type	AWS Glue Extensions API
REST 路徑	POST/extensions/v1/transactions/status
IAM 動作	與啟動交易的動作相同的許可
Lake Formation 許可	與啟動交易的動作相同的許可
Open API 定義	https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L273

考量事項

型錄路徑參數必須遵循字首和型錄路徑參數部分中所述的樣式。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用 AWS Glue Iceberg REST 延伸模組端點連線至 Data Catalog

從獨立 Spark 應用程式連線至 Data Catalog