Apache Iceberg™ REST 카탈로그에 대한 카탈로그 통합 구성

Apache Iceberg™ REST 카탈로그 통합 을 통해 Snowflake는 오픈 소스 Apache Iceberg REST OpenAPI 사양 을 준수하는 원격 카탈로그에서 관리되는 Apache Iceberg™ 테이블 에 액세스할 수 있습니다.

REST 카탈로그에 연결하는 중

공용 엔드포인트 또는 비공개 네트워크를 사용하는 Iceberg REST API에 연결할 수 있습니다.

공용 엔드포인트

퍼블릭 엔드포인트를 사용하여 Iceberg REST API에 연결하려면 다음 인증 메서드를 사용하는 카탈로그 통합을 생성할 수 있습니다.

  • OAuth

  • 전달자 토큰 또는 개인 액세스 토큰(PAT)

  • SigV4

비공개 네트워크

비공개 네트워크에서 호스팅되는 Iceberg REST API에 연결하려면 Signature Version 4(SigV4) 인증을 사용하는 카탈로그 통합을 생성할 수 있습니다.

카탈로그 통합 만들기

CREATE CATALOG INTEGRATION(Apache Iceberg™ REST) 명령을 사용하여 선택한 인증 메서드에 대한 카탈로그 통합을 생성합니다. REST_CONFIG 및 REST_AUTHENTICATION 인자에 지정하는 값은 선택한 인증 메서드에 따라 달라집니다.

OAuth

다음 예에서는 OAuth를 사용하여 Tabular에 연결하는 REST 카탈로그 통합을 만듭니다.

CREATE OR REPLACE CATALOG INTEGRATION tabular_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = 'https://api.tabular.io/ws'
    WAREHOUSE = '<tabular_warehouse_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://api.tabular.io/ws/v1/oauth/tokens'
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_secret>'
    OAUTH_ALLOWED_SCOPES = ('catalog')
  )
  ENABLED = TRUE;
Copy

다음 예제에서는 OAuth를 사용하여 Databricks Unity Catalog에 연결하는 REST 카탈로그 통합을 생성합니다.

CREATE OR REPLACE CATALOG INTEGRATION unity_catalog_int_oauth
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = 'https://my-api/api/2.1/unity-catalog/iceberg'
    WAREHOUSE = '<catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://my-api/oidc/v1/token'
    OAUTH_CLIENT_ID = '123AbC ...'
    OAUTH_CLIENT_SECRET = '1365910ab ...'
    OAUTH_ALLOWED_SCOPES = ('all-apis', 'sql')
  )
  ENABLED = TRUE;
Copy

전달자 토큰 또는 PAT

다음 예제에서는 PAT 토큰을 사용하여 Databricks Unity Catalog에 연결하는 REST 카탈로그 통합을 생성합니다.

CREATE OR REPLACE CATALOG INTEGRATION unity_catalog_int_pat
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://my-api/api/2.1/unity-catalog/iceberg'
    WAREHOUSE = '<catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = 'eyAbCD...eyDeF...'
  )
  ENABLED = TRUE;
Copy

SigV4 (API 게이트웨이)

다음 다이어그램은 Snowflake가 API Gateway 및 SigV4 인증을 사용하여 REST 카탈로그 서버와 상호 작용하는 방법을 보여줍니다.

Iceberg REST 카탈로그가 Amazon API Gateway, IAM 및 S3와 함께 작동하는 방식을 보여주는 다이어그램.

이 섹션의 단계에 따라 Amazon API GatewaySignature Version 4 (SigV4) 인증에서 REST API를 사용하여 공개적으로 액세스할 수 없는 Snowflake를 Iceberg REST 카탈로그에 안전하게 연결합니다.

  1. Amazon API Gateway에서 REST API 만들기

  2. IAM 정책을 생성하고 역할에 연결

  3. API Gateway 리소스 정책 연결(비공개 APIs만 해당)

  4. 사용자 API의 IAM 기반 승인 선택

  5. 엔드포인트 URL 검색

  6. SigV4용 카탈로그 통합 만들기

  7. IAM에서 신뢰 관계 구성

Amazon API Gateway에서 REST API 만들기

Snowflake를 Iceberg REST 카탈로그에 연결하려면 Amazon API Gateway에서 REST API 리소스 가 필요합니다.

