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

# 存取 Data Catalog
<a name="access_catalog"></a>

 您可以使用 AWS Glue Data Catalog （資料目錄） 來探索和了解您的資料。Data Catalog 提供一致的方法來維護結構描述定義、資料類型、位置及其他中繼資料。您可以使用下列方法來存取 Data Catalog：
+ AWS Glue 主控台 – 您可以透過以 Web 為基礎的使用者介面 AWS Glue 主控台存取和管理 Data Catalog。主控台可讓您瀏覽和搜尋資料庫、資料表及其關聯的中繼資料，以及建立、更新和刪除中繼資料定義。
+ AWS Glue 編目程式 – 爬蟲程式是自動掃描資料來源並將中繼資料填入 Data Catalog 的程式。您可以建立和執行爬蟲程式，從各種來源探索和分類資料，例如 Amazon S3、Amazon RDS、Amazon DynamoDB Amazon CloudWatch、 和 JDBC 相容關聯式資料庫，例如 MySQL、PostgreSQL，以及數個非AWS 來源，例如 Snowflake 和 Google BigQuery。
+ AWS Glue APIs – 您可以使用 AWS Glue APIs 以程式設計方式存取 Data Catalog。這些 API 可讓您以程式設計方式與 Data Catalog 互動，從而實現自動化並與其他應用程式和服務整合。
+ AWS Command Line Interface (AWS CLI) – 您可以使用 從命令列 AWS CLI 存取和管理 Data Catalog。CLI 提供用於建立、更新和刪除中繼資料定義以及查詢和擷取中繼資料資訊的命令。
+ 與其他 AWS 服務的整合 – Data Catalog 與各種其他服務整合 AWS ，可讓您存取和利用存放在 目錄中的中繼資料。例如，您可以使用 Amazon Athena 查詢使用 Data Catalog 中中繼資料的資料來源，並使用 AWS Lake Formation 管理 Data Catalog 資源的資料存取和管理。

**Topics**
+ [

# 使用 AWS Glue Iceberg REST 端點連線至 Data Catalog
](connect-glu-iceberg-rest.md)
+ [

# 使用 AWS Glue Iceberg REST 延伸端點連線至 Data Catalog
](connect-glue-iceberg-rest-ext.md)
+ [

# AWS Glue Apache Iceberg 規格的 REST APIs
](iceberg-rest-apis.md)
+ [

# 從獨立 Spark 應用程式連線至 Data Catalog
](connect-gludc-spark.md)
+ [

# Amazon Redshift 與 Apache Iceberg 之間的資料映射
](data-mapping-rs-iceberg.md)
+ [

# 使用 AWS Glue Iceberg REST Catalog APIs時的考量和限制
](limitation-glue-iceberg-rest-api.md)

# 使用 AWS Glue Iceberg REST 端點連線至 Data Catalog
<a name="connect-glu-iceberg-rest"></a>

 AWS Glue的 Iceberg REST 端點支援 Apache Iceberg REST 規格中指定的 API 操作。使用 Iceberg REST 用戶端，您可以將在分析引擎上執行的應用程式連線到 Data Catalog 中託管的 REST 目錄。

 端點同時支援 Apache Iceberg 資料表規格 – v1 和 v2，預設為 v2。使用 Iceberg 資料表 v1 規格時，您必須在 API 呼叫中指定 v1。使用 API 操作，您可以存取儲存在 Amazon S3 物件儲存體和 Amazon S3 資料表儲存體中的 Iceberg 資料表。

**端點組態**

