AWS Glue Apache Iceberg 用の REST API の仕様 - AWS Glue

AWS Glue Apache Iceberg 用の REST API の仕様

このセクションでは、AWS Glue Iceberg REST カタログと AWS Glue 拡張 API に関する仕様と、これらの API を使用する際の考慮事項について説明します。

AWS Glue Data Catalog エンドポイントへの API リクエストは、AWS Signature Version 4 (SigV4) を使用して認証されます。AWS SigV4 の詳細については「API リクエストに対する AWS Signature Version 4」のセクションを参照してください。

AWS Glue サービスエンドポイントと AWS Glue メタデータにアクセスする場合、アプリケーションは glue:getCatalog IAM アクションを必要とする IAM ロールを引き受けます。

データカタログとそのオブジェクトへのアクセスは、IAM、Lake Formation、または Lake Formation ハイブリッドモードのアクセス許可を使用して管理できます。

データカタログのフェデレーティッドカタログには、Lake Formation に登録されたデータロケーションがあります。Lake Formation は Data Catalog と連動して、データカタログに対するユーザーアクセスを管理するためのデータベーススタイルのアクセス許可を提供します。

IAM、AWS Lake Formation、Lake Formation のいずれかのハイブリッドモードのアクセス許可を使用することで、デフォルトのカタログデータとそのオブジェクトへのアクセスを管理できます。

Lake Formation のマネージド型オブジェクトでデータを作成、挿入、または削除するには、IAM ユーザーまたはロールに特定のアクセス許可を設定する必要があります。

  • CREATE_CATALOG – カタログの作成に必要

  • CREATE_DATABASE – データベースの作成に必要

  • CREATE_TABLE – テーブルの作成に必要

  • DELETE – テーブルからのデータの削除に必要

  • DESCRIBE – メタデータの読み取りに必要

  • DROP – テーブルまたはデータベースのドロップ/削除に必要

  • INSERT – プリンシパルがデータをテーブルに挿入する必要がある場合に必要

  • SELECT – プリンシパルがテーブルからデータを選択する必要がある場合に必要

詳細については、「AWS Lake Formation デベロッパーガイド」の「Lake Formation permissions reference」を参照してください。

一般情報
オペレーション名 GetConfig
Type

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
Type

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
Type

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
Type

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
Type

AWS Glue 拡張機能 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 を返します。

  • この API を呼び出すことができるのは、GetCatalog API コールにレスポンスの use-extensions=true パラメータが含まれている場合のみです。

一般情報
オペレーション名 LoadNamespaceMetadata
Type

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
考慮事項と制限事項
一般情報
オペレーション名 UpdateNamespaceProperties
Type

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
考慮事項と制限事項
一般情報
オペレーション名 DeleteNamespace
Type

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 Path パラメータでは、単一レベルの名前空間のみを指定できます。詳細については「名前空間パスパラメータ」セクションを参照してください。

  • データベースにオブジェクトがある場合、オペレーションは失敗します。

  • API は非同期で、CheckTransactionStatus API コールを使用して追跡するために使用できるトランザクション ID を返します。

  • API は、GetCatalog API コールがレスポンスで use-extensions=true を示す場合にのみ使用できます。

一般情報
オペレーション名 StartDeleteNamespaceTransaction
Type

AWS Glue 拡張機能 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 Path パラメータでは、単一レベルの名前空間のみを指定できます。詳細については「名前空間パスパラメータ」セクションを参照してください。

  • データベースにオブジェクトがある場合、オペレーションは失敗します。

  • API は非同期で、CheckTransactionStatus API コールを使用して追跡するために使用できるトランザクション ID を返します。

  • API は、GetCatalog API コールがレスポンスで use-extensions=true を示す場合にのみ使用できます。

一般情報
オペレーション名 ListTables
Type

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 Path パラメータでは、単一レベルの名前空間のみを指定できます。詳細については「名前空間パスパラメータ」セクションを参照してください。

  • Iceberg 以外のテーブルを含むすべてのテーブルが一覧表示されます。テーブルを Iceberg テーブルとしてロードできるかどうかを確認するには、 LoadTable オペレーションを呼び出します。

一般情報
オペレーション名 CreateTable
Type

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 Path パラメータでは、単一レベルの名前空間のみを指定できます。詳細については「名前空間パスパラメータ」セクションを参照してください。

  • ステージングを使用した CreateTable はサポートされていません。stageCreate クエリパラメータを指定するとオペレーションは失敗します。CREATE TABLE AS SELECT のようなオペレーションはサポートされていないため、回避策として CREATE TABLE と INSERT INTO の組み合わせを使用できます。

  • CreateTable API オペレーションはオプション state-create = TRUE をサポートしていません。

一般情報
オペレーション名 CreateTable
Type

AWS Glue 拡張機能 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 Path パラメータでは、単一レベルの名前空間のみを指定できます。詳細については「名前空間パスパラメータ」セクションを参照してください。

  • ステージングを使用した CreateTable はサポートされていません。stageCreate クエリパラメータを指定するとオペレーションは失敗します。CREATE TABLE AS SELECT のようなオペレーションはサポートされていないため、ユーザーは問題を回避するために CREATE TABLE と INSERT INTO を組み合わせて使用する必要があります。

  • API は非同期で、CheckTransactionStatus API コールを使用して追跡するために使用できるトランザクション ID を返します。

  • API は、GetCatalog API コールがレスポンスで use-extensions=true を示す場合にのみ使用できます。

