# Acceso a tablas mediante el punto de conexión Iceberg REST de Tablas de Amazon S3
Puede conectar el cliente de Iceberg REST al punto de conexión Iceberg REST de Tablas de Amazon S3 y realizar llamadas a la REST API para crear, actualizar o consultar tablas en buckets de tablas de S3. El punto de conexión implementa un conjunto de API de Iceberg REST estandarizadas especificadas en la [especificación OpenAPI del catálogo de Apache Iceberg REST](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml). El punto de conexión funciona traduciendo las operaciones Iceberg REST API en las operaciones correspondientes de Tablas de S3.
**nota**
El punto de conexión Iceberg REST de Tablas de Amazon S3 se puede utilizar para acceder a las tablas en implementaciones de catálogo de AWS Partner Network (APN) o implementaciones de catálogo personalizadas. También se puede usar si solo se necesita acceso básico de lectura/escritura a un único bucket de tablas. Para otros casos de acceso, recomendamos usar el punto de conexión Iceberg REST de AWS Glue para conectarse a las tablas, ya que permite una administración unificada de las tablas, una gobernanza centralizada y un control de acceso pormenorizado. Para obtener más información, consulte [Acceso a las tablas de Amazon S3 mediante el punto de conexión Iceberg REST de AWS Glue](s3-tables-integrating-glue-endpoint.md)
## Configuración del punto de conexión
La conexión al punto de conexión Iceberg REST de Tablas de Amazon S3 se realiza mediante el punto de conexión de servicio. Los puntos de conexión Iceberg REST de Tablas de S3 tienen el siguiente formato:
```
https://s3tables..amazonaws.com/iceberg
```
Consulte [Regiones de AWS y puntos de conexión de Tablas de S3](s3-tables-regions-quotas.md#s3-tables-regions) para conocer los puntos de conexión específicos de cada región.
**Propiedades de configuración del catálogo**
Al utilizar un cliente de Iceberg para conectar un motor de análisis al punto de conexión del servicio, debe especificar las siguientes propiedades de configuración al inicializar el catálogo. Reemplace los *valores de marcador de posición* con la información de la región y del bucket de tablas.
+ El punto de conexión específico de la región como URI del punto de conexión: `https://s3tables..amazonaws.com/iceberg`
+ El ARN del bucket de tablas como ubicación del almacén: `arn:aws:s3tables:::bucket/`
+ Las propiedades de Sigv4 para la autenticación. El nombre de la firma de SigV4 para las solicitudes del punto de conexión del servicio es: `s3tables`
Los siguientes ejemplos muestran cómo configurar diferentes clientes para utilizar el punto de conexión Iceberg REST de Tablas de Amazon S3.
------
#### [ PyIceberg ]
Para usar el punto de conexión Iceberg REST de Tablas de Amazon S3 con PyIceberg, especifique las siguientes propiedades de configuración de la aplicación:
```
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 utilizar el punto de conexión Iceberg REST de Tablas de Amazon S3 con Spark, especifique las siguientes propiedades de configuración de la aplicación y sustituya los *valores de marcador de posición* con la información de la región y del bucket de tablas.
```
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"
```
------
## Autenticación y autorización del acceso al punto de conexión
Las solicitudes de API a los puntos de conexión del servicio de Tablas de S3 se autentican mediante AWS Signature Version 4 (SigV4). Consulte [AWS para solicitudes de API](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) para obtener más información sobre AWS SigV4.
El nombre de la firma de SigV4 para las solicitudes del punto de conexión Iceberg REST de Tablas de Amazon S3 es `s3tables`
Las solicitudes al punto de conexión Iceberg REST de Tablas de Amazon S3 se autorizan mediante acciones `s3tables` de IAM correspondientes a las operaciones de la API de REST. Estos permisos se pueden definir en políticas de IAM basadas en identidad o en políticas basadas en recursos asociadas a tablas y buckets de tablas. Para obtener más información, consulte [Administración de acceso para Tablas de S3](s3-tables-setting-up.md).
Puede realizar un seguimiento de las solicitudes realizadas a sus tablas a través del punto de conexión REST con AWS CloudTrail. Las solicitudes se registrarán como su correspondiente acción de IAM de S3. Por ejemplo, una API `LoadTable` generará un evento de administración para la operación `GetTableMetadataLocation` y un evento de datos para la operación `GetTableData`. Para obtener más información, consulte [Registro con para AWS CloudTrail Tablas de S3](s3-tables-logging.md).
## Parámetros de prefijo y ruta
Las API del catálogo de Iceberg REST tienen un prefijo de formato libre en las URL de solicitud. Por ejemplo, la llamada a la API `ListNamespaces` usa el formato de URL `GET/v1/{prefix}/namespaces`. En el caso de Tablas de S3, el `{prefix}` de la ruta de REST es siempre el ARN del bucket de tablas codificado como URL.
Por ejemplo, para el ARN de bucket de tablas `arn:aws:s3tables:us-east-1:111122223333:bucket/bucketname`, el prefijo sería `arn%3Aaws%3As3tables%3Aus-east-1%3A111122223333%3Abucket%2Fbucketname`
### Parámetro de ruta de espacio de nombres
Los espacios de nombres de una ruta de API del catálogo de Iceberg REST puede tener varios niveles. Sin embargo, Tablas de S3 admite únicamente espacios de nombres de un solo nivel. Para acceder a un espacio de nombres en una jerarquía de catálogos de varios niveles, puede conectarse a un catálogo de varios niveles situado encima del espacio de nombres al hacer referencia al espacio de nombres. Esto permite que cualquier motor de consultas que admita la notación de tres partes `catalog.namespace.table` acceda a los objetos de la jerarquía del catálogo de Tablas de S3 sin problemas de compatibilidad, en comparación con el uso de espacios de nombres de varios niveles.
## Operaciones de la API de Iceberg REST admitidas
La siguiente tabla contiene las API de REST de Iceberg compatibles y su correspondencia con las acciones de Tablas de S3.
| Operación REST de Iceberg | Ruta de REST | Acción de IAM en Tablas de S3 | Nombre de eventos de 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` |
## Consideraciones y limitaciones
A continuación se indican las consideraciones y limitaciones que se deben tener en cuenta al utilizar el punto de conexión Iceberg REST de Tablas de Amazon S3.
****Consideraciones****
+ **Comportamiento de la API CreateTable**: la opción `stage-create` no es compatible con esta operación y genera un error de tipo `400 Bad Request`. Esto significa que no puede crear una tabla a partir de los resultados de una consulta utilizando `CREATE TABLE AS SELECT` (CTAS).
+ **Comportamiento de la API DeleteTable**: solo puede excluir tablas con la purga habilitada. Excluir tablas con `purge=false` no es una operación admitida y genera un error de tipo `400 Bad Request`. Algunas versiones de Spark siempre configuran esta marca en false incluso cuando se ejecutan comandos `DROP TABLE PURGE`. Puede intentarlo con `DROP TABLE PURGE` o utilizar la operación [DeleteTable](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTable.html) de Tablas de S3 para eliminar una tabla.
+ El punto de conexión solo admite operaciones de metadatos de tablas estándar. Para el mantenimiento de las tablas, como la administración y compactación de instantáneas, utilice las operaciones de la API de mantenimiento de Tablas de S3. Para obtener más información, consulte [Mantenimiento de Tablas de S3](s3-tables-maintenance-overview.md).
****Limitaciones****
+ No se admiten los espacios de nombres de varios niveles.
+ No se admite la autenticación basada en OAuth.
+ Para los espacios de nombres, solo se admite la propiedad `owner`.
+ No se admiten las API relacionadas con vistas definidas en la [especificación OpenAPI de Apache Iceberg REST](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml).
+ La ejecución de operaciones en una tabla con un archivo `metadata.json` de más de 50 MB no se admite y devolverá un error de tipo `400 Bad Request`. Para controlar el tamaño de los archivos `metadata.json`, utilice las operaciones de mantenimiento de tablas. Para obtener más información, consulte [Mantenimiento de Tablas de S3](s3-tables-maintenance-overview.md).