아직 Amazon API 게이트웨이에 Iceberg 카탈로그에 대한 REST API 리소스가 없는 경우, Iceberg 카탈로그 OpenAPI 정의 파일을 수정 및 가져오거나 엔드포인트를 수동으로 추가하여 간단한 REST API 를 만들 수 있습니다.

참고

Iceberg 카탈로그 OpenAPI 정의를 가져오려면 YAML 파일을 수정해야 합니다. Amazon API 게이트웨이는 OpenAPI 2.0 또는 3.0 사양의 모든 구성 요소를 지원하지 않습니다. 자세한 내용은 REST APIs 의 Amazon API 게이트웨이 중요 참고 사항 섹션을 참조하십시오.

  1. AWS 관리 콘솔에서 API Gateway 를 검색하여 선택합니다.

  2. Create API 를 선택합니다.

  3. REST API 에서 Build 를 선택합니다. 비공개 REST API를 생성하려면 REST API Private 에서 Build 를 선택합니다.

  4. 다음 옵션 중 하나를 선택합니다.

    • 엔드포인트를 수동으로 추가하여 API를 생성하려면 New API 를 선택합니다.

    • OpenAPI 정의 파일을 사용하여 API를 생성하려면 Import API 를 선택한 다음 파일을 업로드하거나 코드 편집기에 정의를 붙여넣습니다.

  5. API name 및 선택 사항 Description 을 입력합니다.

    참고

    비공개 REST API를 생성할 때 VPC 엔드포인트 ID를 입력할 필요가 없습니다.

  6. Create API 를 선택합니다.

API Gateway에서 REST API를 생성하고 개발하는 방법에 대한 자세한 내용은 Amazon API Gateway 개발자 가이드 를 참조하십시오.

IAM 정책을 생성하고 역할에 연결

이 단계에서는 Snowflake가 API 게이트웨이에 연결하는 데 사용할 수 있는 AWS IAM 역할을 생성합니다. API를 호출할 수 있는 권한을 부여하는 정책을 역할에 연결합니다.

  1. AWS 관리 콘솔에서 IAM 을 검색하여 선택합니다.

  2. 왼쪽 탐색 창에서 Policies 를 선택합니다.

  3. Create policy 를 선택한 다음 Policy editor 에 대한 JSON 을 선택합니다.

  4. 빈 정책을 API 메서드를 호출할 수 있는 권한이 있는 정책으로 교체합니다. 예를 들어, 다음 일반 정책은 AWS 계정의 모든 API Gateway 리소스에 대한 호출 작업을 허용합니다

    {
      "Version": "2012-10-17",
      "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": "arn:aws:execute-api:*:<aws_account_id>:*"
        }
      ]
    }
    
    Copy

    중요

    가장 좋은 방법은 사용 사례에 필요한 최소한의 권한을 부여하는 정책을 사용하는 것입니다. 추가 지침 및 예시 정책은 IAM 권한으로 API에 대한 액세스 제어 섹션을 참조하십시오.

  5. Next 를 선택합니다.

  6. Policy name (예: snowflake_access)과 선택 사항인 Description 을 입력합니다.

  7. Create policy 를 선택합니다.

  8. IAM 대시보드의 왼쪽 탐색 창에서 Roles 를 선택합니다.

  9. 정책을 연결할 역할을 선택합니다. 카탈로그 통합을 생성할 때 이 역할을 지정합니다. 역할이 없는 경우 새 역할을 생성합니다.

  10. Permissions 탭의 역할 Summary 페이지에서 Add permissions » Attach policies 를 선택합니다.

  11. API Gateway에 대해 생성한 정책을 검색하여 옆의 확인란을 선택한 다음 Add permissions 를 선택합니다.

  12. 역할 Summary 페이지에서 ARN 역할을 복사합니다. 카탈로그 통합을 생성할 때 이 ARN을 지정합니다.

API Gateway 리소스 정책 연결(비공개 APIs만 해당)

