Zugreifen auf Tabellen über den Amazon S3 Tables Iceberg REST-Endpunkt - Amazon Simple Storage Service
Endpunkt konfigurierenAuthentifizierung und Autorisierung des Zugriffs auf den EndpunktPräfix- und PfadparameterUnterstützte Iceberg REST-API-OperationenÜberlegungen und Einschränkungen

Zugreifen auf Tabellen über den Amazon S3 Tables Iceberg REST-Endpunkt

Sie können Ihren Iceberg REST Client mit dem Amazon S3 Tables Iceberg REST-Endpunkt verbinden und REST API-Aufrufe tätigen, um Tabellen in S3-Tabellen-Buckets zu erstellen, zu aktualisieren oder abzufragen. Der Endpunkt implementiert eine Reihe von standardisierten Iceberg REST-APIs, die in der Apache Iceberg REST-Catalog-Open-API-Spezifikation definiert sind. Der Endpunkt übersetzt Iceberg REST API Operationen in entsprechende S3-Tables-Operationen.

Anmerkung

Der Amazon S3 Tables Iceberg REST-Endpunkt kann für den Zugriff auf Tabellen in AWS Partner Network (APN-) Katalogimplementierungen oder benutzerdefinierten Katalogimplementierungen verwendet werden. Er kann auch verwendet werden, wenn Sie nur einfachen Lese-/Schreibzugriff auf einen einzelnen Tabellen-Bucket benötigen. Für andere Zugriffsszenarien empfehlen wir, den AWS Glue Iceberg REST Endpunkt für die Verbindung zu Tabellen zu verwenden, was eine einheitliche Tabellenverwaltung, zentrale Steuerung und eine detaillierte Zugriffskontrolle bietet. Weitere Informationen finden Sie unter . Zugreifen auf Amazon-S3-Tabellen über den AWS GlueIceberg REST-Endpunkt

Endpunkt konfigurieren

Sie stellen über den Iceberg REST Service-Endpunkt eine Verbindung zum Amazon S3 Tables-Endpunkt her. S3-TablesIceberg REST-Endpunkte haben das folgende Format:

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

Die regionsspezifischen Endpunkte finden Sie unter. AWS-Regionen für S3 Tables und Endpunkte

Katalogkonfigurationseigenschaften

Wenn Sie einen Iceberg-Client verwenden, um eine Analytics-Engine mit dem Service-Endpunkt zu verbinden, müssen Sie bei der Initialisierung des Katalogs die folgenden Konfigurationseigenschaften angeben. Ersetzen Sie die Platzhalterwerte durch die Informationen für Ihre Region und Ihren Tabellen-Bucket.

  • Der regionsspezifische Endpunkt als Endpunkt-URI: https://s3tables.<REGION>.amazonaws.com/iceberg

  • Ihr Tabellen-Bucket-ARN als Lagerstandort: arn:aws:s3tables:<region>:<accountID>:bucket/<bucketname>

  • SigV4-Eigenschaften für die Authentifizierung. Der SigV4-Signaturname für die Dienstendpunktanforderungen lautet: s3tables

Die folgenden Beispiele zeigen, wie Sie verschiedene Clients für die Verwendung des Amazon-S3-Tables Iceberg REST-Endpunkts konfigurieren.

PyIceberg

Um den Amazon S3 Tables Iceberg REST-Endpunkt mit PyIceberg zu verwenden, geben Sie die folgenden Anwendungskonfigurationseigenschaften an:

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

Um den Amazon S3 Tables Iceberg REST-Endpunkt mit Spark zu verwenden, geben Sie die folgenden Eigenschaften für die Anwendungskonfiguration an und ersetzen Sie die Platzhalterwerte durch die Informationen für Ihre Region und Ihren Tabellen-Bucket.

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"

Authentifizierung und Autorisierung des Zugriffs auf den Endpunkt

API-Anfragen an die Endpunkte des S3 Tables-Service werden mithilfe von AWS Signature Version 4 (SigV4) authentifiziert. Weitere Informationen zu AWS SigV4 finden Sie in AWS Signature Version 4 für API-Anfragen.

Der SigV4-Signaturname für Amazon S3 Tables Iceberg REST-Endpunktanforderungen lautet: s3tables

Anfragen an den Amazon S3 Tables Iceberg REST-Endpunkt werden mithilfe von s3tables IAM-Aktionen autorisiert, die den REST API-Vorgängen entsprechen. Diese Berechtigungen können entweder in identitätsbasierten IAM-Richtlinien oder ressourcenbasierten Richtlinien definiert werden, die Tabellen und Tabellen-Buckets zugeordnet sind. Weitere Informationen finden Sie unter Zugriffsverwaltung für S3 Tables.

