Apache Iceberg™ REST カタログのカタログ統合を構成する¶

Amazon API Gatewayで REST API を作成¶

SnowflakeをIceberg REST カタログに接続するには、Amazon API Gatewayの REST API リソース が必要です。

Amazon API GatewayにIcebergカタログ用の REST API リソースがまだない場合は、Icebergカタログ OpenAPI 定義ファイルを修正してインポートするか、手動でエンドポイントを追加することで、シンプルな REST 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 Gatewayに接続するために使用できる 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 がプライベートの場合、Amazon API Gatewayリソースポリシーを API に添付する必要があります。リソースポリシーにより、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 から発信されていないすべてのリクエストを拒否します。2番目のステートメントは、 想定ロールセッションプリンシパル を使用するSnowflake VPC から発信されるリクエストからの（すべてのメソッドに対する）呼び出しアクションを許可します。

API Gatewayリソースポリシーについては、こちらをご覧ください。

• API Gatewayリソースポリシーで API へのアクセスを制御する

• 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 のカタログ統合を作成するには、 CATALOG_SOURCE として ICEBERG_REST を指定し、 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;

プライベート 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;

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 を選択して変更を保存します。

ステップ1: AWS Glueデータカタログのアクセス許可を構成する¶

Snowflakeが AWS Glueデータカタログにアクセスするための IAM ポリシーを作成します。カタログ統合を作成するときに指定する IAM ロールにポリシーを添付します。手順については、 AWS IDおよびアクセス管理ユーザーガイドの IAM ポリシーの作成 と ロール権限ポリシーの変更 をご参照ください。

SnowflakeがGlue Iceberg REST カタログを使用して情報にアクセスするには、少なくとも、 AWS Glueデータカタログに対する以下の権限が必要です。

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

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

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