REST API가 비공개인 경우 API에 Amazon API Gateway 리소스 정책을 연결해야 합니다. Snowflake는 리소스 정책을 통해 Snowflake 계정이 있는 Amazon Virtual Private Cloud(VPC)에서 API를 호출할 수 있습니다.

  1. Snowflake에서 SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO 함수를 호출하여 내 Snowflake 계정이 있는 VPC에 대한 ID를 검색합니다. 함수 출력에서 VPC ID를 복사합니다.

    SELECT SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO();
    
    Copy

    출력:

    {"snowflake-vpc-id":["vpc-c1c234a5"]}
    
  2. API Gateway 리소스 정책 연결하기 섹션의 지침에 따라 REST API에 리소스 정책을 연결합니다.

    다음 예제 정책을 붙여넣고 수정합니다.

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Deny",
          "Principal": "*",
          "Action": "execute-api:Invoke",
          "Resource": "<api_gateway_arn>",
          "Condition": {
            "StringNotEquals": {
              "aws:sourceVpc": "<snowflake_vpc_id>"
            }
          }
        },
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:sts::123456789XXX:assumed-role/<my_api_permissions_role_name>/snowflake"
          },
          "Action": "execute-api:Invoke",
          "Resource": "<api_gateway_arn>/*/*/*",
          "Condition": {
            "StringEquals": {
              "aws:sourceVpc": "<snowflake_vpc_id>"
            }
          }
        }
      ]
    }
    
    Copy

정책의 첫 번째 문은 Snowflake VPC에서 시작되지 않은 모든 요청을 거부합니다. 두 번째 문은 가정된 역할 세션 주체 를 사용하는 Snowflake VPC에서 시작된 요청에서 호출 작업(모든 메서드에 대해)을 허용합니다.

API Gateway 리소스 정책에 대해 자세히 알아보려면 다음을 참조하십시오.

사용자 API의 IAM 기반 승인 선택

REST API에서 액세스를 제공할 각 메서드에 대해 IAM 기반 승인을 선택합니다. IAM 기반 승인을 사용하면 Snowflake는 사용자가 구성한 IAM 역할을 사용하여 API를 호출할 수 있습니다.

  1. Amazon API Gateway 콘솔에서 REST API를 선택합니다.

  2. 각 메서드에 대해:

    1. Resources 의 목록에서 메서드를 선택합니다.

    2. Method request settings 에서 Edit 를 선택합니다.

    3. Authorization 에서 AWS IAM 을 선택합니다.

    4. Save 를 선택합니다.

  3. 승인 변경 사항을 적용하려면 Deploy API 를 선택합니다. 자세한 내용은 API Gateway 콘솔에서 REST API 배포하기 섹션을 참조하십시오.

엔드포인트 URL 검색

REST API 엔드포인트 URL(또는 호출 URL)을 검색합니다. 엔드포인트 URL을 검색하려면 먼저 API를 스테이지에 배포해야 합니다.

  1. Amazon API Gateway 콘솔에서 REST API를 선택합니다.

  2. 왼쪽 탐색 창에서 Stages 를 선택합니다.

  3. Stage details 에서 Invoke URL 을 복사합니다.

카탈로그 통합을 생성할 때 엔드포인트 URL을 지정합니다.

SigV4용 카탈로그 통합 만들기

Amazon API Gateway에 REST API가 있고 IAM 권한을 사용하여 API에 대한 액세스를 제어하는 초기 단계를 완료한 후에는 Snowflake에서 카탈로그 통합을 생성할 수 있습니다.

명령 구문과 매개 변수 설명을 살펴보려면 CREATE CATALOG INTEGRATION(Apache Iceberg™ REST) 섹션을 참조하십시오.

공용 REST API

공용 REST API에 대한 카탈로그 통합을 생성하려면 ICEBERG_RESTCATALOG_SOURCE 로 지정하고 SIGV4 인증을 사용합니다.

API 엔드포인트 URL 및 IAM 역할 ARN과 같은 세부 정보를 포함합니다.

CREATE OR REPLACE CATALOG INTEGRATION my_rest_catalog_integration
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://asdlkfjwoalk-execute-api.us-west-2-amazonaws.com/MyApiStage'
    CATALOG_API_TYPE = AWS_API_GATEWAY
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789XXX:role/my_api_permissions_role'
    SIGV4_EXTERNAL_ID = 'my_iceberg_external_id'
  )
  ENABLED = TRUE;
Copy

비공개 REST API