一般情報
オペレーション名 LoadTable
タイプ

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 Path パラメータでは、単一レベルの名前空間のみを指定できます。詳細については「名前空間パスパラメータ」セクションを参照してください。

  • ステージングを使用した CreateTable はサポートされていません。stageCreate クエリパラメータを指定するとオペレーションは失敗します。CREATE TABLE AS SELECT のようなオペレーションはサポートされていないため、ユーザーは問題を回避するために CREATE TABLE と INSERT INTO を組み合わせて使用する必要があります。

  • API は非同期で、CheckTransactionStatus API コールを使用して追跡するために使用できるトランザクション ID を返します。

  • API は、GetCatalog API コールがレスポンスで use-extensions=true を示す場合にのみ使用できます。

一般情報
オペレーション名 LoadTable
タイプ

AWS Glue 拡張機能 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 Path パラメータでは、単一レベルの名前空間のみを指定できます。詳細については「名前空間パスパラメータ」セクションを参照してください。

  • スナップショットクエリパラメータでは 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
タイプ

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
Open API の定義 https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L211
考慮事項

  • カタログパスパラメータは、「プレフィックスとカタログパスパラメータ」セクションで説明されているスタイルに従う必要があります。

  • REST Path パラメータでは、単一レベルの名前空間のみを指定できます。詳細については「名前空間パスパラメータ」セクションを参照してください。

  • この API の呼び出し元は、ページトークンに基づいて、取得する残りの結果があるかどうかを常に判断する必要があります。サーバー側がまだ処理中で指定された応答時間内に結果を生成できない場合、ページ分割トークンを含む空白のページが返されることがあります。

  • この API は、API ExtendedLoadTable レスポンスに aws.server-side-capabilities.scan-planning=true が含まれている場合にのみ使用できます。

一般情報
オペレーション名 PlanTable
タイプ

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
Open API の定義 https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml#L243
考慮事項

  • カタログパスパラメータは、「プレフィックスとカタログパスパラメータ」セクションで説明されているスタイルに従う必要があります。

  • REST Path パラメータでは、単一レベルの名前空間のみを指定できます。詳細については「名前空間パスパラメータ」セクションを参照してください。

  • この API の呼び出し元は、ページトークンに基づいて、取得する残りの結果があるかどうかを常に判断する必要があります。サーバー側がまだ処理中で指定された応答時間内に結果を生成できない場合、ページ分割トークンを含む空白のページが返されることがあります。

  • この API は、API ExtendedLoadTable レスポンスに aws.server-side-capabilities.scan-planning=true が含まれている場合にのみ使用できます。

一般情報
オペレーション名 TableExists
タイプ

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
考慮事項
一般情報
オペレーション名 UpdateTable
タイプ

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
考慮事項
一般情報
オペレーション名 StartUpdateTableTransaction
タイプ 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 Path パラメータでは、単一レベルの名前空間のみを指定できます。詳細については「名前空間パスパラメータ」セクションを参照してください。

  • API は非同期で、CheckTransactionStatus API コールを使用して追跡するために使用できるトランザクション ID を返します。

  • この API を使用して RenamTable オペレーションを実行することもできます。この場合、呼び出し元は、名前を変更するテーブルの glue:CreateTable または LakeFormation CREATE_TABLE アクセス許可も取得する必要があります。

  • この API は、API ExtendedLoadTable レスポンスに aws.server-side-capabilities.scan-planning=true が含まれている場合にのみ使用できます。

一般情報
オペレーション名 DeleteTable
タイプ

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 Path パラメータでは、単一レベルの名前空間のみを指定できます。詳細については「名前空間パスパラメータ」セクションを参照してください。

  • DeleteTable API オペレーションはパージオプションをサポートします。パージが true に設定されている場合、テーブルデータは削除されます。設定されていない場合は削除されません。Amazon S3 のテーブルの場合、このオペレーションでテーブルデータが削除されることはありません。テーブルが Amazon S3 と purge = TRUE, に保存されている場合、このオペレーションは失敗します。

    テーブルが Amazon Redshift マネージドストレージに保存されている場合、Amazon Redshift での DROP TABLE の動作と同様に、このオペレーションによりテーブルデータは削除されます。テーブルが Amazon Redshift と purge = FALSE に保存されている場合、このオペレーションは失敗します。

  • purgeRequest=true はサポートされていません。

一般情報
オペレーション名 StartDeleteTableTransaction
タイプ

AWS Glue 拡張機能 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 Path パラメータでは、単一レベルの名前空間のみを指定できます。詳細については「名前空間パスパラメータ」セクションを参照してください。

  • purgeRequest=false はサポートされていません。

  • API は非同期で、CheckTransactionStatus を介して追跡できるトランザクション ID を返します。

一般情報
オペレーション名 CheckTransactionStatus
タイプ

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#L273
考慮事項