# Amazon S3 Tables Iceberg REST エンドポイントを使用したテーブルへのアクセス
Iceberg REST クライアントを Amazon S3 Tables Iceberg REST エンドポイントに接続し、REST API コールを行って、S3 テーブルバケット内のテーブルの作成、更新、またはテーブルに対するクエリの実行ができます。エンドポイントは、[Apache Iceberg REST Catalog Open API 仕様](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml)で指定された標準化された Iceberg REST API のセットを実装しています。エンドポイントは、Iceberg REST API オペレーションを対応する S3 Tables オペレーションに変換することで機能します。
**注記**
Amazon S3 Tables Iceberg REST エンドポイントは、AWS Partner Network (APN) カタログ実装またはカスタムカタログ実装のテーブルにアクセスするために使用できます。1 つのテーブルバケットへの基本的な読み取り/書き込みアクセスのみが必要な場合にも使用できます。その他のアクセスシナリオでは、AWS Glue Iceberg REST エンドポイントを使用してテーブルに接続することをお勧めします。これにより、統合されたテーブル管理、一元化されたガバナンス、きめ細かなアクセスコントロールが可能になります。詳細については、[AWS Glue Iceberg REST エンドポイントを使用した Amazon S3 テーブルへのアクセス](s3-tables-integrating-glue-endpoint.md)を参照してください。
## エンドポイントの設定
サービスエンドポイントを使用して Amazon S3 Tables Iceberg REST エンドポイントに接続します。S3 Tables Iceberg REST エンドポイントの形式を次に示します。
```
https://s3tables..amazonaws.com/iceberg
```
リージョン固有のエンドポイントについては、「[S3 Tables AWS リージョンとエンドポイント](s3-tables-regions-quotas.md#s3-tables-regions)」を参照してください。
**カタログ設定プロパティ**
Iceberg クライアントを使用して分析エンジンをサービスエンドポイントに接続する場合は、カタログを初期化するときに次の設定プロパティを指定する必要があります。*プレースホルダーの値*を実際のリージョンとテーブルバケットの情報に置き換えます。
+ エンドポイント URI としてのリージョン固有のエンドポイント: `https://s3tables..amazonaws.com/iceberg`
+ ウェアハウスの場所としてのテーブルバケット ARN: `arn:aws:s3tables:::bucket/`
+ 認証用の Sigv4 プロパティ。サービスエンドポイントリクエスト用の SigV4 署名: `s3tables`
次の例では、Amazon S3 Tables Iceberg REST エンドポイントを使用するようにさまざまなクライアントを設定する方法を示しています。
------
#### [ PyIceberg ]
Amazon S3 Tables Iceberg REST エンドポイントを PyIceberg で使用するには、次のアプリケーション設定プロパティを指定します。
```
rest_catalog = load_catalog(
catalog_name,
**{
"type": "rest",
"warehouse":"arn:aws:s3tables:::bucket/",
"uri": "https://s3tables..amazonaws.com/iceberg",
"rest.sigv4-enabled": "true",
"rest.signing-name": "s3tables",
"rest.signing-region": ""
}
)
```
------
#### [ Apache Spark ]
Amazon S3 Tables Iceberg REST エンドポイントを Spark で使用するには、次のアプリケーション設定プロパティを指定し、*プレースホルダーの値*を実際のリージョンとテーブルバケットの情報に置き換えます。
```
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..amazonaws.com/iceberg" \
--conf "spark.sql.catalog.spark_catalog.warehouse=arn:aws:s3tables:::bucket/" \
--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=" \
--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 Version 4 (SigV4) を使用して認証されます。AWS SigV4 の詳細については、「[API リクエストに対する AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)」を参照してください。
Amazon S3 Tables Iceberg REST エンドポイントリクエストの SigV4 署名: `s3tables`
Amazon S3 Tables Iceberg REST エンドポイントへのリクエストは、REST API オペレーションに対応する `s3tables` IAM アクションを使用して承認されます。これらのアクセス許可は、IAM アイデンティティベースのポリシー、またはテーブルとテーブルバケットにアタッチされたリソースベースのポリシーのいずれかで定義できます。詳細については、「[S3 Tables のアクセス管理](s3-tables-setting-up.md)」を参照してください。
AWS CloudTrail を使用して、REST エンドポイントを通じてテーブルに行われたリクエストを追跡できます。リクエストは、対応する S3 IAM アクションとしてログに記録されます。例えば、`LoadTable` API により `GetTableMetadataLocation` オペレーションに対して管理イベントが発生し、`GetTableData` オペレーションに対してデータイベントが発生します。詳細については、「[S3 Tablesの AWS CloudTrail を使用したログ記録](s3-tables-logging.md)」を参照してください。
## プレフィックスとパスのパラメータ
Iceberg REST Catalog API のリクエスト URL には、自由形式のプレフィックスが含まれます。例えば、`ListNamespaces` API コールでは `GET/v1/{prefix}/namespaces` URL 形式が使用されます。S3 Tables では、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` の 3 つの部分で構成される表記をサポートするクエリエンジンが S3 Tables のカタログ階層内のオブジェクトにアクセスできます。複数レベルの名前空間を使用する場合とは異なり、互換性の問題はありません。
## サポートされている Iceberg REST API オペレーション
次の表では、サポートされている Iceberg REST API とそれらが S3 テーブルアクションにどのように対応するかを示しています。
| 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` エラーが発生します。Spark の一部のバージョンでは、`DROP TABLE PURGE` コマンドの実行時でも常にこのフラグが false に設定されます。`DROP TABLE PURGE` を試すか、S3 Tables の [DeleteTable](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTable.html) オペレーションを使用してテーブルを削除できます。
+ エンドポイントは標準のテーブルメタデータオペレーションのみをサポートしています。スナップショット管理や圧縮などのテーブルメンテナンスには、S3 Tables のメンテナンス API オペレーションを使用します。詳細については、「[S3 Tables のメンテナンス](s3-tables-maintenance-overview.md)」を参照してください。
****制限事項****
+ 複数レベルの名前空間はサポートされていません。
+ OAuth ベースの認証はサポートされていません。
+ 名前空間では `owner` プロパティのみがサポートされています。
+ [Apache Iceberg REST Open API 仕様](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml)で定義されているビュー関連の API はサポートされていません。
+ 50 MB を超える `metadata.json` ファイルを使用してテーブルに対してオペレーションを実行することはサポートされておらず、`400 Bad Request` エラーが返されます。`metadata.json` ファイルのサイズを制御するには、テーブルメンテナンスオペレーションを使用します。詳細については、「[S3 Tables のメンテナンス](s3-tables-maintenance-overview.md)」を参照してください。