비공개 REST API에 대한 카탈로그 통합을 생성하려면 CATALOG_API_TYPE 매개 변수를 AWS_PRIVATE_API_GATEWAY 으로 설정해야 합니다.

CREATE OR REPLACE CATALOG INTEGRATION my_rest_catalog_integration
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://asdlkfjwoalk-execute-api.us-west-2-amazonaws.com/MyApiStage'
    CATALOG_API_TYPE = AWS_PRIVATE_API_GATEWAY
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789XXX:role/my_api_permissions_role'
    SIGV4_EXTERNAL_ID = 'my_iceberg_external_id'
  )
  ENABLED = TRUE;
Copy

참고

두 예제 모두 IAM 역할(다음 단계에서)에 대한 신뢰 관계에서 사용할 수 있는 외부 ID (SIGV4_EXTERNAL_ID = 'my_iceberg_external_id')를 지정합니다.

외부 ID 를 지정하면 IAM 역할 신뢰 정책을 업데이트하지 않고도 여러 카탈로그 통합에서 동일한 IAM 역할을 사용할 수 있습니다. 이렇게 하면 카탈로그 통합을 여러 번 만들거나 교체해야 하는 경우 시나리오를 테스트할 때 특히 유용합니다.

IAM에서 신뢰 관계 구성

카탈로그 통합을 만들 때 Snowflake 계정에 대해 생성된 AWS IAM 사용자에 대한 정보를 검색하고 IAM 역할에 대한 신뢰 관계를 구성합니다.

  1. Snowflake에서 DESCRIBE CATALOG INTEGRATION 명령을 호출합니다.

    DESCRIBE CATALOG INTEGRATION my_rest_catalog_integration;
    
    Copy

    다음 값을 기록합니다.

    설명

    API_AWS_IAM_USER_ARN

    Snowflake 계정용으로 생성된 AWS IAM 사용자입니다(예: arn:aws:iam::123456789001:user/abc1-b-self1234). Snowflake는 전체 Snowflake 계정에 대해 단일 IAM 사용자를 프로비저닝합니다.

    API_AWS_EXTERNAL_ID

    신뢰 관계를 구축하는 데 필요한 외부 ID입니다. 카탈로그 통합을 만들 때 외부 ID(SIGV4_EXTERNAL_ID)를 지정하지 않은 경우 Snowflake에서 ID 를 생성하여 사용할 수 있도록 합니다. 생성된 외부 ID로 IAM 역할 신뢰 정책을 업데이트할 수 있도록 값을 기록합니다.

  2. AWS 관리 콘솔에서 IAM 을 검색하여 선택합니다.

  3. 왼쪽 탐색 창에서 Roles 를 선택합니다.

  4. 카탈로그 통합에 대해 생성한 IAM 역할을 선택합니다.

  5. Trust relationships 탭을 선택합니다.

  6. Edit trust policy 를 선택합니다.

  7. 기록한 값으로 정책 문서를 수정합니다.

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "",
          "Effect": "Allow",
          "Principal": {
            "AWS": "<api_aws_iam_user_arn>"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "<api_aws_external_id>"
            }
          }
        }
      ]
    }
    
    Copy
  8. Update policy 를 선택하여 변경 사항을 저장합니다.

SigV4 (Glue)

이 섹션의 단계에 따라 Signature Version 4(SigV4) 인증을 사용하여 AWS Glue Iceberg REST 엔드포인트 에 대한 카탈로그 통합을 생성하십시오.

1단계: AWS Glue Data Catalog에 대한 액세스 허가 구성

AWS Glue 데이터 카탈로그에 액세스하기 위해 Snowflake에 대한 IAM 정책을 만듭니다. 카탈로그 통합을 만들 때 지정하는 IAM 역할에 정책을 첨부합니다. 지침은 AWS Identity and Access Management 사용자 가이드에서 IAM 정책 만들기역할 권한 정책 수정하기 를 참조하십시오.

Snowflake는 최소한 다음 권한이 필요합니다. AWS Glue 데이터 카탈로그에서 다음 권한을 사용하여 Glue Iceberg REST 카탈로그를 사용하여 정보에 액세스합니다.

  • glue:GetConfig

  • glue:GetDatabase

  • glue:GetDatabases

  • glue:GetTable

  • glue:GetTables

