为|iceberg-tm| REST 目录配置目录集成¶

在 Amazon API Gateway 中创建 REST API¶

要将 Snowflake 连接到 Iceberg REST 目录，您需要在 Amazon API Gateway 中建立 REST API 资源 (https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html)。

如果 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 开发者指南 (https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-develop.html)。

创建 IAM 策略并将其附加到角色上¶

在此步骤中，您将创建一个 AWS IAM 角色，Snowflake 可使用该角色连接到 API Gateway。您为角色附加了一个策略，以授予调用 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 的访问 (https://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html)。

5. 选择 Next。

6. 输入 Policy name （例如 snowflake_access）和可选的 Description。

7. 选择 Create policy。

8. 在 IAM 仪表板的左侧导航窗格中，选择 Roles。

9. 选择要附加策略的角色。创建目录集成时，需要指定该角色。如果您没有角色，请 创建新角色 (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html)。

10. 在角色 Summary 页面的 Permissions 选项卡中，选择 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 资源策略 (https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies-create-attach.html#apigateway-resource-policies-create-attach-console) 中的说明，将资源策略附加到 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 且使用 假设角色会话主体 (https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-role-session) 的请求执行调用操作（针对所有方法）。

要了解有关 API Gateway 资源政策的更多信息，请参阅：

• 利用 API 网关资源策略控制对 API 的访问 (https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies.html)

• API Gateway 资源策略示例 (https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies-examples.html)

为 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 (https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-deploy-api-with-console.html)。

检索端点 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_REST 指定为:code:CATALOG_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;

专用 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 步：检索访问令牌¶

使用 curl 命令从目录中检索访问令牌。下面的示例请求从 Snowflake Open Catalog 获取访问令牌：

curl -X POST https://xx123xx.us-west-2.aws.snowflakecomputing.cn/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.cn/polaris/api/catalog/v1/oauth/tokens 是检索 OAuth 令牌 (getToken (https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L132)) 的端点。

• 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 POST "https://xx123xx.us-west-2.aws.snowflakecomputing.cn/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 (https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L616) 操作从 REST 目录中加载表数据。

curl -X POST "https://xx123xx.us-west-2.aws.snowflakecomputing.cn/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 POST "https://xx123xx.us-west-2.aws.snowflakecomputing.cn/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.cn/polaris/api/catalog/v1/oauth/tokens 是检索 OAuth 令牌 (getToken (https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L132)) 的端点。

• ?warehouse=warehouse 可选择指定从目录中请求的仓库名称（如果支持）。

• BEARER_TOKEN 是一个变量，其中包含您在上一步中检索到的 access_token。

返回值示例：

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

第 2 步：从目录中加载表¶

您也可以发出 GET 请求来加载表。Snowflake 使用 loadTable (https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L616) 操作从 REST 目录中加载表数据。

curl -X POST "https://xx123xx.us-west-2.aws.snowflakecomputing.cn/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 会为 Snowflake 账户配置 AWS IAM 用户。您 将该 Snowflake IAM 用户添加到 :ref:`IAM 角色 的信任关系 <label-tables_iceberg_rest_catalog_integration_trust_relationship_sigv4>` 中，该角色有权访问 API Gateway 资源。

要测试您的配置，您 可以在将 AWS 用户添加到角色的信任策略文档后，以 AWS 账户中的用户身份担任该角色。要检索当前 IAM 用户 ARN，请使用 AWS 命令行界面 (CLI) (https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) 的 sts get-caller-identity (https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sts/get-caller-identity.html) 命令：

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 文档中的`更新角色信任策略 <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-trust-policy.html (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-trust-policy.html)>`_。

第 2 步：假设 IAM 角色以获取临时凭证¶

要获取 AWS 的临时安全凭证，请使用 AWS CLI 的 sts assume-role (https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sts/assume-role.html) 命令。

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 (https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L65) 操作。

• ?warehouse=warehouse 可选择指定从目录中请求的仓库名称（如果支持）。

• $AWS_ACCESS_KEY_ID 是一个变量，其中包含使用 sts assume-role 命令检索的 AccessKeyId。

• $AWS_SECRET_ACCESS_KEY 是一个变量，其中包含使用 sts assume-role 命令检索的 SecretAccessKey。

• $AWS_SESSION_TOKEN 是一个变量，其中包含使用 sts assume-role 命令检索的 SessionToken。

返回值示例：

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

您也可以发出 GET 请求来加载表。Snowflake 使用 loadTable (https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml#L616) 操作从 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 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 的主机名。