Acessar tabelas usando o endpoint Iceberg REST do serviço Tabelas do Amazon S3 - Amazon Simple Storage Service
Configuração do endpointAutenticar e autorizar o acesso ao endpointParâmetros de caminho e prefixoOperações de API do Iceberg REST compatíveisConsiderações e limitações

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. 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 ter mais informações, consulte Acessar tabelas do Amazon S3 usando o endpoint Iceberg REST do AWS Glue.

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

Consulte os endpoints específicos da região em Regiões da AWS e endpoints da funcionalidade Tabelas do S3.

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

  • O ARN do bucket de tabela como localização do warehouse: arn:aws:s3tables:<region>:<accountID>:bucket/<bucketname>

  • 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:<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 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.<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"

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 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.

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.

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 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.

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 não são compatíveis.

  • A execução de operações em uma tabela com um tamanho de arquivo metadata.json maior que 5 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.