다음 예시 정책(JSON 형식)에서는 지정된 데이터베이스의 모든 테이블에 액세스하는 데 필요한 권한을 제공합니다.

{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Sid": "AllowGlueCatalogTableAccess",
         "Effect": "Allow",
         "Action": [
           "glue:GetConfig",
           "glue:GetDatabase",
           "glue:GetDatabases",
           "glue:GetTable",
           "glue:GetTables"
         ],
         "Resource": [
            "arn:aws:glue:*:<accountid>:table/*/*",
            "arn:aws:glue:*:<accountid>:catalog",
            "arn:aws:glue:*:<accountid>:database/<database-name>"
         ]
      }
   ]
}
Copy

참고

  • 이 정책의 Resource 요소를 수정하여 허용되는 리소스(예: 카탈로그, 데이터베이스 또는 테이블)를 추가로 제한할 수 있습니다. 자세한 내용은 AWS Glue에서 정의된 리소스 유형 을 참조하십시오.

  • AWS Glue에 암호화를 사용하는 경우 AWS Key Management Service(AWS KMS) 권한을 추가하도록 정책을 수정해야 합니다. 자세한 내용은 AWS Glue에서 암호화 설정하기 를 참조하십시오.

2단계: Snowflake에서 카탈로그 통합 만들기

CREATE CATALOG INTEGRATION(Apache Iceberg™ REST) 명령을 사용하여 AWS Glue Iceberg REST 엔드포인트 에 대한 카탈로그 통합을 만듭니다. 구성한 IAM 역할을 지정합니다. WAREHOUSE 의 경우 AWS 계정 ID 를 사용합니다.

CREATE CATALOG INTEGRATION glue_rest_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'rest_catalog_integration'
  REST_CONFIG = (
    CATALOG_URI = 'https://glue.us-west-2.amazonaws.com/iceberg'
    CATALOG_API_TYPE = AWS_GLUE
    WAREHOUSE = '123456789012'
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789012:role/my-role'
    SIGV4_SIGNING_REGION = 'us-west-2'
  )
  ENABLED = TRUE;
Copy

REST 카탈로그 구성 확인하기

다음 시나리오를 사용하여 Snowflake가 카탈로그 서버와 상호 작용할 수 있도록 Iceberg REST 카탈로그에 대한 인증 및 액세스 제어를 올바르게 구성했는지 확인할 수 있습니다.

SYSTEM$VERIFY_CATALOG_INTEGRATION 사용

SYSTEM$VERIFY_CATALOG_INTEGRATION 함수를 사용하여 카탈로그 통합 구성을 확인할 수 있습니다.

다음 예제는 시스템 함수가 부적절하게 구성된 카탈로그 통합의 문제를 포착하고 보고하는 방법을 보여줍니다.

다음 예제 문은 잘못된 OAuth 클라이언트 시크릿을 사용하여 REST 카탈로그 통합을 생성합니다(오류 없이 실행됨):

CREATE CATALOG INTEGRATION my_rest_cat_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = 'https://abc123.us-west-2.aws.myapi.com/polaris/api/catalog'
    WAREHOUSE = 'my_warehouse'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = '123AbC ...'
    OAUTH_CLIENT_SECRET = '1365910abIncorrectSecret ...'
    OAUTH_ALLOWED_SCOPES = ('all-apis', 'sql')
  )
  ENABLED = TRUE;
Copy

시스템 함수를 사용하여 카탈로그 통합을 확인하고 실패를 예상합니다.

SELECT SYSTEM$VERIFY_CATALOG_INTEGRATION('my_rest_cat_int');
Copy

출력:

+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|                                                                                                              SYSTEM$VERIFY_CATALOG_INTEGRATION('MY_REST_CAT_INT')                                                                                                               |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| {                                                                                                                                                                                                                                                                               |
|  "success" : false,                                                                                                                                                                                                                                                             |                                                                                                                                                                                                                                                                    |
|   "errorCode" : "004155",                                                                                                                                                                                                                                                       |
|   "errorMessage" : "SQL Execution Error: Failed to perform OAuth client credential flow for the REST Catalog integration MY_REST_CAT_INT due to error: SQL execution error: OAuth2 Access token request failed with error 'unauthorized_client:The client is not authorized'.." |
| }                                                                                                                                                                                                                                                                               |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

OAuth 에 대한 구성 확인

