# Acessar tabelas usando o endpoint Iceberg REST do serviço Tabelas do Amazon S3
É possível conectar o cliente do Iceberg REST ao endpoint Iceberg REST do serviço Tabelas do Amazon S3 e fazer chamadas à REST API para criar, atualizar ou consultar tabelas em buckets de tabela do S3. O endpoint implementa um conjunto de APIs Iceberg REST padronizadas descritas na [especificação da API Catalog Open do Apache Iceberg REST](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml). Ele converte operações da Iceberg REST API em operações correspondentes do serviço Tabelas do S3.
**nota**
O endpoint Iceberg REST do serviço Tabelas do Amazon S3 pode ser usado para acessar tabelas em implementações de catálogo da AWS Partner Network (APN) ou implementações de catálogo personalizadas. Ele também pode ser usado se você precisar apenas de acesso básico de leitura/gravação a um único bucket de tabela. Em outros cenários de acesso, recomendamos usar o endpoint Iceberg REST do AWS Glue para se conectar às tabelas, que fornece gerenciamento unificado de tabelas, governança centralizada e controle de acesso refinado. Para obter mais informações, consulte . [Acessar tabelas do Amazon S3 usando o endpoint Iceberg REST do AWS Glue](s3-tables-integrating-glue-endpoint.md)
## Configuração do endpoint
Você se conecta ao endpoint Iceberg REST do serviço Tabelas do Amazon S3 usando o endpoint de serviço. Os endpoints Iceberg REST de Tabelas do S3 têm o seguinte formato:
```
https://s3tables..amazonaws.com/iceberg
```
Consulte os endpoints específicos da região em [Regiões da AWS e endpoints da funcionalidade Tabelas do S3](s3-tables-regions-quotas.md#s3-tables-regions).
**Propriedades de configuração do catálogo**
Ao usar um cliente do Iceberg para conectar um mecanismo de analytics ao endpoint de serviço, é necessário especificar as propriedades de configuração a seguir ao inicializar o catálogo. Substitua os *valores de espaços reservados* por suas informações de região e bucket de tabela.
+ O endpoint específico da região como o URI do endpoint: `https://s3tables..amazonaws.com/iceberg`
+ O ARN do bucket de tabela como localização do warehouse: `arn:aws:s3tables:::bucket/`
+ Propriedades do Sigv4 para autenticação. O nome de assinatura do SigV4 para as solicitações do endpoint de serviço é `s3tables`.
Os exemplos a seguir mostram como configurar diferentes clientes para usar o endpoint Iceberg REST do serviço Tabelas do Amazon S3.
------
#### [ PyIceberg ]
Para usar o endpoint Iceberg REST desse serviço com o PyIceberg, especifique as seguintes propriedades de configuração da aplicação:
```
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 ]
Para usar o endpoint Iceberg REST do serviço Tabelas do Amazon S3 com o Spark, especifique as propriedades de configuração a seguir da aplicação, substituindo os *valores de espaço reservado* por suas informações de região e bucket de tabela.
```
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"
```
------
## Autenticar e autorizar o acesso ao endpoint
As solicitações de API aos endpoints de serviço de Tabelas do S3 são autenticadas usando o AWS Signature Version 4 (SigV4). Consulte [AWS Signature Version 4 para solicitações de API](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) para saber mais sobre o AWS SigV4.
O nome de assinatura do SigV4 para solicitações de endpoint Iceberg REST do serviço Tabelas do Amazon S3 é `s3tables`.
As solicitações ao endpoint Iceberg REST do serviço Tabelas do Amazon S3 são autorizadas usando ações `s3tables` do IAM correspondentes às operações de API REST. Essas permissões podem ser definidas em políticas baseadas em identidade do IAM ou em políticas baseadas em recurso anexadas a tabelas e buckets de tabela. Para ter mais informações, consulte [Gerenciamento de acesso para a funcionalidade Tabelas do S3](s3-tables-setting-up.md).
Você pode acompanhar as solicitações feitas às tabelas por meio do endpoint REST com o AWS CloudTrail. As solicitações serão registradas como a ação correspondente do IAM no S3. Por exemplo, uma API `LoadTable` gerará um evento de gerenciamento para a operação `GetTableMetadataLocation` e um evento de dados para a operação `GetTableData`. Para ter mais informações, consulte [Registro em log com o AWS CloudTrail para a funcionalidade Tabelas do S3](s3-tables-logging.md).
## Parâmetros de caminho e prefixo
As APIs do catálogo Iceberg REST têm um prefixo de formato livre nos respectivos URLs de solicitação. Por exemplo, a chamada de API `ListNamespaces` usa o formato de URL `GET/v1/{prefix}/namespaces`. Para tabelas do S3, o `{prefix}` do caminho REST é sempre o ARN do bucket de tabelas codificado em URL.
Por exemplo, para o ARN do bucket de tabela `arn:aws:s3tables:us-east-1:111122223333:bucket/bucketname`, o prefixo seria `arn%3Aaws%3As3tables%3Aus-east-1%3A111122223333%3Abucket%2Fbucketname`.
### Parâmetro do caminho do namespace
Os namespaces no caminho de API do catálogo do Iceberg REST podem ter vários níveis. No entanto, o serviço Tabelas do S3 só é compatível com namespaces de nível único. Para acessar um namespace em uma hierarquia de catálogos de vários níveis, é possível se conectar a um catálogo de vários níveis acima do namespace ao fazer referência ao namespace. Isso possibilita que qualquer mecanismo de consulta que permita a notação em três partes de `catalog.namespace.table` acesse objetos na hierarquia de catálogos do serviço Tabelas do S3 sem problemas de compatibilidade em comparação com o uso do namespace de vários níveis.
## Operações de API do Iceberg REST compatíveis
A tabela a seguir contém as APIs REST do Iceberg compatíveis e mostra como elas correspondem às ações do serviço Tabelas do S3.
| Operação REST do Iceberg | Caminho REST | Ação do IAM em Tabelas do S3 | Nome do evento do CloudTrail |
| --- | --- | --- | --- |
| `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` |
## Considerações e limitações
Veja a seguir as considerações e limitações ao usar o endpoint Iceberg REST do serviço Tabelas do Amazon S3.
****Considerações****
+ **Comportamento da API CreateTable**: a opção `stage-create` não é permitida para essa operação e resulta em um erro `400 Bad Request`. Isso significa que não é possível criar uma tabela com base em resultados de consultas usando `CREATE TABLE AS SELECT` (CTAS).
+ **Comportamento da API DeleteTable**: você só pode excluir tabelas com a limpeza habilitada. A exclusão de tabelas com `purge=false` não é permitida e resulta em um erro `400 Bad Request`. Algumas versões do Spark sempre definem esse sinalizador como falso, mesmo ao executar comandos `DROP TABLE PURGE`. Você pode tentar com `DROP TABLE PURGE` ou usar a operação [DeleteTable](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTable.html) de Tabelas do S3 para excluir uma tabela.
+ O endpoint só permite operações de metadados de tabela padrão. Para manutenção de tabelas, como gerenciamento de snapshots e compactação, use as operações de API de manutenção de Tabelas do S3. Para ter mais informações, consulte [Manutenção da funcionalidade Tabelas do S3](s3-tables-maintenance-overview.md).
****Limitações****
+ Namespaces multinível não são compatíveis.
+ A autenticação baseada em OAuth não é compatível.
+ Somente a propriedade `owner` é compatível com namespaces.
+ As APIs relacionadas à visualização definidas na [especificação da API Open do Apache Iceberg REST](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml) não são compatíveis.
+ A execução de operações em uma tabela com um tamanho de arquivo `metadata.json` maior que 50 MB não é permitida e retornará um erro `400 Bad Request`. Para controlar o tamanho dos arquivos `metadata.json`, use as operações de manutenção de tabelas. Para ter mais informações, consulte [Manutenção da funcionalidade Tabelas do S3](s3-tables-maintenance-overview.md).