Accesso alle tabelle utilizzando l’endpoint Iceberg REST di Tabelle Amazon S3 - Amazon Simple Storage Service
Configurazione dell’endpointAutenticazione e autorizzazione dell’accesso all’endpointPrefisso e parametri di percorsoOperazioni Iceberg REST API supportateConsiderazioni e limitazioni

Accesso alle tabelle utilizzando l’endpoint Iceberg REST di Tabelle Amazon S3

È possibile collegare il client Iceberg REST all’endpoint Iceberg REST di Tabelle Amazon S3 ed effettuare chiamate REST API per creare, aggiornare o sottoporre a query le tabelle nei bucket di tabelle S3. L’endpoint implementa un set di Iceberg REST API standardizzate specificate nella specifica Apache Iceberg REST Catalog Open API. L’endpoint funziona traducendo le operazioni Iceberg REST API nelle corrispondenti operazioni di Tabelle S3.

Nota

L’endpoint Iceberg REST di Tabelle Amazon S3 può essere utilizzato per accedere alle tabelle nelle implementazioni di cataloghi AWS Partner Network (APN) o nelle implementazioni di cataloghi personalizzati. Può essere utilizzato anche se è necessario solo l’accesso di base in lettura/scrittura a un singolo bucket di tabelle. Per altri scenari di accesso, è consigliabile utilizzare l’endpoint AWS GlueIceberg REST per connettersi alle tabelle, che fornisce una gestione unificata delle tabelle, una governance centralizzata e un controllo granulare degli accessi. Per ulteriori informazioni, consulta . Accesso alle tabelle Amazon S3 utilizzando l’endpoint AWS Glue Iceberg REST

Configurazione dell’endpoint

Ci si connette all’endpoint Iceberg REST di Tabelle Amazon S3 utilizzando l’endpoint del servizio. Gli endpoint Iceberg REST di Tabelle S3 hanno il formato seguente:

https://s3tables.<REGION>.amazonaws.com/iceberg

Fai riferimento a Endpoint e Regioni AWS di Tabelle S3 per gli endpoint specifici della Regione.

Proprietà della configurazione del catalogo

Quando si utilizza un client Iceberg per connettere un motore di analisi all’endpoint del servizio, è necessario specificare le seguenti proprietà di configurazione quando si inizializza il catalogo. Sostituisci i valori segnaposto con le informazioni relative alla Regione e al bucket di tabelle.

  • L’endpoint specifico della Regione come l’URI dell’endpoint: https://s3tables.<REGION>.amazonaws.com/iceberg

  • L’ARN del bucket di tabelle come posizione del warehouse: arn:aws:s3tables:<region>:<accountID>:bucket/<bucketname>

  • Proprietà Sigv4 per l’autenticazione. Il nome di firma SigV4 per le richieste degli endpoint del servizio è: s3tables

I seguenti esempi illustrano come configurare client diversi per utilizzare l’endpoint Iceberg REST di Tabelle Amazon S3.

PyIceberg

Per utilizzare l’endpoint Iceberg REST di Tabelle Amazon S3 con PyIceberg, specifica le seguenti proprietà di configurazione dell’applicazione:

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

Per utilizzare l’endpoint Iceberg REST di Tabelle Amazon S3 con Spark, specifica le seguenti proprietà di configurazione dell’applicazione, sostituendo i valori segnaposto con le informazioni relative alla Regione e al bucket di tabelle.

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"

Autenticazione e autorizzazione dell’accesso all’endpoint

Le richieste API agli endpoint del servizio Tabelle S3 vengono autenticate utilizzando AWS Signature Version 4 (SigV4). Consulta AWS Signature Version 4 per le richieste API per ulteriori informazioni su AWS SigV4.

Il nome di firma SigV4 per le richieste degli endpoint Iceberg REST di Tabelle Amazon S3 è: s3tables

