Accès aux tables à l’aide du point de terminaison Iceberg REST d’Amazon S3 Tables - Amazon Simple Storage Service
Configuration du point de terminaisonAuthentification et autorisation d’accès au point de terminaisonParamètres de chemin et de préfixeOpérations d’API Iceberg REST prises en chargeConsidérations et restrictions

Accès aux tables à l’aide du point de terminaison Iceberg REST d’Amazon S3 Tables

Vous pouvez connecter votre Iceberg REST client au point de terminaison Iceberg REST d’Amazon S3 Tables et passer des appels REST API pour créer, mettre à jour ou interroger des tables dans des compartiments de table S3. Le point de terminaison implémente un ensemble d’API Iceberg REST standardisées spécifiées dans la spécification de l’API Apache Iceberg REST Catalog Open. Le point de terminaison fonctionne en traduisant les opérations de l’Iceberg REST API en opérations de S3 Tables correspondantes.

Note

Le point de terminaison Iceberg REST d’Amazon S3 Tables peut être utilisé pour accéder aux tables dans les implémentations de catalogues AWS Partner Network (APN) ou dans les implémentations de catalogues personnalisés. Il peut également être utilisé si vous n’avez besoin que d’un accès de base en lecture/écriture à un seul compartiment de table. Pour les autres scénarios d’accès, nous recommandons d’utiliser le point de terminaison AWS Glue Iceberg REST pour se connecter aux tables, ce qui permet une gestion unifiée des tables, une gouvernance centralisée et un contrôle d’accès précis. Pour plus d’informations, consultez  Accès à Amazon S3 Tables à l’aide du point de terminaison AWS Glue Iceberg REST

Configuration du point de terminaison

Vous vous connectez au point de terminaison Iceberg REST d’Amazon S3 Tables à l’aide du point de terminaison du service. Les points de terminaison Iceberg REST de S3 Tables ont le format suivant :

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

Reportez-vous à Points de terminaison et Régions AWS S3 Tables pour les points de terminaison spécifiques à une région.

Propriétés de configuration du catalogue

Lorsque vous utilisez un client Iceberg pour connecter un moteur d’analytique au point de terminaison du service, vous devez spécifier les propriétés de configuration suivantes lors de l’initialisation du catalogue. Remplacez les valeurs des espaces réservés par les informations de votre compartiment de table et de votre région.

  • Le point de terminaison spécifique à la région en tant qu’URI du point de terminaison : https://s3tables.<REGION>.amazonaws.com/iceberg

  • L’ARN de votre compartiment de table comme emplacement de l’entrepôt : arn:aws:s3tables:<region>:<accountID>:bucket/<bucketname>

  • Propriétés Sigv4 pour l’authentification. Le nom de signature SigV4 pour les demandes de point de terminaison de service est le suivant : s3tables

Les exemples suivants vous montrent comment configurer différents clients pour utiliser le point de terminaison Iceberg REST d’Amazon S3 Tables.

PyIceberg

Pour utiliser le point de terminaison Iceberg REST d’Amazon S3 Tables avec PyIceberg, spécifiez les propriétés de configuration d’application suivantes :

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

Pour utiliser le point de terminaison Iceberg REST d’Amazon S3 Tables avec Spark, spécifiez les propriétés de configuration de l’application suivantes, en remplaçant les valeurs d’espace réservé par les informations relatives à votre région et à votre compartiment de table.

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"

Authentification et autorisation d’accès au point de terminaison

Les demandes d’API adressées aux points de terminaison de service de S3 Tables sont authentifiées à l’aide d’AWS Signature Version 4 (SigV4). Consultez AWS Signature Version 4 pour les demandes d’API pour en savoir plus sur AWS SigV4.

Le nom de signature SigV4 pour les demandes de point de terminaison Iceberg REST d’Amazon S3 Tables est le suivant : s3tables

Les demandes adressées au point de terminaison Iceberg REST d’Amazon S3 Tables sont autorisées à l’aide d’actions s3tables IAM correspondant aux opérations d’API REST. Ces autorisations peuvent être définies dans les stratégies IAM basées sur l’identité ou les politiques basées sur les ressources associées aux tables et aux compartiments de table. Pour plus d’informations, consultez Gestion des accès pour S3 Tables.

