REST 카탈로그 구성 확인하기¶

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

여기서

• 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

여기서

• ?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

여기서

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

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

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

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

여기서

• 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

여기서

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

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

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

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

출력 예:

{
  "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"
        }
      }
    }
  ]
}

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

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

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

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

여기서

• 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"
  }
}

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"

여기서

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

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

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

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

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

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

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

• $AWS_SESSION_TOKEN 는 sts 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"

여기서

• 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"

여기서

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

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