Mengakses tabel menggunakan endpoint Amazon S3 Iceberg REST Tables - Amazon Simple Storage Service
Mengkonfigurasi titik akhirMengautentikasi dan mengotorisasi akses ke titik akhirParameter awalan dan jalurOperasi Iceberg REST API yang didukungPertimbangan dan batasan

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Mengakses tabel menggunakan endpoint Amazon S3 Iceberg REST Tables

Anda dapat menghubungkan Iceberg REST klien Anda ke Iceberg REST titik akhir Tabel Amazon S3 dan melakukan REST API panggilan untuk membuat, memperbarui, atau menanyakan tabel di bucket tabel S3. Titik akhir mengimplementasikan satu set standar yang Iceberg REST APIs ditentukan dalam spesifikasi API Terbuka Apache Iceberg RESTKatalog. Titik akhir bekerja dengan menerjemahkan Iceberg REST API operasi ke dalam operasi Tabel S3 yang sesuai.

catatan

Iceberg RESTTitik akhir Tabel Amazon S3 dapat digunakan untuk mengakses tabel dalam implementasi katalog AWS Partner Network (APN) atau implementasi katalog khusus. Ini juga dapat digunakan jika Anda hanya membutuhkan read/write akses dasar ke ember meja tunggal. Untuk skenario akses lainnya, sebaiknya gunakan AWS Glue Iceberg REST titik akhir untuk terhubung ke tabel, yang menyediakan manajemen tabel terpadu, tata kelola terpusat, dan kontrol akses berbutir halus. Untuk informasi selengkapnya, lihat Mengakses tabel Amazon S3 menggunakan titik akhir AWS GlueIceberg REST

Mengkonfigurasi titik akhir

Anda terhubung ke Iceberg REST titik akhir Tabel Amazon S3 menggunakan titik akhir layanan. Iceberg RESTTitik akhir Tabel S3 memiliki format berikut:

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

Lihat Tabel S3 Wilayah AWS dan titik akhir untuk titik akhir khusus Wilayah.

Properti konfigurasi katalog

Saat menggunakan klien Iceberg untuk menghubungkan mesin analitik ke titik akhir layanan, Anda harus menentukan properti konfigurasi berikut saat menginisialisasi katalog. Ganti placeholder values dengan informasi untuk Wilayah dan keranjang meja Anda.

  • Titik akhir khusus wilayah sebagai URI titik akhir: https://s3tables.<REGION>.amazonaws.com/iceberg

  • Bucket meja ARN anda sebagai lokasi gudang: arn:aws:s3tables:<region>:<accountID>:bucket/<bucketname>

  • Properti Sigv4 untuk otentikasi. Nama penandatanganan SigV4 untuk permintaan titik akhir layanan adalah: s3tables

Contoh berikut menunjukkan cara mengonfigurasi klien yang berbeda untuk menggunakan titik akhir Tabel Iceberg REST Amazon S3.

PyIceberg

Untuk menggunakan Iceberg REST endpoint Amazon S3 Tables denganPyIceberg, tentukan properti konfigurasi aplikasi berikut:

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

Untuk menggunakan Iceberg REST endpoint Amazon S3 Tables denganSpark, tentukan properti konfigurasi aplikasi berikut, ganti placeholder values dengan informasi untuk Region dan bucket tabel Anda.

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"

Mengautentikasi dan mengotorisasi akses ke titik akhir

Permintaan API ke titik akhir layanan Tabel S3 diautentikasi menggunakan AWS Signature Version 4 (SigV4). Lihat AWS Sigv4 Versi Tanda Tangan untuk permintaan API guna mempelajari lebih lanjut tentang AWS SigV4.

Nama penandatanganan SiGv4 untuk permintaan titik akhir Iceberg REST Tabel Amazon S3 adalah: s3tables

Permintaan ke Iceberg REST titik akhir Tabel Amazon S3 diotorisasi menggunakan tindakan s3tables IAM yang terkait dengan operasi API. REST Izin ini dapat didefinisikan dalam kebijakan berbasis identitas IAM atau kebijakan berbasis sumber daya yang dilampirkan pada tabel dan bucket tabel. Untuk informasi selengkapnya, lihat Manajemen akses untuk Tabel S3.

