Configurar uma integração de catálogo para catálogos Apache Iceberg™ REST¶

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 ID para a VPC em que sua conta Snowflake está localizada. Copie o ID da VPC da saída da função.

   SELECT SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO();
   

   Copy

   Saída:

   {"snowflake-vpc-id":["vpc-c1c234a5"]}
   

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.

Etapa 1: configurar permissões de acesso para o catálogo de dados do AWS Glue¶

Crie uma política IAM para que o Snowflake acesse o AWS Glue Data Catalog. Anexe a política a uma função IAM, que você especifica ao criar uma integração de catálogo. Para obter instruções, consulte Criação de políticas de IAM e Modificação de uma política de permissões de função no Guia do usuário do gerenciamento de identidade e acesso do AWS.

No mínimo, o Snowflake requer as seguintes permissões no AWS Glue Data Catalog para acessar informações usando o catálogo Glue Iceberg REST.

• glue:GetConfig

• glue:GetDatabase

• glue:GetDatabases

• glue:GetTable

• glue:GetTables

O exemplo de política a seguir (no formato JSON) fornece as permissões necessárias para acessar todas as tabelas em um banco de dados especificado.

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

Etapa 2: criar uma integração de catálogo no Snowflake¶

Crie uma integração de catálogo para o ponto de extremidade AWS Glue Iceberg REST usando o comando CREATE CATALOG INTEGRATION (Apache Iceberg™ REST). Especifique a função IAM que você configurou. Para WAREHOUSE, use seu ID de conta AWS.

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;

Etapa 1: recuperação de um token de acesso¶

Use um comando curl para recuperar um token de acesso de seu catálogo. O exemplo a seguir solicita um token de acesso no 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

Onde:

• https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens é o ponto de extremidade para recuperar um token OAuth (getToken).

• scope é o mesmo valor que você especifica para o parâmetro OAUTH_ALLOWED_SCOPES ao criar uma integração de catálogo. Para vários escopos, use um espaço como separador.

• my_client_id é o mesmo ID de cliente que você especifica para o parâmetro OAUTH_CLIENT_ID ao criar uma integração de catálogo.

• my_client_secret é o mesmo segredo de cliente que você especifica para o parâmetro OAUTH_CLIENT_SECRET ao criar uma integração de catálogo.

Exemplo de valor de retorno:

{
  "access_token": "xxxxxxxxxxxxxxxx",
  "token_type": "bearer",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "expires_in": 3600
}

Etapa 2: verifique as permissões do token de acesso¶

Usando o token de acesso recuperado na etapa anterior, verifique se você tem permissão para acessar o servidor de catálogo.

É possível usar o comando curl para listar as definições de configuração de seu catálogo:

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

Onde:

• ?warehouse=warehouse especifica opcionalmente o nome do warehouse a ser solicitado de seu catálogo (se compatível). Para Snowflake Open Catalog, o nome do warehouse é o nome do catálogo.

• ACCESS_TOKEN é uma variável que contém o access_token recuperado na etapa anterior.

Exemplo de valor de retorno:

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

Etapa 3: carregamento de uma tabela do catálogo¶

Você também pode fazer uma solicitação GET para carregar uma tabela. O Snowflake usa a operação loadTable para carregar dados de tabela de seu catálogo 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

Onde:

• prefix especifica opcionalmente o prefixo obtido da resposta anterior de getConfig.

• namespace é o namespace da tabela que você deseja recuperar. Se o namespace estiver aninhado, use o separador %1F; por exemplo, parentNamespace%1FchildNamespace.

• table é o nome da tabela.

Etapa 1: verificação das permissões do token de acesso¶

Use um comando curl para verificar se você tem permissão para acessar o servidor de catálogo:

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

Onde:

• https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens é o ponto de extremidade para recuperar um token OAuth (getToken).

• ?warehouse=warehouse especifica opcionalmente o nome do warehouse a ser solicitado de seu catálogo (se compatível).

• BEARER_TOKEN é uma variável que contém o access_token recuperado na etapa anterior.

Exemplo de valor de retorno:

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

Etapa 2: carregamento de uma tabela do catálogo¶

Você também pode fazer uma solicitação GET para carregar uma tabela. O Snowflake usa a operação loadTable para carregar dados de tabela de seu catálogo 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