您可以使用 服務端點存取 AWS Glue Iceberg REST 目錄。如需區域特定的端點，請參閱 [AWS Glue 服務端點參考指南](https://docs.aws.amazon.com/general/latest/gr/glue.html#glue_region)。例如，在 us-east-1 區域中連線至 AWS Glue 時，您需要設定端點 URI 屬性，如下所示：

```
Endpoint : https://glue.us-east-1.amazonaws.com/iceberg
```

**其他組態屬性** – 使用 Iceberg 用戶端將 Spark 等分析引擎連線至服務端點時，您必須指定下列應用程式組態屬性：

```
catalog_name = "mydatacatalog"
aws_account_id = "123456789012"
aws_region = "us-east-1"
spark = SparkSession.builder \
    ... \
    .config("spark.sql.defaultCatalog", catalog_name) \
    .config(f"spark.sql.catalog.{catalog_name}", "org.apache.iceberg.spark.SparkCatalog") \
    .config(f"spark.sql.catalog.{catalog_name}.type", "rest") \
    .config(f"spark.sql.catalog.{catalog_name}.uri", "https://glue.{aws_region}.amazonaws.com/iceberg") \
    .config(f"spark.sql.catalog.{catalog_name}.warehouse", "{aws_account_id}") \
    .config(f"spark.sql.catalog.{catalog_name}.rest.sigv4-enabled", "true") \
    .config(f"spark.sql.catalog.{catalog_name}.rest.signing-name", "glue") \    
    .config("spark.sql.extensions","org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions") \
    .getOrCreate()
```

AWS Glue Iceberg 端點` https://glue.us-east-1.amazonaws.com/iceberg`支援下列 Iceberg REST APIs：
+ GetConfig
+ ListNamespaces
+ CreateNamespace
+ LoadNamespaceMetadata
+ UpdateNamespaceProperties
+ DeleteNamespace
+ ListTables
+ CreateTable
+ LoadTable
+ TableExists
+ UpdateTable
+ DeleteTable

## 字首和目錄路徑參數
<a name="prefix-catalog-path-parameters"></a>

Iceberg REST 目錄 API 在其請求 URL 中具有自由格式字首。例如，`ListNamespaces`API 呼叫使用 `GET/v1/{prefix}/namespaces` URL format. AWS Glue prefix 一律遵循 `/catalogs/{catalog}`結構，以確保 REST 路徑符合 AWS Glue 多目錄階層。可以根據下列規則衍生 `{catalog}` 路徑參數：


| **存取模式** |  **Glue 目錄 ID 樣式**  |  **字首樣式**  | **預設目錄 ID 範例** |  **範例 REST 路由**  | 
| --- | --- | --- | --- | --- | 
|  存取目前帳戶中的預設目錄  | 非必要 | : |  不適用  |  GET /v1/catalogs/:/namespaces  | 
|  存取特定帳戶中的預設目錄  | accountID | accountID | 111122223333 | GET /v1/catalogs/111122223333/namespaces | 
|  存取目前帳戶中的巢狀目錄  |  catalog1/catalog2  |  catalog1/catalog2  |  rmscatalog1:db1  |  GET /v1/catalogs/rmscatalog1:db1/namespaces  | 
|  存取特定帳戶中的巢狀目錄  |  accountId:catalog1/catalog2  |  accountId:catalog1/catalog2  |  123456789012/rmscatalog1:db1  |  GET /v1/catalogs/123456789012:rmscatalog1:db1/namespaces  | 

只有在您直接呼叫 REST API 時，才需要此目錄 ID 至字首映射。當您透過 引擎使用 AWS Glue Iceberg REST 目錄 APIs 時，您需要在 Iceberg REST AWS Glue 目錄 API 設定的 `warehouse` 參數中指定目錄 ID，或在 AWS Glue 延伸 API 設定的 `glue.id` 參數中指定目錄 ID。例如，請參閱[將 Iceberg 叢集與 Spark 搭配使用](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-iceberg-use-spark-cluster.html)，以了解如何將其與 EMR Spark 搭配使用。

## 命名空間路徑參數
<a name="ns-path-param"></a>

Iceberg REST 目錄 API 路徑中的命名空間可以具有多個層級。但是， AWS Glue 僅支援單一層級命名空間。若要存取多層目錄階層中的命名空間，您可以連線到命名空間上方的多層目錄，以參考命名空間。這允許支援 的 3 部分表示法的任何查詢引擎`catalog.namespace.table`存取多層級目錄階層中的物件 AWS Glue，與使用多層級命名空間相比，沒有相容性問題。

# 使用 AWS Glue Iceberg REST 延伸端點連線至 Data Catalog
<a name="connect-glue-iceberg-rest-ext"></a>

 AWS Glue Iceberg REST 延伸端點提供額外的 APIs，這些 API 不存在於 Apache Iceberg REST 規格中，並提供伺服器端掃描規劃功能。當您存取儲存在 Amazon Redshift 受管儲存體中的資料表時，會使用這些額外的 API。您可以使用 Apache Iceberg AWS Glue Data Catalog 延伸模組從應用程式存取端點。

**端點組態** – 可使用服務端點存取 Redshift 受管儲存中具有資料表的目錄。如需區域特定的端點，請參閱 [AWS Glue 服務端點參考指南](https://docs.aws.amazon.com/general/latest/gr/glue.html#glue_region)。例如，在 us-east-1 AWS Glue 區域中連線至 時，您需要設定端點 URI 屬性，如下所示：

```
Endpoint : https://glue.us-east-1.amazonaws.com/extensions
```

```
catalog_name = "myredshiftcatalog"
aws_account_id = "123456789012"
aws_region = "us-east-1"
spark = SparkSession.builder \
    .config("spark.sql.defaultCatalog", catalog_name) \
    .config(f"spark.sql.catalog.{catalog_name}", "org.apache.iceberg.spark.SparkCatalog") \
    .config(f"spark.sql.catalog.{catalog_name}.type", "glue") \
    .config(f"spark.sql.catalog.{catalog_name}.glue.id", "{123456789012}:redshiftnamespacecatalog/redshiftdb") \
    .config("spark.sql.extensions","org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions") \
    .getOrCreate()
```

# AWS Glue Apache Iceberg 規格的 REST APIs
<a name="iceberg-rest-apis"></a>

本節包含 AWS Glue Iceberg REST 目錄和 AWS Glue 延伸 APIs的規格，以及使用這些 APIs時的考量事項。

對 AWS Glue Data Catalog 端點的 API 請求會使用 AWS Signature 第 4 版 (SigV4) 進行身分驗證。如需 [AWS API 請求的詳細資訊，請參閱簽章版本 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 一節 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\$1CATALOG – 需要建立目錄 
+ CREATE\$1DATABASE – 需要建立資料庫
+ CREATE\$1TABLE – 需要建立資料表
+ DELETE – 需要從資料表刪除資料
+ DESCRIBE – 需要讀取中繼資料 
+ DROP – 需要捨棄/刪除資料表或資料庫
+ INSERT – 當主體需要將資料插入資料表時需要
+ SELECT – 當主體需要從資料表中選取資料時需要

如需詳細資訊，請參閱《 AWS Lake Formation 開發人員指南》中的 [Lake Formation 許可參考](https://docs.aws.amazon.com/lake-formation/latest/dg/lf-permissions-reference.html)。

# GetConfig
<a name="get-config"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | 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\$1L67 | 

****考量和限制****
+ `warehouse` 查詢參數必須設定為 AWS Glue 目錄 ID。如果未設定，則會使用目前帳戶中的根目錄來傳回回應。如需詳細資訊，請參閱[字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)。

# GetCatalog
<a name="get-catalog"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | GetCatalog | 
| 類型 |  AWS Glue 延伸 API  | 
| REST 路徑 |  GET/extensions/v1/catalogs/\$1catalog\$1  | 
| 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\$1L40 | 

****考量和限制****
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。

# ListNamespaces
<a name="list-ns"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | ListNamespaces | 
| 類型 |  Iceberg REST Catalog API  | 
| REST 路徑 |  GET/iceberg/v1/catalogs/\$1catalog\$1/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\$1L205 | 

****考量和限制****
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只會顯示下一級別的命名空間。要列出更深層的命名空間，請在目錄路徑參數中指定巢狀目錄 ID。

# CreateNamespace
<a name="create-ns"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | CreateNamespace | 
| 類型 |  Iceberg REST Catalog API  | 
| REST 路徑 |  POST/iceberg/v1/catalogs/\$1catalog\$1/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\$1L256 | 

****考量和限制****
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能建立單一層級命名空間。若要建立多層級命名空間，您必須反覆建立每個層級，並使用目錄路徑參數連接至該層級。

# StartCreateNamespaceTransaction
<a name="start-create-ns-transaction"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | StartCreateNamespaceTransaction | 
| 類型 |  AWS Glue 延伸項目 API  | 
| REST 路徑 |  POST/extensions/v1/catalogs/\$1catalog\$1/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\$1L256 | 

****考量和限制****
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能建立單一層級命名空間。若要建立多層級命名空間，必須反覆建立每個層級，並使用目錄路徑參數連接至該層級。
+ API 為非同步，並傳回可用於使用 `CheckTransactionStatus` API 呼叫進行追蹤的交易 ID。
+  只有當 `GetCatalog` API 呼叫在回應中包含參數 `use-extensions=true` 時，才能呼叫此 API。

## LoadNamespaceMetadata
<a name="load-ns-metadata"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | LoadNamespaceMetadata | 
| 類型 |  Iceberg REST Catalog API  | 
| REST 路徑 |  GET/iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1  | 
| 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\$1L302 | 

****考量和限制****
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱 [命名空間路徑參數](connect-glu-iceberg-rest.md#ns-path-param) 一節。

## UpdateNamespaceProperties
<a name="w2aac20c29c16c21c13"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | UpdateNamespaceProperties | 
| 類型 |  Iceberg REST Catalog API  | 
| REST 路徑 |  POST /iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/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\$1L400 | 

****考量和限制****
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱 [命名空間路徑參數](connect-glu-iceberg-rest.md#ns-path-param) 一節。

# DeleteNamespace
<a name="delete-ns"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | DeleteNamespace | 
| 類型 |  Iceberg REST Catalog API  | 
| REST 路徑 |  DELETE/iceberg/v1/catalogs/\$1catalog\$1/namespces/\$1ns\$1  | 
| 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\$1L365 | 

****考量和限制****
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱[命名空間路徑參數](connect-glu-iceberg-rest.md#ns-path-param)一節。
+ 如果資料庫中有物件，操作將會失敗。
+ API 為非同步，並傳回可用於使用 `CheckTransactionStatus` API 呼叫進行追蹤的交易 ID。
+  只有 `GetCatalog` API 呼叫在回應中指示 `use-extensions=true` 時，才能使用 API。

# StartDeleteNamespaceTransaction
<a name="start-delete-ns-transaction"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | StartDeleteNamespaceTransaction | 
| 類型 |  AWS Glue 延伸項目 API  | 
| REST 路徑 |  DELETE /extensions/v1/catalogs/\$1catalog\$1/namespces/\$1ns\$1  | 
| 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\$1L85 | 

****考量和限制****
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱[命名空間路徑參數](connect-glu-iceberg-rest.md#ns-path-param)一節。
+ 如果資料庫中有物件，操作將會失敗。
+ API 為非同步，並傳回可用於使用 `CheckTransactionStatus` API 呼叫進行追蹤的交易 ID。
+  只有 `GetCatalog` API 呼叫在回應中指示 `use-extensions=true` 時，才能使用 API。

# ListTables
<a name="list-tables"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | ListTables | 
| 類型 |  Iceberg REST Catalog API  | 
| REST 路徑 |  GET /iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/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\$1L463 | 

****考量和限制****
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱[命名空間路徑參數](connect-glu-iceberg-rest.md#ns-path-param)一節。
+ 將列出包括非 Iceberg 資料表在內的所有資料表。若要確定資料表是否可以載入為 Iceberg 資料表，請呼叫 `LoadTable`操作。

# CreateTable
<a name="create-table"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | CreateTable | 
| 類型 |  Iceberg REST Catalog API  | 
| REST 路徑 |  GET /iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables  | 
| IAM 動作 |  glue:CreateTable  | 
| Lake Formation 許可 | ALL, CREATE\$1TABLE | 
| CloudTrail 事件 |  glue:CreateTable  | 
| Open API 定義 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L497 | 

****考量和限制****
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱[命名空間路徑參數](connect-glu-iceberg-rest.md#ns-path-param)一節。
+ 不支援具有暫存的 `CreateTable`。如果指定 `stageCreate` 查詢參數，操作將會失敗。這表示不支援 `CREATE TABLE AS SELECT` 等操作，您可以使用 `CREATE TABLE` 和 `INSERT INTO` 的組合作為解決方法。
+ `CreateTable` API 操作不支援選項 `state-create = TRUE`。

# StartCreateTableTransaction
<a name="start-create-table-transaction"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | CreateTable | 
| 類型 |  AWS Glue 延伸項目 API  | 
| REST 路徑 |  POST/extensions/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables  | 
| IAM 動作 |  glue:CreateTable  | 
| Lake Formation 許可 | ALL, CREATE\$1TABLE | 
| CloudTrail 事件 |  glue:CreateTable  | 
| Open API 定義 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml\$1L107 | 

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

# LoadTable
<a name="load-table"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | LoadTable | 
| Type |  Iceberg REST Catalog API  | 
| REST 路徑 |  GET /iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| 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\$1L616 | 

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

# ExtendedLoadTable
<a name="extended-load-table"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | LoadTable | 
| Type |  AWS Glue 延伸項目 API  | 
| REST 路徑 |  GET /extensions/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| 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\$1L134 | 

**考量事項**
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱[命名空間路徑參數](connect-glu-iceberg-rest.md#ns-path-param)一節。
+ 快照查詢參數僅支援 `all` 模式。
+ 與 `LoadTable` API 相比，`ExtendedLoadTable` API 有下列不同：
  +  並不嚴格要求所有字段都可用。
  + 在回應的組態欄位中提供下列額外參數：  
**額外參數**    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/extended-load-table.html)

# PreplanTable
<a name="preplan-table"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | PreplanTable | 
| Type |  AWS Glue 延伸項目 API  | 
| REST 路徑 |  POST /extensions/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1/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\$1L211 | 

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

# PlanTable
<a name="plan-table"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | PlanTable | 
| Type |  AWS Glue 延伸項目 API  | 
| REST 路徑 |  POST /extensions/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1/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\$1L243 | 

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

# TableExists
<a name="table-exists"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | TableExists | 
| Type |  Iceberg REST Catalog API  | 
| REST 路徑 |  HEAD/iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| 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\$1L833 | 

**考量事項**
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱 [命名空間路徑參數](connect-glu-iceberg-rest.md#ns-path-param) 一節。

# UpdateTable
<a name="update-table"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | UpdateTable | 
| Type |  Iceberg REST Catalog API  | 
| REST 路徑 |  POST /iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| 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\$1L677 | 

**考量事項**
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱 [命名空間路徑參數](connect-glu-iceberg-rest.md#ns-path-param) 一節。

# StartUpdateTableTransaction
<a name="start-update-table-transaction"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | StartUpdateTableTransaction | 
| Type | AWS Glue 延伸 API | 
| REST 路徑 |  POST/extensions/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| 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\$1L154 | 

**考量事項**
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱[命名空間路徑參數](connect-glu-iceberg-rest.md#ns-path-param)一節。
+ API 為非同步，並傳回可用於使用 `CheckTransactionStatus` API 呼叫進行追蹤的交易 ID。
+  也可以透過此 API 執行 `RenamTable` 操作。發生這種情況時，呼叫者也必須擁有 ahve glue：CreateTable 或 LakeFormation CREATE\$1TABLE 許可，才能重新命名資料表。
+  只有在 `ExtendedLoadTable` API 回應包含 `aws.server-side-capabilities.scan-planning=true` 時，才能使用此 API。

# DeleteTable
<a name="delete-table"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | DeleteTable | 
| Type |  Iceberg REST Catalog API  | 
| REST 路徑 |  DELETE/iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| 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\$1L793 | 

**考量事項**
+ 目錄路徑參數應遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 一節中所述的樣式。
+ 只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱[命名空間路徑參數](connect-glu-iceberg-rest.md#ns-path-param)一節。
+ `DeleteTable` API 操作支援清除選項。在清除設定為 `true` 時，資料表資料會刪除，否則不會刪除資料。對於 Amazon S3 中的資料表，操作不會刪除資料表資料。當資料表儲存在 Amazon S3 中且 `purge = TRUE,` 時，操作會失敗。

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

# StartDeleteTableTransaction
<a name="start-delete-table-transaction"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | StartDeleteTableTransaction | 
| Type |  AWS Glue 延伸項目 API  | 
| REST 路徑 |  DELETE /extensions/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| 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\$1L793 | 

**考量事項**
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。
+ 只能在 REST 路徑參數中指定單一層級命名空間。如需詳細資訊，請參閱[命名空間路徑參數](connect-glu-iceberg-rest.md#ns-path-param)一節。
+ 不支援 `purgeRequest=false`。
+  API 是非同步的，並傳回可透過 `CheckTransactionStatus` 追蹤的交易 ID。

# CheckTransactionStatus
<a name="check-transaction-status"></a>


**一般資訊**  

|  |  | 
| --- |--- |
| 操作名稱 | CheckTransactionStatus | 
| Type |  AWS Glue 延伸項目 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\$1L273 | 

**考量事項**
+ 目錄路徑參數必須遵循 [字首和目錄路徑參數](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters) 部分中所述的樣式。

# 從獨立 Spark 應用程式連線至 Data Catalog
<a name="connect-gludc-spark"></a>

您可以使用 Apache Iceberg 連接器從獨立應用程式連線至 Data Catalog。

1. 為 Spark 應用程式建立 IAM 角色。

1. 使用 AWS Glue Iceberg 連接器連接到 Iceberg Rest 端點。

   ```
   # configure your application. Refer to https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html for best practices on configuring environment variables.
   export AWS_ACCESS_KEY_ID=$(aws configure get appUser.aws_access_key_id)
   export AWS_SECRET_ACCESS_KEY=$(aws configure get appUser.aws_secret_access_key)
   export AWS_SESSION_TOKEN=$(aws configure get appUser.aws_secret_token)
   
   export AWS_REGION=us-east-1
   export REGION=us-east-1
   export AWS_ACCOUNT_ID = {specify your aws account id here}
   
   ~/spark-3.5.3-bin-hadoop3/bin/spark-shell \
       --packages org.apache.iceberg:iceberg-spark-runtime-3.4_2.12:1.6.0 \
       --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://glue.us-east-1.amazonaws.com/iceberg" \
       --conf "spark.sql.catalog.spark_catalog.warehouse = {AWS_ACCOUNT_ID}" \
       --conf "spark.sql.catalog.spark_catalog.rest.sigv4-enabled=true" \
       --conf "spark.sql.catalog.spark_catalog.rest.signing-name=glue" \
       --conf "spark.sql.catalog.spark_catalog.rest.signing-region=us-east-1" \
       --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"
   ```

1. 查詢 Data Catalog 中的資料。

   ```
   spark.sql("create database myicebergdb").show()
   spark.sql("""CREATE TABLE myicebergdb.mytbl (name string) USING iceberg location 's3://bucket_name/mytbl'""")
   spark.sql("insert into myicebergdb.mytbl values('demo') ").show()
   ```

# Amazon Redshift 與 Apache Iceberg 之間的資料映射
<a name="data-mapping-rs-iceberg"></a>

Redshift 和 Iceberg 支援各種資料類型。下列相容性矩陣概述在這兩個資料系統之間映射資料時的支援和限制。如需個別資料系統中支援的資料類型的詳細資訊，請參閱 [Amazon Redshift 資料類型](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html)和 [Apache Iceberg 資料表規格](https://iceberg.apache.org/spec/#primitive-types)。


| Redshift 資料類型 | 別名 | Iceberg 資料類型 | 
| --- | --- | --- | 
| SMALLINT | INT2 | int | 
| INTEGER | INT、INT4 | int | 
| BIGINT | INT8 | long | 
| DECIMAL | NUMERIC | decimal | 
| REAL | FLOAT4 | float | 
| REAL | FLOAT4 | float | 
| DOUBLE PRECISION | FLOAT8、FLOAT | double | 
| CHAR | CHARACTER、NCHAR | string | 
| VARCHAR | CHARACTER VARYING、NVARCHAR | string | 
| BPCHAR |  | string | 
| TEXT |  | string | 
| DATE |  | date | 
| TIME | TIME WITHOUT TIMEZONE | time | 
| TIME | TIME WITH TIMEZONE | 不支援 | 
| TIMESTAMP | TIMESTAMP WITHOUT TIMEZONE | TIMESTAMP | 
| TIMESTAMPZ | TIMESTAMP WITH TIMEZONE | TIMESTAMPZ | 
| INTERVAL YEAR TO MONTH |  | 不支援 | 
| INTERVAL DAY TO SECOND |  | 不支援 | 
| BOOLEAN | BOOL | bool | 
| HLLSKETCH |  | 不支援 | 
| SUPER |  | 不支援 | 
| VARBYTE | VARBINARY、BINARY VARYING | binary | 
| GEOMETRY |  | 不支援 | 
| GEOGRAPHY |  | 不支援 | 

# 使用 AWS Glue Iceberg REST Catalog APIs時的考量和限制
<a name="limitation-glue-iceberg-rest-api"></a>

以下是使用 Apache Iceberg REST Catalog 資料定義語言 (DDL) 操作行為時的考量和限制。

**考量事項**
+  **`RenameTable` API 行為** – Amazon Redshift 中的資料表支援 `RenameTable` 操作，但 Amazon S3 中不支援。
+  **Amazon Redshift 中命名空間和資料表的 DDL 操作** – Amazon Redshift 中命名空間和資料表的建立、更新、刪除操作是非同步操作，因為其取決於 Amazon Redshift 受管工作群組何時可用，以及是否有衝突的 DDL 和 DML 交易正在進行，並且操作必須等待鎖定，然後再嘗試遞交變更。

**限制**
+  AWS Glue Iceberg REST Catalog 不支援在 Apache Iceberg REST 規格中檢視 APIs。