원격 REST 카탈로그를 사용하여 OAuth 구성을 확인하려면 다음 단계를 따르십시오.

1단계: 엑세스 토큰 검색하기

curl 명령을 사용하여 카탈로그에서 엑세스 토큰을 검색합니다. 다음 예제는 Snowflake Open Catalog 에서 엑세스 토큰을 요청합니다.

curl -X POST https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens \
    -H "Accepts: application/json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "grant_type=client_credentials" \
    --data-urlencode "scope=PRINCIPAL_ROLE:ALL" \
    --data-urlencode "client_id=<my_client_id>" \
    --data-urlencode "client_secret=<my_client_secret>" | jq
Copy

여기서

  • https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens 는 OAuth 토큰을 검색하는 엔드포인트입니다(getToken).

  • scope 은 카탈로그 통합을 생성할 때 OAUTH_ALLOWED_SCOPES 매개 변수에 지정하는 값과 동일합니다. 범위가 여러 개인 경우 공백을 구분 기호로 사용합니다.

  • my_client_id 는 카탈로그 통합을 생성할 때 OAUTH_CLIENT_ID 매개 변수에 지정한 것과 동일한 클라이언트 ID 입니다.

  • my_client_secret 은 카탈로그 통합을 만들 때 OAUTH_CLIENT_SECRET 매개 변수에 지정한 것과 동일한 클라이언트 시크릿입니다.

반환 값 예제:

{
  "access_token": "xxxxxxxxxxxxxxxx",
  "token_type": "bearer",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "expires_in": 3600
}

2단계: 엑세스 토큰 권한 확인하기

이전 단계에서 검색한 엑세스 토큰을 사용하여 카탈로그 서버에 액세스할 수 있는 권한이 있는지 확인합니다.

curl 명령을 사용하여 카탈로그의 구성 설정을 목록으로 만들 수 있습니다.

curl -X GET "https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<warehouse>" \
    -H "Accepts: application/json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq
Copy

여기서

  • ?warehouse=warehouse 는 선택적으로 카탈로그에서 요청할 웨어하우스 이름을 지정합니다(지원되는 경우). Snowflake Open Catalog 의 경우 웨어하우스 이름은 카탈로그 이름입니다.

  • ACCESS_TOKEN 은 이전 단계에서 검색한 access_token 을 포함하는 변수입니다.

반환 값 예제:

{
  "defaults": {
    "default-base-location": "s3://my-bucket/polaris/"
  },
  "overrides": {
    "prefix": "my-catalog"
  }
}

3단계: 카탈로그에서 테이블 로드하기

GET 으로 요청하여 테이블을 로딩할 수도 있습니다. Snowflake는 loadTable 작업을 사용하여 REST 카탈로그에서 테이블 데이터를 로드합니다.

curl -X GET "https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/<prefix>/namespaces/<namespace>/tables/<table>" \
    -H "Accepts: application/json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq
Copy

여기서

  • prefix 는 선택적으로 이전 getConfig 응답에서 얻은 접두사를 지정합니다.

  • namespace 는 검색하려는 테이블의 네임스페이스입니다. 네임스페이스가 중첩된 경우 %1F 구분 기호를 사용합니다(예: parentNamespace%1FchildNamespace).

  • table 은 테이블 이름입니다.

무기명 토큰에 대한 구성 확인

다음 단계에 따라 원격 REST 카탈로그에서 무기명 토큰 사용에 대한 구성을 확인하십시오.

1단계: 엑세스 토큰 권한 확인하기

curl 명령을 사용하여 카탈로그 서버에 액세스할 수 있는 권한이 있는지 확인합니다.

curl -X GET "https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<warehouse>" \
    -H "Accepts: application/json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: Bearer ${BEARER_TOKEN}" | jq
Copy

여기서

  • https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens 는 OAuth 토큰을 검색하는 엔드포인트입니다(getToken).

  • ?warehouse=warehouse 는 선택적으로 카탈로그에서 요청할 웨어하우스 이름을 지정합니다(지원되는 경우).

  • BEARER_TOKEN 은 이전 단계에서 검색한 access_token 을 포함하는 변수입니다.

반환 값 예제:

{
  "defaults": {
    "default-base-location": "s3://my-bucket/polaris"
  },
  "overrides": {
    "prefix": "my-catalog"
  }
}

