Acceso a tablas mediante el punto de conexión Iceberg REST de Tablas de Amazon S3 - Amazon Simple Storage Service
Configuración del punto de conexiónAutenticación y autorización del acceso al punto de conexiónParámetros de prefijo y rutaOperaciones de la API de Iceberg REST admitidasConsideraciones y limitaciones

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 de API abierta del catálogo de Apache Iceberg REST. 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

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.<REGION>.amazonaws.com/iceberg

Consulte Regiones de AWS y puntos de conexión de Tablas de S3 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.<REGION>.amazonaws.com/iceberg

  • El ARN del bucket de tablas como ubicación del almacén: arn:aws:s3tables:<region>:<accountID>:bucket/<bucketname>

  • 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:<Region>:<accountID>:bucket/<bucketname>",
    "uri": "https://s3tables.<Region>.amazonaws.com/iceberg",
    "rest.sigv4-enabled": "true",
    "rest.signing-name": "s3tables",
    "rest.signing-region": "<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.<Region>.amazonaws.com/iceberg" \
  --conf "spark.sql.catalog.spark_catalog.warehouse=arn:aws:s3tables:<Region>:<accountID>:bucket/<bucketname>" \
  --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=<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 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.

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.

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 soltar tablas con la purga habilitada. Soltar 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 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.

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 de API abierta de Apache Iceberg REST.

  • La ejecución de operaciones en una tabla con un archivo metadata.json de más de 5 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.