Configure uma integração de catálogo para o Amazon API Gateway¶

Criar uma REST API no Amazon API Gateway¶

Para conectar o Snowflake ao seu catálogo Iceberg REST, você precisa de um recurso REST API no Amazon API Gateway.

Se você ainda não tiver um recurso REST API no Amazon API Gateway para o seu catálogo Iceberg, poderá criar um REST API simples modificando e importando um arquivo de definição OpenAPI do catálogo Iceberg ou adicionando manualmente os pontos de extremidade.

1. No Console de gerenciamento da AWS, procure e selecione API Gateway.

2. Selecione Create API.

3. Selecione Build em REST API. Para criar uma REST API privada, selecione Build em REST API Private.

4. Selecione uma das seguintes opções:

   • Para criar uma API adicionando pontos de extremidade manualmente, selecione New API.

   • Para criar uma API usando um arquivo de definição OpenAPI, selecione Import API e carregue o arquivo ou cole a definição no editor de código.

5. Insira um API name e Description opcional.

   Nota

   Você não precisa inserir um ID de ponto de extremidade VPC ao criar uma RESTAPI privada.

6. Selecione Create API.

Para obter mais informações sobre como criar e desenvolver uma REST API no API Gateway, consulte o Guia do desenvolvedor do Amazon API Gateway.

Criar uma política de IAM e anexá-la a uma função¶

Nessa etapa, você cria uma função AWS IAM que o Snowflake pode usar para se conectar ao API Gateway. Você anexa uma política à função que concede permissão para chamar sua API.

1. No Console de gerenciamento da AWS, procure e selecione IAM.

2. Selecione Policies no painel de navegação à esquerda.

3. Selecione Create policy e depois selecione JSON para o Policy editor.

4. Substitua a política vazia por uma política que tenha permissão para invocar seus métodos de API. Por exemplo, a seguinte política geral permite a ação de invocação para todos os recursos do API Gateway em uma conta AWS.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
           "Effect": "Allow",
           "Action": [
               "execute-api:Invoke"
           ],
           "Resource": "arn:aws:execute-api:*:<aws_account_id>:*"
       }
     ]
   }
   

   Copy

   Importante

   Como prática recomendada, use uma política que conceda os privilégios mínimos necessários para seu caso de uso. Para obter orientações adicionais e exemplos de políticas, consulte Controlar acesso a uma API com permissões IAM.

5. Selecione Next.

6. Insira um Policy name (por exemplo, snowflake_access) e uma Description opcional.

7. Selecione Create policy.

8. Na seção de navegação esquerda do painel IAM, selecione Roles.

9. Selecione uma função para anexar à política. Ao criar uma integração de catálogo, você especifica essa função. Se você não tiver uma função, crie uma nova função.

10. Na página da função Summary, na guia Permissions, selecione Add permissions » Attach policies.

11. Procure e marque a caixa ao lado da política que você criou para o API Gateway e selecione Add permissions.

12. Na página da função Summary, copie a função ARN. Você especifica esse ARN ao criar uma integração de catálogo.

Anexar uma política de recursos do API Gateway (somente APIs privadas)¶

Se a sua REST API for privada, você deverá anexar uma política de recursos do Amazon API Gateway à sua API. A política de recursos permite que o Snowflake chame sua API da Amazon Virtual Private Cloud (VPC) na qual sua conta Snowflake está localizada.

1. No Snowflake, chame a função SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO para obter o IDs para a VPC em que sua conta Snowflake está localizada. Na saída da função, para cada propriedade identificada com “purpose”: “generic”, registre o(s) ID(s) de VPC correspondente(s).

   SELECT SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO();
   

   Copy

   Saída:

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

2. Siga as instruções em Anexando políticas de recursos do API Gateway para anexar uma política de recursos à sua REST API.

   Cole e modifique o seguinte exemplo de política.

   {
     "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

A primeira instrução na política nega todas as solicitações que não se originam da Snowflake VPC. A segunda instrução permite a ação de invocação (para todos os métodos) de solicitações originadas da Snowflake VPC que usam o principal de sessão com função assumida.

Para saber mais sobre as políticas de recursos do API Gateway, consulte:

• Controlando o acesso a uma API com políticas de recursos do API Gateway

• Exemplos de política de recursos do API Gateway

Selecionar a autorização baseada em IAM para a sua API¶

Selecione a autorização baseada em IAM para cada método ao qual você deseja fornecer acesso na sua REST API. Com a autorização baseada em IAM, o Snowflake pode usar a função IAM que você configurou para fazer chamadas para a API.

1. No console do Amazon API Gateway, selecione sua REST API.

2. Para cada método:

   1. Em Resources, selecione um método na lista.

   2. Em Method request settings, selecione Edit.

   3. Para Authorization, selecione AWS IAM.

   4. Selecione Save.

3. Para aplicar as alterações de autorização, selecione Deploy API. Para obter mais informações, consulte Implantando uma REST API a partir do console do API Gateway.

Obter o URL do ponto de extremidade¶

Obtenha seu URL do ponto de extremidade da REST API (ou URL de invocação). Sua API deve ser implantada em um estágio antes de você obter o URL do ponto de extremidade.

1. No console do Amazon API Gateway, selecione sua REST API.

2. No painel de navegação esquerdo, selecione Stages.

3. Em Stage details, copie o Invoke URL.

Você especifica o URL do ponto de extremidade ao criar uma integração de catálogo.

Criar uma integração de catálogo para SigV4¶

Depois de ter uma REST API no Amazon API Gateway e ter concluído as etapas iniciais para controlar o acesso à sua API usando permissões de IAM, você pode criar uma integração de catálogo no Snowflake.

Para exibir a sintaxe do comando e as descrições dos parâmetros, consulte CREATE CATALOG INTEGRATION (Apache Iceberg™ REST).

REST API pública

Para criar uma integração de catálogo para uma REST API pública, especifique ICEBERG_REST como CATALOG_SOURCE e use a autenticação SIGV4.

Inclua detalhes como URL do ponto de extremidade da API e ARN da função IAM.

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 privada

Para criar uma integração de catálogo para uma REST API privada, você deve definir o parâmetro CATALOG_API_TYPE como 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;

Configurar a relação de confiança no IAM¶

Recupere informações sobre o usuário AWS IAM que foi criado para a sua conta Snowflake durante a criação da integração de catálogo e configure a relação de confiança para sua função IAM.

1. No Snowflake, chame o comando DESCRIBE CATALOG INTEGRATION:

   DESCRIBE CATALOG INTEGRATION my_rest_catalog_integration;
   

   Copy

   Registre os seguintes valores:

   Valor	Descrição
   API_AWS_IAM_USER_ARN	O usuário AWS IAM criado para sua conta Snowflake, por exemplo, arn:aws:iam::123456789001:user/abc1-b-self1234. O Snowflake fornece um único usuário IAM para toda a sua conta Snowflake.
   API_AWS_EXTERNAL_ID	O ID externo necessário para estabelecer uma relação de confiança. Se você não especificou um ID externo (SIGV4_EXTERNAL_ID) ao criar a integração de catálogo, o Snowflake gera um ID para ser usado. Registre o valor para que você possa atualizar sua política de confiança da função IAM com o ID externo gerado.

2. No Console de gerenciamento da AWS, procure e selecione IAM.

3. Selecione Roles no painel de navegação à esquerda.

4. Selecione a função IAM que você criou para sua integração de catálogo.

5. Selecione a guia Trust relationships.

6. Selecione Edit trust policy.

7. Modifique o documento da política com os valores que você registrou.

   {
     "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. Selecione Update policy para salvar suas alterações.