2단계: 카탈로그에서 테이블 로드하기

GET 으로 요청하여 테이블을 로딩할 수도 있습니다. Snowflake는 loadTable 작업을 사용하여 REST 카탈로그에서 테이블 데이터를 로드합니다.

curl -X GET "https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/<prefix>/namespaces/<namespace>/tables/<table>" \
    -H "Accepts: application/json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: Bearer ${BEARER_TOKEN}" | jq
Copy

여기서

  • prefix 는 선택적으로 이전 getConfig 응답에서 얻은 접두사를 지정합니다.

  • namespace 는 검색하려는 테이블의 네임스페이스입니다. 네임스페이스가 중첩된 경우 %1F 구분 기호를 사용합니다(예: parentNamespace%1FchildNamespace).

  • table 은 테이블 이름입니다.

SigV4 에 대한 구성 확인

AWS 로 SigV4 에 대한 구성을 확인하려면 다음 단계를 따르십시오.

1단계: IAM 역할 신뢰 관계에 사용자를 추가합니다

SigV4 에 대한 REST 카탈로그 통합을 생성하면 Snowflake는 AWS IAM 사용자를 Snowflake 계정에 프로비저닝합니다. API 게이트웨이 리소스에 액세스할 수 있는 권한이 있는 IAM 역할 에 대한 IAM 사용자를 신뢰 관계에 추가 합니다.

구성을 테스트하려면 사용자는 역할의 신뢰 정책 문서에 AWS 사용자를 추가한 후 AWS 계정에서 사용자로 역할을 맡을 수 있습니다. 현재 IAM 사용자를 검색하려면 ARN, AWS 명령줄 인터페이스(CLI)에 sts get-caller-identity 명령을 사용합니다. :

aws sts get-caller-identity
Copy

출력 예:

{
  "UserId": "ABCDEFG1XXXXXXXXXXX",
  "Account": "123456789XXX",
  "Arn": "arn:aws:iam::123456789XXX:user/managed/my_user"
}

업데이트된 신뢰 정책 문서에는 다음과 같이 Snowflake 사용자(ARN)와 사용자(ARN)가 모두 포함되어야 합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "<snowflake_iam_user_arn>",
          "<my_iam_user_arn>"
        ]
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "my_external_id"
        }
      }
    }
  ]
}
Copy

전체 지침은 AWS IAM 설명서의 역할 신뢰 정책 업데이트 섹션을 참조하십시오.

2단계: 임시 자격 증명을 얻기 위해 IAM 역할을 가정합니다.

AWS 에 대한 임시 보안 자격 증명을 얻으려면 sts assume-role 명령을 사용하여 AWS CLI 에 대한 임시 보안 자격 증명을 얻습니다.

aws sts assume-role \
  --role-arn <my_role_arn> \
  --role-session-name <session_name>
Copy

여기서

  • my_role_arn 는 Snowflake에 대해 구성한 IAM 역할의 Amazon 리소스 이름(ARN)입니다.

  • session_name 는 가정된 역할 세션에 대해 사용자가 선택한 문자열 식별자입니다(예: my_rest_session).

출력 예:

{
  "Credentials": {
      "AccessKeyId": "XXXXXXXXXXXXXXXXXXXXX",
      "SecretAccessKey": "XXXXXXXXXXXXXXXXXXXXX",
      "SessionToken": "XXXXXXXXXXXXXXXXXXXXX",
      "Expiration": "2024-10-09T08:13:15+00:00"
  },
  "AssumedRoleUser": {
      "AssumedRoleId": "{AccessKeyId}:my_rest_catalog_session",
      "Arn": "arn:aws:sts::123456789XXX:assumed-role/my_catalog_role/my_rest_catalog_session"
  }
}

참고

assume-role 명령이 실패하면 현재 AWS 사용자가 역할의 신뢰 정책에 허용된 주체로 포함되어 있지 않다는 의미입니다.

마찬가지로 Snowflake IAM 사용자 ARN 이 신뢰 정책에 포함되지 않은 경우 Snowflake는 API 게이트웨이 리소스에 연결할 수 없습니다. 자세한 내용은 IAM에서 신뢰 관계 구성 섹션을 참조하십시오.

