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 は取得したいテーブルの名前空間です。名前空間が入れ子になっている場合は、 parentNamespace%1FchildNamespace のように、 %1F 区切り文字を使用します。

• 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 は取得したいテーブルの名前空間です。名前空間が入れ子になっている場合は、 parentNamespace%1FchildNamespace のように、 %1F 区切り文字を使用します。

• table はテーブル名です。

ステップ1: IAM ロールの信頼関係にユーザーを追加する¶

SigV4 用の REST カタログ統合を作成すると、SnowflakeはSnowflakeアカウントに AWS IAM ユーザーをプロビジョニングします。API Gatewayリソースへのアクセス権限を持つ IAM ロール の信頼関係に、 そのSnowflake 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 Gateway 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 Gateway のホスト名です。

• 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 は取得したいテーブルの名前空間です。名前空間が入れ子になっている場合は、 parentNamespace%1FchildNamespace のように、 %1F 区切り文字を使用します。

• table はテーブル名です。

プライベート API

プライベート API の場合、同じ curl コマンドで VPC エンドポイントとプライベートAmazon API Gateway のホスト名を指定できます。

例:

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 Gateway のプライベート API のホスト名です。