Sie können Anfragen an Ihre Tabellen über den Endpunkt REST mit AWS CloudTrail verfolgen. Anfragen werden als entsprechende S3-IAM-Aktion protokolliert. Beispielsweise generiert eine LoadTable API ein Verwaltungsereignis für den GetTableMetadataLocation Vorgang und ein Datenereignis für den GetTableData Vorgang. Weitere Informationen finden Sie unter Protokollieren mit AWS CloudTrail für S3 Tables.

Präfix- und Pfadparameter

Iceberg REST-Katalog-APIs verfügen über ein frei wählbares Präfix in ihren Anfrage-URLs. Beispielsweise verwendet der ListNamespaces API-Aufruf das GET/v1/{prefix}/namespaces URL-Format. Für S3 Tables {prefix} ist der REST-Pfad immer Ihr URL-kodierter Tabellen-Bucket-ARN.

Für den folgenden Tabellen-Bucket-ARN: wäre arn:aws:s3tables:us-east-1:111122223333:bucket/bucketname das Präfix beispielsweise: arn%3Aaws%3As3tables%3Aus-east-1%3A111122223333%3Abucket%2Fbucketname

Namespace-Pfadparameter

Namespaces in einem Iceberg REST-Katalog-API-Pfad können mehrere Ebenen aufweisen. S3 Tables unterstützt jedoch nur einstufige Namespaces. Um auf einen Namespace in einer mehrstufigen Kataloghierarchie zuzugreifen, können Sie eine Verbindung zu einem übergeordneten mehrstufigen Katalog herstellen, um auf den Namespace zu verweisen. Dadurch kann jede Abfrage-Engine, die die dreiteilige Notation von catalog.namespace.table unterstützt, auf Objekte in der Kataloghierarchie von S3 Tables zugreifen, ohne dass es zu Kompatibilitätsproblemen im Vergleich zur Verwendung des mehrstufigen Namespace kommt.

Unterstützte Iceberg REST-API-Operationen

Die folgende Tabelle enthält die unterstützten Iceberg-REST-APIs und wie sie den Aktionen in S3 Tables entsprechen.

Iceberg-REST-Betrieb REST-Pfad IAM-Aktion von 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

Überlegungen und Einschränkungen

Im Folgenden finden Sie Überlegungen und Einschränkungen bei der Verwendung des Amazon S3 Tables Iceberg REST-Endpunkts.

Überlegungen

  • CreateTable API-Verhalten – Diese stage-create-Option wird für diesen Vorgang nicht unterstützt und führt zu einem 400 Bad Request-Fehler. Das bedeutet, dass Sie mit CREATE TABLE AS SELECT (CTAS) keine Tabelle aus Abfrageergebnissen erstellen können.

  • DeleteTable API-Verhalten – Sie können nur Tabellen löschen, für die die Bereinigung aktiviert ist. Das Löschen von Tabellen mit purge=false wird nicht unterstützt und führt zu einem Fehler 400 Bad Request. Einige Versionen von Spark setzen dieses Flag immer auf „False“, selbst wenn DROP TABLE PURGE-Befehle ausgeführt werden. Sie können versuchen, mit DROP TABLE PURGE eine Tabelle zu löschen, oder die Operation DeleteTable von S3 Tables verwenden.

  • Der Endpunkt unterstützt nur Standardoperationen mit Tabellenmetadaten. Verwenden Sie für die Tabellenverwaltung, z. B. die Verwaltung und Komprimierung von Snapshots, API-Operationen zur Wartung von S3 Tables. Weitere Informationen finden Sie unter Wartung von S3 Tables.

Einschränkungen

  • Mehrstufige Namespaces werden nicht unterstützt.

  • Die OAuth-basierte Authentifizierung wird nicht unterstützt.

  • Nur die owner Eigenschaft wird für Namespaces unterstützt.

  • Ansichtsbezogene APIs, die in der Apache Iceberg REST-Open-API-Spezifikation definiert sind, werden nicht unterstützt.

  • Das Ausführen von Operationen an einer Tabelle mit einer metadata.json Datei über 5 MB wird nicht unterstützt und es wird ein Fehler 400 Bad Request zurückgegeben. Verwenden Sie Tabellenverwaltungsoperationen, um die Größe Ihrer metadata.json Dateien zu kontrollieren. Weitere Informationen finden Sie unter Wartung von S3 Tables.