3단계: IAM 역할에 올바른 권한이 있는지 확인합니다

이전 단계에서 검색한 임시 자격 증명을 사용하여 IAM 역할에 API 게이트웨이 APIs 를 호출할 수 있는 권한이 있는지 확인합니다.

curl 명령을 사용하여 카탈로그의 구성 설정을 목록으로 만들 수 있습니다.

curl -v -X GET  "https://123xxxxxxx.execute-api.us-west-2.amazonaws.com/test_v2/v1/config?warehouse=<warehouse>" \
  --user "$AWS_ACCESS_KEY_ID":"$AWS_SECRET_ACCESS_KEY" \
  --aws-sigv4 "aws:amz:us-west-2:execute-api" \
  -H "x-amz-security-token: $AWS_SESSION_TOKEN"
Copy

여기서

  • 123xxxxxxx.execute-api.us-west-2.amazonaws.com 은 API 게이트웨이 호스트 이름입니다.

  • test_v2 는 API 가 배포되는 스테이지의 이름입니다.

  • v1/config 는 Iceberg 카탈로그 OpenAPI 정의에서 getConfig 작업을 지정합니다.

  • ?warehouse=warehouse 는 선택적으로 카탈로그에서 요청할 웨어하우스 이름을 지정합니다(지원되는 경우).

  • $AWS_ACCESS_KEY_IDsts assume-role 명령을 사용하여 검색한 AccessKeyId 를 포함하는 변수입니다.

  • $AWS_SECRET_ACCESS_KEYsts assume-role 명령을 사용하여 검색한 SecretAccessKey 를 포함하는 변수입니다.

  • aws:amz:us-west-2:execute-api 는 SigV4 프로토콜의 서명 이름입니다. AWS Glue의 경우 aws:amz:us-west-2:glue 를 대신 사용하십시오.

  • $AWS_SESSION_TOKENsts assume-role 명령을 사용하여 검색한 SessionToken 을 포함하는 변수입니다.

반환 값 예제:

{
  "defaults": {},
  "overrides": {
    "prefix": "my-catalog"
  }
}

GET 으로 요청하여 테이블을 로딩할 수도 있습니다. Snowflake는 loadTable 작업을 사용하여 REST 카탈로그에서 테이블 데이터를 로드합니다.

curl -v -X GET "https://123xxxxxxx.execute-api.us-west-2.amazonaws.com/test_v2/v1/<prefix>/namespaces/<namespace>/tables/<table>" \
    --user "$AWS_ACCESS_KEY_ID":"$AWS_SECRET_ACCESS_KEY" \
    --aws-sigv4 "aws:amz:us-west-2:execute-api" \
    -H "x-amz-security-token: $AWS_SESSION_TOKEN"
Copy

여기서

  • prefix 는 선택적으로 이전 getConfig 응답에서 얻은 접두사를 지정합니다.

  • namespace 는 검색하려는 테이블의 네임스페이스입니다. 네임스페이스가 중첩된 경우 %1F 구분 기호를 사용합니다(예: parentNamespace%1FchildNamespace).

  • table 은 테이블 이름입니다.

비공개 API

비공개 API 의 경우 동일한 curl 명령에서 VPC 엔드포인트와 비공개 Amazon API 게이트웨이 호스트 이름을 지정할 수 있습니다.

예:

curl -v -X GET  "https://vpce-xxxxxxxxxxxxxxxxxxxxxxxxxx.execute-api.us-west-2.vpce.amazonaws.com/test_v2/v1/config?warehouse=<warehouse>" \
  --user "$AWS_ACCESS_KEY_ID":"$AWS_SECRET_ACCESS_KEY" \
  --aws-sigv4 "aws:amz:us-west-2:execute-api" \
  -H "x-amz-security-token: $AWS_SESSION_TOKEN"
  -H "Host: abc1defgh2.execute-api.us-west-2.amazonaws.com"
Copy

여기서

  • https://vpce-xxxxxxxxxxxxxxxxxxxxxxxxxx.execute-api.us-west-2.vpce.amazonaws.com/... 은 VPC 엔드포인트의 호스트 이름입니다.

  • abc1defgh2.execute-api.us-west-2.amazonaws.com 은 Amazon API 게이트웨이에서 비공개 API 의 호스트 이름입니다.