Onde:

• prefix especifica opcionalmente o prefixo obtido da resposta anterior de getConfig.

• namespace é o namespace da tabela que você deseja recuperar. Se o namespace estiver aninhado, use o separador %1F; por exemplo, parentNamespace%1FchildNamespace.

• table é o nome da tabela.

Etapa 1: adicione seu usuário à relação de confiança da função IAM¶

Ao criar uma integração de catálogo REST para SigV4, o Snowflake provisiona um usuário AWS IAM para sua conta Snowflake. Você adiciona esse usuário do Snowflake IAM à relação de confiança para uma função IAM com permissão para acessar os recursos do API Gateway.

Para testar a configuração, você pode assumir a função de usuário em sua conta AWS após adicionar o usuário AWS ao documento de política de confiança da função. Para recuperar o ARN de seu usuário IAM atual, use o comando sts get-caller-identity para a interface de linha de comando (CLI) AWS :

aws sts get-caller-identity

Exemplo de saída:

{
  "UserId": "ABCDEFG1XXXXXXXXXXX",
  "Account": "123456789XXX",
  "Arn": "arn:aws:iam::123456789XXX:user/managed/my_user"
}

O documento de política de confiança atualizado deve incluir o ARN do usuário Snowflake e o ARN do usuário da seguinte forma:

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

Para obter instruções completas, consulte Atualização de uma política de confiança de função na documentação AWS IAM.

Etapa 2: assuma sua função IAM para obter credenciais temporárias¶

Para obter credenciais de segurança temporárias para AWS, use o comando sts assume-role para AWS CLI.

aws sts assume-role \
  --role-arn <my_role_arn> \
  --role-session-name <session_name>

Onde:

• my_role_arn é o nome de recurso da Amazon (ARN) da função IAM que você configurou para o Snowflake.

• session_name é um identificador de cadeia de caracteres de sua escolha para a sessão de função assumida; por exemplo, my_rest_session.

Exemplo de saída:

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

Etapa 3: verifique se a função IAM tem as permissões corretas¶

Usando as credenciais temporárias que você recuperou na etapa anterior, verifique se a função IAM tem permissão para invocar as APIs do API Gateway.

É possível usar o comando curl para listar as definições de configuração de seu catálogo:

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"

Onde:

• 123xxxxxxx.execute-api.us-west-2.amazonaws.com é o nome de host do API Gateway.

• test_v2 é o nome do estágio em que seu API foi implementado.

• v1/config especifica a operação getConfig da definição OpenAPI do catálogo Iceberg.

• ?warehouse=warehouse especifica opcionalmente o nome do warehouse a ser solicitado de seu catálogo (se compatível).

• $AWS_ACCESS_KEY_ID é uma variável que contém o AccessKeyId que você recuperou usando o comando sts assume-role.

• $AWS_SECRET_ACCESS_KEY é uma variável que contém o SecretAccessKey que você recuperou usando o comando sts assume-role.

• aws:amz:us-west-2:execute-api é o nome de assinatura do protocolo SigV4. Para AWS Glue, use aws:amz:us-west-2:glue.

• $AWS_SESSION_TOKEN é uma variável que contém o SessionToken que você recuperou usando o comando sts assume-role.

Exemplo de valor de retorno:

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

Você também pode fazer uma solicitação GET para carregar uma tabela. O Snowflake usa a operação loadTable para carregar dados de tabela de seu catálogo 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"

Onde:

• prefix especifica opcionalmente o prefixo obtido da resposta anterior de getConfig.

• namespace é o namespace da tabela que você deseja recuperar. Se o namespace estiver aninhado, use o separador %1F; por exemplo, parentNamespace%1FchildNamespace.

• table é o nome da tabela.

API privada

Para uma API privada, é possível especificar o ponto de extremidade da VPC e o nome de host privado do Amazon API Gateway nos mesmos comandos curl.

Por exemplo:

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"

Onde:

• https://vpce-xxxxxxxxxxxxxxxxxxxxxxxxxx.execute-api.us-west-2.vpce.amazonaws.com/... é o nome de host de seu ponto de extremidade de VPC.

• abc1defgh2.execute-api.us-west-2.amazonaws.com é o nome de host de sua API privada no Amazon API Gateway.