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

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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 de Iceberg REST APIs normes 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 Iceberg REST terminaison 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 read/write accès de base à un seul compartiment de table. Pour les autres scénarios d'accès, nous recommandons d'utiliser le AWS Glue Iceberg REST point de terminaison 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 de plus amples 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 le placeholder values par les informations relatives à votre région et à votre compartiment de tables.

  • 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 Iceberg REST terminaison Amazon S3 Tables avecSpark, spécifiez les propriétés de configuration de l'application suivantes, en les placeholder values remplaçant par les informations relatives à votre région et à votre compartiment de tables.

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 du service S3 Tables sont authentifiées à l'aide de AWS Signature Version 4 (SigV4). Consultez AWS la version 4 de Signature pour les demandes d'API afin d'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 de plus amples informations, veuillez consulter 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 de plus amples informations, veuillez consulter Journalisation avec AWS CloudTrail pour S3 Tables.

Paramètres de chemin et de préfixe

Iceberg REST APIs les catalogues ont un préfixe de forme libre dans leur demande. URLs 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

Le tableau suivant présente les REST Iceberg pris en charge APIs et indique comment ils correspondent aux actions 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

  • CreateTable Comportement de l'API — L'stage-createoption n'est pas prise en charge pour cette opération et entraîne une 400 Bad Request erreur. 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).

  • DeleteTable Comportement de l'API : 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 DROP TABLE PURGE ou utiliser l'DeleteTableopération 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 de plus amples informations, veuillez consulter Maintenance de S3 Tables.

Limites

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

  • OAuthl'authentification basée n'est pas prise en charge.

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

  • Les paramètres liés à la vue APIs définis dans la spécification Apache Iceberg REST Open API ne sont pas pris en charge.

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