Anda dapat melacak permintaan yang dibuat ke tabel Anda melalui REST titik akhir dengan AWS CloudTrail. Permintaan akan dicatat sebagai tindakan IAM S3 yang sesuai. Misalnya, LoadTable API akan menghasilkan peristiwa manajemen untuk GetTableMetadataLocation operasi dan peristiwa data untuk GetTableData operasi. Untuk informasi selengkapnya, lihat Logging dengan AWS CloudTrail untuk Tabel S3.

Parameter awalan dan jalur

Iceberg RESTkatalog APIs memiliki awalan bentuk bebas dalam permintaan mereka. URLs Misalnya, panggilan ListNamespaces API menggunakan format GET/v1/{prefix}/namespaces URL. Untuk Tabel S3, jalur REST {prefix} selalu ARN bucket tabel yang disandikan url Anda.

Misalnya, untuk keranjang tabel ARN berikut: arn:aws:s3tables:us-east-1:111122223333:bucket/bucketname awalannya adalah: arn%3Aaws%3As3tables%3Aus-east-1%3A111122223333%3Abucket%2Fbucketname

Parameter jalur namespace

Ruang nama di jalur API Iceberg REST katalog dapat memiliki beberapa level. Namun, Tabel S3 hanya mendukung ruang nama tingkat tunggal. Untuk mengakses namespace dalam hierarki katalog multi-level, Anda dapat terhubung ke katalog multi-level di atas namespace saat mereferensikan namespace. Ini memungkinkan mesin kueri apa pun yang mendukung notasi 3 bagian catalog.namespace.table untuk mengakses objek dalam hierarki katalog Tabel S3 tanpa masalah kompatibilitas dibandingkan dengan menggunakan namespace multi-level.

Operasi Iceberg REST API yang didukung

Tabel berikut berisi Iceberg REST yang didukung APIs dan bagaimana mereka sesuai dengan tindakan Tabel S3.

Operasi Iceberg REST Jalur REST S3 Tabel aksi IAM 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

Pertimbangan dan batasan

Berikut ini adalah pertimbangan dan batasan saat menggunakan endpoint Amazon S3 TablesIceberg REST.

Pertimbangan-pertimbangan

  • CreateTable Perilaku API — stage-create Opsi ini tidak didukung untuk operasi ini, dan menghasilkan 400 Bad Request kesalahan. Ini berarti Anda tidak dapat membuat tabel dari hasil kueri menggunakan CREATE TABLE AS SELECT (CTAS).

  • DeleteTable Perilaku API - Anda hanya dapat menjatuhkan tabel dengan pembersihan diaktifkan. Menjatuhkan tabel dengan purge=false tidak didukung dan menghasilkan 400 Bad Request kesalahan. Beberapa versi Spark selalu menyetel flag ini ke false bahkan saat menjalankan DROP TABLE PURGE perintah. Anda dapat mencoba dengan DROP TABLE PURGE atau menggunakan DeleteTableoperasi Tabel S3 untuk menghapus tabel.

  • Titik akhir hanya mendukung operasi metadata tabel standar. Untuk pemeliharaan tabel, seperti manajemen snapshot dan pemadatan, gunakan operasi API pemeliharaan Tabel S3. Untuk informasi selengkapnya, lihat Pemeliharaan Tabel S3.

Batasan

  • Ruang nama bertingkat tidak didukung.

  • OAuthotentikasi berbasis tidak didukung.

  • Hanya owner properti yang didukung untuk ruang nama.

  • Terkait tampilan yang APIs ditentukan dalam spesifikasi Apache Iceberg REST Open API tidak didukung.

  • Menjalankan operasi di atas meja dengan metadata.json file lebih dari 50MB tidak didukung, dan akan mengembalikan 400 Bad Request kesalahan. Untuk mengontrol ukuran metadata.json file Anda, gunakan operasi pemeliharaan tabel. Lihat informasi yang lebih lengkap di Pemeliharaan Tabel S3.