为 Amazon API Gateway 配置目录集成¶

在 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 的 IDs。在函数输出中，对于使用 "purpose": "generic" 标识的每个属性，记录相应的 VPC ID。

   SELECT SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO();
   

   Copy

   输出：

   {
     "snowflake-vpc-id": ["vpc-c1c234a5"],
     "snowflake-egress-vpc-ids": [
       ...
       {
         "id": "vpc-c1c234a5",
         "expires": "2025-03-01T00:00:00",
         "purpose": "generic"
       },
       ...
     ]
   }
   

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 保存更改。