Le richieste all’endpoint Iceberg REST di Tabelle Amazon S3 sono autorizzate utilizzando azioni IAM s3tables che corrispondono alle operazioni REST API. Queste autorizzazioni possono essere definite in policy basate su identità IAM o in policy basate su risorse collegate a tabelle e bucket di tabelle. Per ulteriori informazioni, consulta Gestione degli accessi per Tabelle S3.

È possibile monitorare le richieste effettuate alle tabelle tramite l’endpoint REST con AWS CloudTrail. Le richieste verranno registrate nei log come azioni IAM S3 corrispondenti. Ad esempio, un’API LoadTable genererà un evento di gestione per l’operazione GetTableMetadataLocation e un evento di dati per l’operazione GetTableData. Per ulteriori informazioni, consulta Registrazione con AWS CloudTrail per Tabelle S3.

Prefisso e parametri di percorso

Le API del catalogo Iceberg REST hanno un prefisso in formato libero negli URL delle richieste. Ad esempio, la chiamata API ListNamespaces utilizza il formato URL GET/v1/{prefix}/namespaces. Per Tabelle S3, il {prefix} del percorso REST è sempre l’ARN del bucket di tabelle con codifica URL.

Ad esempio, per il seguente ARN di bucket di tabelle: arn:aws:s3tables:us-east-1:111122223333:bucket/bucketname il prefisso sarebbe: arn%3Aaws%3As3tables%3Aus-east-1%3A111122223333%3Abucket%2Fbucketname

Parametro del percorso namespace

I namespace in un percorso API del catalogo Iceberg REST possono avere più livelli. Tuttavia, Tabelle S3 supporta solo namespace con un singolo livello. Per accedere a un namespace in una gerarchia di cataloghi con più livelli, è possibile connettersi a un catalogo con più livelli sopra il namespace per fare riferimento al namespace. Ciò consente a qualsiasi motore di query che supporti la notazione in tre parti catalog.namespace.table di accedere agli oggetti nella gerarchia del catalogo di Tabelle S3 senza problemi di compatibilità rispetto all’utilizzo del namespace multilivello.

Operazioni Iceberg REST API supportate

La tabella seguente contiene le Iceberg REST API supportate e il modo in cui corrispondono alle azioni di Tabelle S3.

Operazione Iceberg REST Percorso REST Azione IAM di Tabelle S3 Nome dell’evento 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

Considerazioni e limitazioni

Di seguito sono riportate le considerazioni e le limitazioni relative all’utilizzo dell’endpoint Iceberg REST di Tabelle Amazon S3.

Considerazioni

  • Comportamento dell’API CreateTable: l’opzione stage-create non è supportata per questa operazione e genera un errore 400 Bad Request. Ciò significa che non è possibile creare una tabella dai risultati della query utilizzando CREATE TABLE AS SELECT (CTAS).

  • Comportamento dell’API DeleteTable: è possibile eliminare le tabelle solo se l’eliminazione è abilitata. L’eliminazione di tabelle con purge=false non è supportata e genera un errore 400 Bad Request. Alcune versioni di Spark impostano sempre questo flag su false anche quando eseguono i comandi DROP TABLE PURGE. È possibile provare con DROP TABLE PURGE o utilizzare l’operazione DeleteTable di Tabelle S3 per eliminare una tabella.

  • L’endpoint supporta solo le operazioni standard sui metadati delle tabelle. Per la manutenzione delle tabelle, come la gestione e la compattazione di snapshot, utilizza le operazioni API di manutenzione di Tabelle S3. Per ulteriori informazioni, consulta Manutenzione di Tabelle S3.

Limitazioni

  • I namespace multilivello non sono supportati.

  • L’autenticazione basata su OAuth non è supportata.

  • Solo la proprietà owner è supportata per i namespace.

  • Le API relative alla visualizzazione definite nella specifica Apache Iceberg REST Open API non sono supportate.

  • L’esecuzione di operazioni su una tabella con un file metadata.json superiore a 5 MB non è supportata e restituirà un errore 400 Bad Request. Per controllare la dimensione dei file metadata.json, utilizza le operazioni di manutenzione delle tabelle. Per ulteriori informazioni, consulta Manutenzione di Tabelle S3.