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

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

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, in der Apache Iceberg RESTCatalog Open API-Spezifikation Iceberg REST APIs spezifizierten. Der Endpunkt übersetzt Iceberg REST API Operationen in entsprechende S3-Tables-Operationen.

Anmerkung

Der Amazon S3 Iceberg REST Tables-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 read/write Basiszugriff 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 das placeholder values 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 Iceberg REST Tables-Endpunkt mit zu verwendenSpark, geben Sie die folgenden Eigenschaften der Anwendungskonfiguration an und ersetzen Sie die placeholder values 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 Service-Endpunkte von S3 Tables werden mit AWS Signature Version 4 (Sigv4) authentifiziert. Weitere Informationen zu AWS Sigv4 finden Sie unter Signature Version 4 für API-Anfragen. AWS

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 RESTKataloge APIs haben in ihrer Anfrage ein Präfix in freier Form. 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-Dateien APIs und wie sie den Aktionen in S3-Tabellen 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 — Die 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, wenn das Löschen 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, eine Tabelle mit dem DeleteTableVorgang S3-Tabellen zu löschen DROP TABLE PURGE oder ihn zu 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.

  • OAuthDie basierte Authentifizierung wird nicht unterstützt.

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

  • In der Apache Iceberg RESTOpen API-Spezifikation APIs definierte View-bezogene Daten werden nicht unterstützt.

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