本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
本節包含 AWS Glue Iceberg REST 目錄和 AWS Glue 延伸 APIs的規格，以及使用這些 APIs時的考量事項。
對 AWS Glue Data Catalog 端點的 API 請求會使用 AWS Signature 第 4 版 (SigV4) 進行身分驗證。如需 AWS API 請求的詳細資訊，請參閱簽章版本 4 一節 AWS SigV4。
存取 AWS Glue 服務端點和 AWS Glue 中繼資料時，應用程式會擔任需要 IAM 動作的 IAM glue:getCatalog 角色。
您可以使用 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 目錄 API |
| REST 路徑 |
GET /iceberg/v1/config |
| IAM 動作 |
glue：GetCatalog |
| Lake Formation 許可 | 不適用 |
| CloudTrail 事件 |
glue：GetCatalog |
| 開啟 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 |
| 開啟 API 定義 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L40 |
考量與限制
-
目錄路徑參數必須遵循 字首和目錄路徑參數章節中所述的樣式。
| 操作名稱 | ListNamespaces |
| 類型 |
Iceberg REST 目錄 API |
| REST 路徑 |
GET/iceberg/v1/catalogs/{catalog}/namespaces |
| IAM 動作 |
glue：GetDatabase |
| Lake Formation 許可 | ALL、DESCRIBE、SELECT |
| CloudTrail 事件 |
glue：GetDatabase |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L205 |
考量與限制
-
目錄路徑參數必須遵循 字首和目錄路徑參數章節中所述的樣式。
-
只會顯示下一個關卡的命名空間。若要列出更深層的命名空間，請在目錄路徑參數中指定巢狀目錄 ID。
| 操作名稱 | CreateNamespace |
| 類型 |
Iceberg REST 目錄 API |
| REST 路徑 |
POST/iceberg/v1/catalogs/{catalog}/namespaces |
| IAM 動作 |
glue：CreateDatabase |
| Lake Formation 許可 | ALL、DESCRIBE、SELECT |
| CloudTrail 事件 |
glue：CreateDatabase |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L256 |
考量與限制
-
目錄路徑參數必須遵循 字首和目錄路徑參數章節中所述的樣式。
-
只能建立單一層級命名空間。若要建立多層級命名空間，您必須反覆建立每個層級，並使用目錄路徑參數連接到該層級。
| 操作名稱 | StartCreateNamespaceTransaction |
| 類型 |
AWS Glue 擴充功能 API |
| REST 路徑 |
POST/extensions/v1/catalogs/{catalog}/namespaces |
| IAM 動作 |
glue：CreateDatabase |
| Lake Formation 許可 | ALL、DESCRIBE、SELECT |
| CloudTrail 事件 |
glue：CreateDatabase |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L256 |
考量和限制
-
目錄路徑參數必須遵循 字首和目錄路徑參數章節中所述的樣式。
-
您只能建立單一層級命名空間。若要建立多層級命名空間，您必須反覆建立每個層級，並使用目錄路徑參數連接到該層級。
-
API 是非同步的，並傳回交易 ID，您可以使用
CheckTransactionStatusAPI 呼叫進行追蹤。 -
只有在 API 呼叫在回應
use-extensions=true中包含 參數時，您才能呼叫此GetCatalogAPI。
| 操作名稱 | LoadNamespaceMetadata |
| 類型 |
Iceberg REST 目錄 API |
| REST 路徑 |
GET/iceberg/v1/catalogs/{catalog}/namespaces/{ns} |
| IAM 動作 |
glue：GetDatabase |
| Lake Formation 許可 | ALL、DESCRIBE、SELECT |
| CloudTrail 事件 |
glue：GetDatabase |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L302 |
| 操作名稱 | UpdateNamespaceProperties |
| 類型 |
Iceberg REST 目錄 API |
| REST 路徑 |
POST /iceberg/v1/catalogs/{catalog}/namespaces/{ns}/properties |
| IAM 動作 |
glue：UpdateDatabase |
| Lake Formation 許可 | ALL、ALTER |
| CloudTrail 事件 |
glue：UpdateDatabase |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L400 |
| 操作名稱 | DeleteNamespace |
| 類型 |
Iceberg REST 目錄 API |
| REST 路徑 |
DELETE/iceberg/v1/catalogs/{catalog}/namespces/{ns} |
| IAM 動作 |
glue：DeleteDatabase |
| Lake Formation 許可 | ALL、DROP |
| CloudTrail 事件 |
glue：DeleteDatabase |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L365 |
考量與限制
| 操作名稱 | StartDeleteNamespaceTransaction |
| 類型 |
AWS Glue 擴充功能 API |
| REST 路徑 |
DELETE /extensions/v1/catalogs/{catalog}/namespces/{ns} |
| IAM 動作 |
glue：DeleteDatabase |
| Lake Formation 許可 | ALL、DROP |
| CloudTrail 事件 |
glue：DeleteDatabase |
| 開啟 API 定義 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L85 |
考量和限制
| 操作名稱 | ListTables |
| 類型 |
Iceberg REST 目錄 API |
| REST 路徑 |
GET /iceberg/v1/catalogs/{catalog}/namespaces/{ns}/tables |
| IAM 動作 |
glue：GetTables |
| Lake Formation 許可 | ALL、SELECT、DESCRIBE |
| CloudTrail 事件 |
glue：GetTables |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L463 |
考量與限制
| 操作名稱 | CreateTable |
| 類型 |
Iceberg REST 目錄 API |
| REST 路徑 |
GET /iceberg/v1/catalogs/{catalog}/namespaces/{ns}/tables |
| IAM 動作 |
glue：CreateTable |
| Lake Formation 許可 | ALL、CREATE_TABLE |
| CloudTrail 事件 |
glue：CreateTable |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L497 |
考量與限制
| 操作名稱 | CreateTable |
| 類型 |
AWS Glue 擴充功能 API |
| REST 路徑 |
POST/extensions/v1/catalogs/{catalog}/namespaces/{ns}/tables |
| IAM 動作 |
glue：CreateTable |
| Lake Formation 許可 | ALL、CREATE_TABLE |
| CloudTrail 事件 |
glue：CreateTable |
| 開啟 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 是非同步的，並傳回交易 ID，您可以使用
CheckTransactionStatusAPI 呼叫進行追蹤。 -
只有在 API 呼叫指示
use-extensions=true回應時，才能使用GetCatalogAPI。
| 操作名稱 | LoadTable |
| Type |
AWS Glue 擴充功能 API |
| REST 路徑 |
GET /iceberg/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table} |
| IAM 動作 |
glue：GeTTable |
| Lake Formation 許可 | ALL、SELECT、DESCRIBE |
| CloudTrail 事件 |
glue：GetTable |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L616 |
考量事項
-
目錄路徑參數必須遵循 字首和目錄路徑參數章節中所述的樣式。
您只能在 REST Path 參數中指定單一層級命名空間。如需形成的詳細資訊，請參閱命名空間路徑參數一節。
-
CreateTable不支援使用預備。如果指定stageCreate查詢參數，操作將會失敗。這表示CREATE TABLE AS SELECT不支援 這類操作，使用者應該使用CREATE TABLE和 的組合INSERT INTO來解決此問題。 -
API 是非同步的，並傳回交易 ID，您可以使用
CheckTransactionStatusAPI 呼叫進行追蹤。 -
只有在 API 呼叫指示
use-extensions=true回應時，才能使用GetCatalogAPI。
| 操作名稱 | LoadTable |
| Type |
AWS Glue 擴充功能 API |
| REST 路徑 |
GET /extensions/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table} |
| IAM 動作 |
glue：GetTable |
| Lake Formation 許可 | ALL、SELECT、DESCRIBE |
| CloudTrail 事件 |
glue：GetTable |
| 開啟 API 定義 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L134 |
考量事項
-
目錄路徑參數必須遵循 字首和目錄路徑參數章節中所述的樣式。
您只能在 REST Path 參數中指定單一層級命名空間。如需形成的詳細資訊，請參閱命名空間路徑參數一節。
-
快照查詢參數僅支援
all模式。 -
與
LoadTableAPI 相比，ExtendedLoadTableAPI 有下列不同：不會嚴格強制執行要提供的所有欄位。
-
在回應的組態欄位中提供下列其他參數：
其他參數 組態鍵 描述 aws.server-side-capabilities.scan-planning
指示是否可以使用 PreparePlan 資料表和 PlanTable APIs掃描資料表。 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 擴充功能 API |
| REST 路徑 |
POST /extensions/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table}/preplan |
| IAM 動作 |
glue：GetTable |
| Lake Formation 許可 | ALL、SELECT、DESCRIBE |
| CloudTrail 事件 |
glue：GetTable |
| 開啟 API 定義 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L211 |
考量事項
| 操作名稱 | PlanTable |
| Type |
AWS Glue 擴充功能 API |
| REST 路徑 |
POST /extensions/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table}/plan |
| IAM 動作 |
glue：GetTable |
| Lake Formation 許可 | ALL、SELECT、DESCRIBE |
| CloudTrail 事件 |
glue：GetTable |
| 開啟 API 定義 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L243 |
考量事項
| 操作名稱 | TableExists |
| Type |
Iceberg REST 目錄 API |
| REST 路徑 |
HEAD/iceberg/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table} |
| IAM 動作 |
glue：GetTable |
| Lake Formation 許可 | ALL、SELECT、DESCRIBE |
| CloudTrail 事件 |
glue：GetTable |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L833 |
| 操作名稱 | UpdateTable |
| Type |
Iceberg REST 目錄 API |
| REST 路徑 |
POST /iceberg/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table} |
| IAM 動作 |
glue：UpdateTable |
| Lake Formation 許可 | ALL、ALTER |
| CloudTrail 事件 |
glue：UpdateTable |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L677 |
| 操作名稱 | 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 |
| 開啟 API 定義 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L154 |
考量事項
-
目錄路徑參數必須遵循 字首和目錄路徑參數章節中所述的樣式。
您只能在 REST Path 參數中指定單一層級命名空間。如需形成的詳細資訊，請參閱命名空間路徑參數一節。
-
API 是非同步的，並傳回交易 ID，您可以使用
CheckTransactionStatusAPI 呼叫進行追蹤。 -
RenamTable操作也可以透過此 API 執行。發生這種情況時，呼叫者也必須將 glue：CreateTable 或 LakeFormation CREATE_TABLE 許可，才能重新命名資料表。 -
只有在 API 回應包含 時，您才能使用此
ExtendedLoadTableAPIaws.server-side-capabilities.scan-planning=true。
| 操作名稱 | DeleteTable |
| Type |
Iceberg REST 目錄 API |
| REST 路徑 |
DELETE/iceberg/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table} |
| IAM 動作 |
glue：DeleteTable |
| Lake Formation 許可 | ALL、DROP |
| CloudTrail 事件 |
glue：DeleteTable |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L793 |
考量事項
-
目錄路徑參數應遵循 字首和目錄路徑參數章節中所述的樣式。
您只能在 REST Path 參數中指定單一層級命名空間。如需形成的詳細資訊，請參閱命名空間路徑參數一節。
-
DeleteTableAPI 操作支援清除選項。當清除設定為 時true，資料表資料會被刪除，否則不會刪除資料。對於 Amazon S3 中的資料表，操作不會刪除資料表資料。當資料表存放在 Amazon S3 和purge = TRUE,時，操作會失敗。對於存放在 Amazon Redshift 受管儲存體中的資料表，操作會刪除資料表資料，類似於 Amazon Redshift 中
DROP TABLE的行為。當資料表存放在 Amazon Redshift 和 時，操作會失敗purge = FALSE。 -
不支援
purgeRequest=true。
| 操作名稱 | StartDeleteTableTransaction |
| Type |
AWS Glue 擴充功能 API |
| REST 路徑 |
DELETE /extensions/v1/catalogs/{catalog}/namespaces/{ns}/tables/{table} |
| IAM 動作 |
glue：DeleteTable |
| Lake Formation 許可 | ALL、DROP |
| CloudTrail 事件 |
glue：DeleteTable |
| 開啟 API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L793 |
考量事項
| 操作名稱 | CheckTransactionStatus |
| Type |
AWS Glue 擴充功能 API |
| REST 路徑 |
POST/extensions/v1/transactions/status |
| IAM 動作 |
與啟動交易的動作相同的許可 |
| Lake Formation 許可 | 與啟動交易的動作相同的許可 |
| 開啟 API 定義 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L273 |
考量事項
-
目錄路徑參數必須遵循 字首和目錄路徑參數章節中所述的樣式。