Vous pouvez suivre les demandes adressées à vos tables via le point de terminaison REST avec AWS CloudTrail. Les demandes seront journalisées en tant qu’action IAM S3 correspondante. Par exemple, une API LoadTable génère un événement de gestion pour l’opération GetTableMetadataLocation et un événement de données pour l’opération GetTableData. Pour plus d’informations, consultez Journalisation avec AWS CloudTrail pour S3 Tables.

Paramètres de chemin et de préfixe

Les API du catalogue Iceberg REST contiennent un préfixe de forme libre dans leurs URL de demande. Par exemple, l’appel d’API ListNamespaces utilise le format d’URL GET/v1/{prefix}/namespaces. Pour S3 Tables, le {prefix} de chemin REST est toujours l’ARN de votre compartiment de table codé en URL.

Par exemple, pour l’ARN du compartiment de table suivant : arn:aws:s3tables:us-east-1:111122223333:bucket/bucketname le préfixe serait : arn%3Aaws%3As3tables%3Aus-east-1%3A111122223333%3Abucket%2Fbucketname

Paramètre de chemin d’accès à l’espace de noms

Les espaces de noms du chemin des API du catalogue Iceberg REST peuvent comporter plusieurs niveaux. Toutefois, S3 Tables ne prend en charge que les espaces de noms à un seul niveau. Pour accéder à un espace de noms dans une hiérarchie de catalogue à plusieurs niveaux, vous pouvez vous connecter à un catalogue à plusieurs niveaux situé au-dessus de l’espace de noms pour référencer l’espace de noms. Cela permet à tout moteur de requête qui prend en charge la notation en trois parties de catalog.namespace.table d’accéder aux objets de la hiérarchie du catalogue S3 Tables sans problèmes de compatibilité par rapport à l’utilisation de l’espace de noms à plusieurs niveaux.

Opérations d’API Iceberg REST prises en charge

La table suivante présente les API REST d’Iceberg prises en charge et indique comment elles correspondent aux actions de S3 Tables.

Opération REST Iceberg Chemin REST Action IAM de S3 Tables CloudTrail EventName

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

Considérations et restrictions

Vous trouverez ci-dessous les considérations et les limites relatives à l’utilisation du point de terminaison Iceberg REST d’Amazon S3 Tables.

Considérations

  • Comportement de l’API CreateTable : l’option stage-create n’est pas prise en charge pour cette opération et entraîne une erreur 400 Bad Request. Cela signifie que vous ne pouvez pas créer de table à partir des résultats d’une requête à l’aide de CREATE TABLE AS SELECT (CTAS).

  • Comportement de l’API DeleteTable : vous ne pouvez supprimer des tables que lorsque la purge est activée. La suppression de tables avec purge=false n’est pas prise en charge et entraîne une erreur 400 Bad Request. Certaines versions de Spark attribuent toujours à cet indicateur la valeur false, même lors de l’exécution de commandes DROP TABLE PURGE. Vous pouvez essayer avec DROP TABLE PURGE ou utiliser l’opération DeleteTable de S3 Tables pour supprimer une table.

  • Le point de terminaison prend uniquement en charge les opérations de métadonnées de table standard. Pour la maintenance des tables, par exemple la gestion des instantanés et le compactage, utilisez les opérations de l’API de maintenance de S3 Tables. Pour plus d’informations, consultez Maintenance de S3 Tables.

Limites

  • Les espaces de noms multiniveaux ne sont pas pris en charge.

  • L’authentification basée sur OAuth n’est pas prise en charge.

  • Seule la propriété owner est prise en charge pour les espaces de noms.

  • Les API liées à la vue définies dans la spécification Apache Iceberg REST Open API ne sont pas prises en charge.

  • L’exécution d’opérations sur une table contenant un fichier metadata.json de plus de 5 Mo n’est pas prise en charge et renverra une erreur 400 Bad Request. Pour contrôler la taille de vos fichiers metadata.json, utilisez les opérations de maintenance des tables. Pour plus d’informations, consultez Maintenance de S3 Tables.