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'
    CATALOG_NAME = 'my_catalog_name'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = '123AbC ...'
    OAUTH_CLIENT_SECRET = '1365910abIncorrectSecret ...'
    OAUTH_ALLOWED_SCOPES = ('all-apis', 'sql')
  )
  ENABLED = TRUE;

システム関数を使用して、カタログの統合を確認します。

SELECT SYSTEM$VERIFY_CATALOG_INTEGRATION('my_rest_cat_int');

出力:

+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|                                                                                                              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

条件:

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 はテーブル名です。

ベアラートークンの構成の確認¶

以下の手順に従って、ベアラートークンを使用するための構成をリモートの 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

条件:

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: カタログからテーブルをロードする¶

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 はテーブル名です。

SigV4 の構成の確認¶

以下の手順に従って、 AWS で SigV4 の構成を確認します。

ステップ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"
  }
}

注釈

assume-role コマンドが失敗した場合、現在の AWS ユーザーがロールの信頼ポリシーに許可されたプリンシパルとして含まれていないことを意味します。

同様に、Snowflake IAM ユーザー ARN が信頼ポリシーに含まれていない場合、Snowflakeは API Gatewayリソースに接続できません。詳細については、 IAM の信頼関係を設定するをご参照ください。

ステップ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"
  }
}

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 のホスト名です。