Amazon S3 Tables Iceberg REST 엔드포인트를 사용하여 테이블에 액세스

Iceberg REST 클라이언트를 Amazon S3 Tables Iceberg REST 엔드포인트에 연결하고 S3 테이블 버킷에서 테이블을 생성, 업데이트 또는 쿼리하는 REST API 직접 호출을 할 수 있습니다. 엔드포인트는 Apache Iceberg RESTCatalog Open API 사양에 지정된 표준화된 Iceberg REST API 세트를 구현합니다. 엔드포인트는 Iceberg REST API 작업을 해당 S3 Tables 작업으로 변환하여 작동합니다.

엔드포인트 구성

서비스 엔드포인트를 사용하여 Amazon S3 Tables Iceberg REST 엔드포인트에 연결합니다. S3 Tables Iceberg REST 엔드포인트의 형식은 다음과 같습니다.

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

리전별 엔드포인트는 S3 Tables AWS 리전 및 엔드포인트 섹션을 참조하세요.

다음 예제에서는 Amazon S3 Tables Iceberg REST 엔드포인트를 사용하도록 여러 클라이언트를 구성하는 방법을 보여줍니다.

PyIceberg

PyIceberg 에서 Amazon S3 TablesIceberg REST 엔드포인트를 사용하려면 다음 애플리케이션 구성 속성을 지정합니다.

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

Spark에서 Amazon S3 Tables Iceberg REST 엔드포인트를 사용하려면 자리 표시자 값을 리전 및 테이블 버킷의 정보로 바꾸어 다음 애플리케이션 구성 속성을 지정합니다.

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"               

엔드포인트에 대한 액세스 인증 및 권한 부여

S3 Tables 서비스 엔드포인트에 대한 API 요청은 AWS Signature Version 4(SigV4)를 사용하여 인증됩니다. AWS SigV4에 대한 자세한 내용은 API 요청용 AWS Signature Version 4 섹션을 참조하세요.

Amazon S3 Tables Iceberg REST 엔드포인트 요청의 SigV4 서명 이름은 s3tables입니다.

Amazon S3 Tables Iceberg REST 엔드포인트에 대한 요청은 REST API 작업에 해당하는 s3tables IAM 작업을 사용하여 승인됩니다. 이러한 권한은 IAM 자격 증명 기반 정책 또는 테이블 및 테이블 버킷에 연결된 리소스 기반 정책에서 정의할 수 있습니다. 자세한 내용은 S3 Tables의 액세스 관리 단원을 참조하십시오.

AWS CloudTrail을 사용하여 REST 엔드포인트를 통해 테이블에 대한 요청을 추적할 수 있습니다. 요청은 해당 S3 IAM 작업으로 기록됩니다. 예를 들어 LoadTable API는 GetTableMetadataLocation 작업에 대한 관리 이벤트와 GetTableData 작업에 대한 데이터 이벤트를 생성합니다. 자세한 내용은 S3 Tables에서 AWS CloudTrail을 사용하여 로깅 단원을 참조하십시오.

접두사 및 경로 파라미터

Iceberg REST 카탈로그 API는 요청 URL에 자유 형식 접두사를 사용합니다. 예를 들어 ListNamespaces API 직접 호출은 GET/v1/{prefix}/namespaces URL 형식을 사용합니다. S3 테이블의 경우 REST 경로 {prefix}는 항상 URL로 인코딩된 테이블 버킷 ARN입니다.

예를 들어 다음 테이블 버킷 ARN arn:aws:s3tables:us-east-1:111122223333:bucket/bucketname의 경우 접두사는 arn%3Aaws%3As3tables%3Aus-east-1%3A111122223333%3Abucket%2Fbucketname입니다.

네임스페이스 경로 파라미터

Iceberg REST 카탈로그 API 경로의 네임스페이스는 여러 수준을 가질 수 있습니다. 그러나 S3 Tables는 단일 수준 네임스페이스만 지원합니다. 다중 수준 카탈로그 계층 구조의 네임스페이스에 액세스하려면 네임스페이스 위의 다중 수준 카탈로그에 연결하여 네임스페이스를 참조하면 됩니다. 이렇게 하면 다중 수준 네임스페이스를 사용하는 것에 비해 호환성 문제 없이 catalog.namespace.table의 3부 표기법을 지원하는 모든 쿼리 엔진이 S3 Tables의 카탈로그 계층 구조의 객체에 액세스할 수 있습니다.

지원되는 Iceberg REST API 작업

다음 표에는 지원되는 Iceberg REST API와 이러한 API가 S3 Tables 작업에 대응하는 방식이 나와 있습니다.

고려 사항 및 제한 사항

다음은 Amazon S3 Tables Iceberg REST 엔드포인트 사용 시 고려 사항 및 제한 사항입니다.