# Conector o Amazon Athena para o Snowflake O conector do Amazon Athena para o [Snowflake](https://www.snowflake.com/) permite que o Amazon Athena execute consultas SQL nos dados armazenados no seu banco de dados SQL Snowflake ou em instâncias do RDS usando JDBC. Esse conector pode ser registrado como um catálogo federado no Glue Data Catalog. Ele é compatível com controles de acesso a dados definidos no Lake Formation nos níveis de catálogo, banco de dados, tabela, coluna, linha e tag. Esse conector usa o Glue Connections para centralizar as propriedades de configuração no Glue. ## Pré-requisitos Implante o conector na sua Conta da AWS usando o console do Athena ou a operação da API `CreateDataCatalog`. Para obter mais informações, consulte [Criar uma conexão de fonte de dados](connect-to-a-data-source.md). ## Limitações + Não há suporte para operações de gravação de DDL. + Em uma configuração de multiplexador, o prefixo e o bucket de derramamento são compartilhados em todas as instâncias do banco de dados. + Quaisquer limites relevantes do Lambda. Para obter mais informações, consulte [Cotas do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html) no *Guia do desenvolvedor do AWS Lambda*. + Somente conexões legadas são compatíveis com a configuração do multiplexador. + No momento, as visualizações do Snowflake com uma única divisão são compatíveis. + No Snowflake, os nomes dos objetos diferenciam maiúsculas de minúsculas. O Athena aceita maiúsculas e minúsculas nas consultas DDL e DML, mas, por padrão, converte os nomes dos objetos para [minúsculas](https://docs.aws.amazon.com/athena/latest/ug/tables-databases-columns-names.html#table-names-and-table-column-names-in-ate-must-be-lowercase) ao executar a consulta. O conector do Snowflake aceita somente letras minúsculas quando o Catálogo do Glue/Lake Formation é usado. Quando o Catálogo do Athena é usado, os clientes podem controlar o comportamento de diferenciação de maiúsculas e minúsculas usando a variável de ambiente `casing_mode` do Lambda cujos valores possíveis estão listados na seção [Parâmetros](#connectors-snowflake-parameters) (por exemplo, `key=casing_mode, value = CASE_INSENSITIVE_SEARCH`). ## Termos Os termos a seguir estão relacionados ao conector Snowflake. + **Instância do banco de dados**: qualquer instância de um banco de dados implantado on-premises, no Amazon EC2 ou no Amazon RDS. + **Manipulador**: um manipulador Lambda que acessa sua instância de banco de dados. Um manipulador pode ser para metadados ou para registros de dados. + **Manipulador de metadados**: um manipulador Lambda que recupera metadados da sua instância de banco de dados. + **Manipulador de registros**: um manipulador Lambda que recupera registros de dados da sua instância de banco de dados. + **Manipulador composto**: um manipulador Lambda que recupera tanto metadados quanto registros de dados da sua instância de banco de dados. + **Propriedade ou parâmetro**: uma propriedade do banco de dados usada pelos manipuladores para extrair informações do banco de dados. Você configura essas propriedades como variáveis de ambiente do Lambda. + **String de conexão**: uma string de texto usada para estabelecer uma conexão com uma instância de banco de dados. + **Catálogo**: um catálogo não AWS Glue registrado no Athena que é um prefixo obrigatório para a propriedade `connection_string`. + **Manipulador de multiplexação**: um manipulador Lambda que pode aceitar e usar várias conexões de banco de dados. ## Parâmetros Use os parâmetros nesta seção para configurar o conector do Snowflake. ### Conexões do Glue (recomendação) Recomendamos que você configure um conector do Snowflake usando um objeto de conexão do Glue. Para fazer isso, defina a variável de ambiente `glue_connection` da função do Lambda para o conector do Snowflake com o nome da conexão do Glue que deseja usar. **Propriedades das conexões do Glue** Use o comando apresentado a seguir para obter o esquema de um objeto de conexão do Glue. Esse esquema contém todos os parâmetros que você pode usar para controlar a conexão. ``` aws glue describe-connection-type --connection-type SNOWFLAKE ``` **Propriedades do ambiente do Lambda** + **glue\$1connection**: especifica o nome da conexão do Glue associada ao conector federado. + **casing\$1mode** (Opcional): especifica como lidar com maiúsculas e minúsculas para nomes de esquemas e tabelas. O parâmetro `casing_mode` usa os seguintes valores para especificar o comportamento do mapeamento de maiúsculas e minúsculas: + **NONE**: mantém a diferenciação de maiúsculas e minúsculas nos nomes de esquema e tabela (executa a consulta sem modificações no Snowflake). Esse é o valor padrão quando **casing\$1mode** não é especificado. + **UPPER**: converte para maiúsculas todos os nomes de esquema e tabela fornecidos na consulta antes de executá-la no Snowflake. + **LOWER**: converte para minúsculas todos os nomes de esquema e tabela fornecidos na consulta antes de executá-la no Snowflake. + **CASE\$1INSENSITIVE\$1SEARCH**: faz pesquisas sem diferenciar maiúsculas de minúsculas em nomes de esquemas e tabelas no Snowflake. Por exemplo, você pode usar esse modo quando você tem uma consulta como `SELECT * FROM EMPLOYEE` e o Snowflake contém uma tabela chamada `Employee`. No entanto, na presença de duplicidade de nomes, como ter uma tabela chamada `EMPLOYEE` e outra chamada `Employee` no Snowflake, a consulta falhará. **nota** O conector do Snowflake criado usando conexões do Glue não é compatível com o uso de um manipulador de multiplexação. O conector do Snowflake criado usando conexões do Glue é compatível apenas com o `ConnectionSchemaVersion` 2. **Armazenar credenciais** Todos os conectores que usam conexões do Glue devem usar o AWS Secrets Manager para armazenar credenciais. Para obter mais informações, consulte [Autenticar com o Snowflake](connectors-snowflake-authentication.md). ### Conexões legadas **nota** Os conectores de fonte de dados do Athena criados a partir de 3 de dezembro de 2024 usam conexões do AWS Glue. Os nomes dos parâmetros e suas definições listados abaixo referem-se a conectores de fonte de dados do Athena criados sem uma conexão do Glue associada. Os parâmetros apresentados abaixo devem ser usados somente quando você [implantar manualmente](connect-data-source-serverless-app-repo.md) uma versão anterior de um conector de fonte de dados do Athena ou quando a propriedade de ambiente `glue_connection` não for especificada. **Propriedades do ambiente do Lambda** + **default**: uma string de conexão JDBC a ser usada para conexão com a instância do banco de dados Snowflake. Por exemplo, ., `snowflake://${jdbc_connection_string}` + **catalog\$1connection\$1string**: usada pelo manipulador de multiplexação (não compatível com o uso de uma conexão do Glue). Uma string de conexão de instância de banco de dados. Prefixe a variável de ambiente com o nome do catálogo usado no Athena. Por exemplo, se o catálogo registrado no Athena for mysnowflakecatalog, o nome da variável de ambiente será mysnowflakecatalog\$1connection\$1string. + **casing\$1mode** (Opcional): especifica como lidar com maiúsculas e minúsculas para nomes de esquemas e tabelas. O parâmetro `casing_mode` usa os seguintes valores para especificar o comportamento do mapeamento de maiúsculas e minúsculas: + **NONE**: mantém a diferenciação de maiúsculas e minúsculas nos nomes de esquema e tabela (executa a consulta sem modificações no Snowflake). Esse é o valor padrão quando **casing\$1mode** não é especificado. + **UPPER**: converte para maiúsculas todos os nomes de esquema e tabela fornecidos na consulta antes de executá-la no Snowflake. + **LOWER**: converte para minúsculas todos os nomes de esquema e tabela fornecidos na consulta antes de executá-la no Snowflake. + **CASE\$1INSENSITIVE\$1SEARCH**: faz pesquisas sem diferenciar maiúsculas de minúsculas em nomes de esquemas e tabelas no Snowflake. Por exemplo, você pode usar esse modo quando você tem uma consulta como `SELECT * FROM EMPLOYEE` e o Snowflake contém uma tabela chamada `Employee`. No entanto, na presença de duplicidade de nomes, como ter uma tabela chamada `EMPLOYEE` e outra chamada `Employee` no Snowflake, a consulta falhará. + **spill\$1bucket**: especifica o bucket do Amazon S3 para dados que excedem os limites da função do Lambda. + **spill\$1prefix**: (opcional) assume como padrão uma subpasta no `spill_bucket` especificado chamado `athena-federation-spill`. Recomendamos que você configure um [ciclo de vida de armazenamento](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) do Amazon S3 neste local para excluir derramamentos anteriores a um número predeterminado de dias ou horas. + **spill\$1put\$1request\$1headers**: (opcional) um mapa codificado em JSON de cabeçalhos e valores de solicitações para a solicitação `putObject` do Amazon S3 usada para o derramamento (por exemplo, `{"x-amz-server-side-encryption" : "AES256"}`). Para outros cabeçalhos possíveis, consulte [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) na *Referência da API do Amazon Simple Storage Service*. + **kms\$1key\$1id**: (opcional) por padrão, todos os dados transmitidos para o Amazon S3 são criptografados usando o modo de criptografia autenticado AES-GCM e uma chave gerada aleatoriamente. Para que sua função do Lambda use chaves de criptografia mais fortes geradas pelo KMS, como `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`, é possível especificar um ID de chave do KMS. + **disable\$1spill\$1encryption**: (opcional) quando definido como `True`, desativa a criptografia do derramamento. É padronizado como `False`, para que os dados transmitidos para o S3 sejam criptografados usando o AES-GCM — usando uma chave gerada aleatoriamente ou o KMS para gerar chaves. Desativar a criptografia do derramamento pode melhorar a performance, especialmente se o local do derramamento usar [criptografia no lado do servidor](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html). #### String de conexão Use uma string de conexão JDBC no seguinte formato para se conectar a uma instância de banco de dados. ``` snowflake://${jdbc_connection_string} ``` #### Uso de um manipulador de multiplexação É possível usar um multiplexador para se conectar a várias instâncias de banco de dados com uma única função do Lambda. As solicitações são encaminhadas por nome do catálogo. Use as seguintes classes no Lambda. **** | Manipulador | Classe | | --- | --- | | Manipulador composto | SnowflakeMuxCompositeHandler | | Manipulador de metadados | SnowflakeMuxMetadataHandler | | Manipulador de registros | SnowflakeMuxRecordHandler | ##### Parâmetros do manipulador de multiplexação **** | Parameter | Descrição | | --- | --- | | \$1catalog\$1connection\$1string | Obrigatório. Uma string de conexão de instância de banco de dados. Prefixe a variável de ambiente com o nome do catálogo usado no Athena. Por exemplo, se o catálogo registrado no Athena for mysnowflakecatalog, então o nome da variável de ambiente será mysnowflakecatalog\$1connection\$1string. | | default | Obrigatório. A string de conexão padrão. Essa string é usada quando o catálogo for lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1. | As propriedades de exemplo a seguir são para uma função do Lambda MUX do Snowflake que ofereça suporte a duas instâncias de banco de dados: `snowflake1` (o padrão) e `snowflake2`. **** | Propriedade | Valor | | --- | --- | | default | snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1&\$1\$1Test/RDS/Snowflake1\$1 | | snowflake\$1catalog1\$1connection\$1string | snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1\$1\$1Test/RDS/Snowflake1\$1 | | snowflake\$1catalog2\$1connection\$1string | snowflake://jdbc:snowflake://snowflake2.host:port/?warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2 | ##### Fornecimento de credenciais Para fornecer um nome de usuário e uma senha para seu banco de dados na string de conexão JDBC, é possível usar as propriedades da string de conexão ou o AWS Secrets Manager. + **String de conexão**: um nome de usuário e uma senha podem ser especificados como propriedades na string de conexão do JDBC. **Importante** Como prática recomendada de segurança, não use credenciais com codificação rígida em suas variáveis de ambiente ou strings de conexão. Para obter informações sobre como mover seus segredos codificados para o AWS Secrets Manager, consulte [Mover segredos codificados para o AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) no *Guia do usuário do AWS Secrets Manager*. + **AWS Secrets Manager**: para usar o recurso Athena Federated Query com o AWS Secrets Manager, a VPC conectada à sua função do Lambda deve ter [acesso à Internet](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/) ou um [endpoint da VPC](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) para se conectar ao Secrets Manager. É possível colocar o nome de um segredo no AWS Secrets Manager na sua string de conexão JDBC. O conector substitui o nome secreto pelos valores de `username` e `password` do Secrets Manager. Para instâncias de banco de dados do Amazon RDS, esse suporte é totalmente integrado. Se você usa o Amazon RDS, é altamente recomendável usar o AWS Secrets Manager e rotação de credenciais. Se seu banco de dados não usar o Amazon RDS, armazene as credenciais em JSON no seguinte formato: ``` {"username": "${username}", "password": "${password}"} ``` **Exemplo de string de conexão com nome secreto** A string a seguir tem o nome secreto `${Test/RDS/Snowflake1}`. ``` snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1${Test/RDS/Snowflake1}&... ``` O conector usa o nome secreto para recuperar segredos e fornecer o nome de usuário e a senha, como no exemplo a seguir. ``` snowflake://jdbc:snowflake://snowflake1.host:port/warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2&... ``` Atualmente, o Snowflake reconhece as propriedades `user` e `password` do JDBC. Ele também aceita o nome do usuário e a senha no formato *nome de usuário*`/`*senha* sem as chaves `user` ou `password`. #### Uso de um único manipulador de conexão É possível usar os seguintes metadados de conexão única e manipuladores de registros para se conectar a uma única instância do Snowflake. **** | Tipo de manipulador | Classe | | --- | --- | | Manipulador composto | SnowflakeCompositeHandler | | Manipulador de metadados | SnowflakeMetadataHandler | | Manipulador de registros | SnowflakeRecordHandler | ##### Parâmetros do manipulador de conexão única **** | Parameter | Descrição | | --- | --- | | default | Obrigatório. A string de conexão padrão. | Os manipuladores de conexão únicos oferecem suporte a uma instância de banco de dados e devem fornecer um parâmetro de string de conexão `default`. Todas as outras strings de conexão são ignoradas. O exemplo de propriedade a seguir é para uma única instância do Snowflake com suporte em uma função do Lambda. **** | Propriedade | Valor | | --- | --- | | default | snowflake://jdbc:snowflake://snowflake1.host:port/?secret=Test/RDS/Snowflake1 | #### Parâmetros de derramamento O SDK do Lambda pode derramar dados no Amazon S3. Todas as instâncias do banco de dados acessadas pela mesma função do Lambda derramam no mesmo local. **** | Parameter | Descrição | | --- | --- | | spill\$1bucket | Obrigatório. Nome do bucket de derramamento. | | spill\$1prefix | Obrigatório. Prefixo de chave do bucket de derramamento. | | spill\$1put\$1request\$1headers | (Opcional) Um mapa codificado em JSON de cabeçalhos e valores de solicitações para a solicitação putObject do Amazon S3 usada para o derramamento (por exemplo, \$1"x-amz-server-side-encryption" : "AES256"\$1). Para outros cabeçalhos possíveis, consulte [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) na Referência da API do Amazon Simple Storage Service. | ## Suporte ao tipo de dados A tabela a seguir mostra os correspondentes tipos de dados do JDBC e do Apache Arrow. **** | JDBC | Arrow | | --- | --- | | Booleano | Bit | | Inteiro | Tiny | | Short | Smallint | | Inteiro | Int | | Longo | Bigint | | flutuação | Float4 | | Duplo | Float8 | | Data | Data/Dia | | Timestamp | Date Milli | | String | Varchar | | Bytes | Varbinary | | BigDecimal | Decimal | | ARRAY | Lista | ## Conversões de tipos de dados Além das conversões de JDBC para Arrow, o conector realiza algumas outras conversões para tornar a fonte do Snowflake e os tipos de dados do Athena compatíveis. Essas conversões ajudam a garantir que as consultas sejam executadas com êxito. A tabela a seguir mostra essas conversões: **** | Tipo de dados de origem (Snowflake) | Tipo de dados convertidos (Athena) | | --- | --- | | TIMESTAMP | TIMESTAMPMILLI | | DATE | TIMESTAMPMILLI | | INTEGER | INT | | DECIMAL | BIGINT | | TIMESTAMP\$1NTZ | TIMESTAMPMILLI | Todos os outros tipos de dados sem suporte são convertidos em `VARCHAR`. ## Partições e divisões As partições são usadas para determinar como gerar divisões para o conector. O Athena constrói uma coluna sintética do tipo `varchar` que representa o esquema de particionamento da tabela para ajudar o conector a gerar divisões. O conector não modifica a definição real da tabela. Para criar essa coluna sintética e as partições, o Athena exige que uma chave primária seja definida. No entanto, como o Snowflake não impõe restrições de chave primária, você mesmo deve impor a exclusividade. Caso você não faça isso, o Athena vai ter como padrão uma divisão única. ## desempenho Para obter um desempenho ideal, use filtros nas consultas sempre que possível. Além disso, é altamente recomendável o particionamento nativo para recuperar grandes conjuntos de dados com distribuição uniforme de partições. A seleção de um subconjunto de colunas acelera o runtime da consulta e reduz os dados verificados de forma significativa. O conector Snowflake é resiliente ao controle de utilização devido à simultaneidade. O conector do Athena para o Snowflake executa a passagem direta de predicados para diminuir os dados examinados pela consulta. Cláusulas `LIMIT`, predicados simples e expressões complexas são passados diretamente ao conector para reduzir a quantidade de dados examinados e o runtime de execução da consulta. ### Cláusulas LIMIT Uma instrução `LIMIT N` reduz os dados examinados pela consulta. Com a passagem direta de `LIMIT N`, o conector só retorna `N` linhas para o Athena. ### Predicados Um predicado é uma expressão na cláusula `WHERE` de uma consulta SQL, que avalia para um valor booleano e filtra as linhas com base em várias condições. O conector do Athena para o Snowflake pode combinar essas expressões e passá-las diretamente ao Snowflake para melhorar a funcionalidade e reduzir a quantidade de dados examinados. Os seguintes operadores do conector do Athena para o Snowflake são compatíveis com a passagem direta de predicados: + **Booleanos:** E, OU, NÃO + **Igualdade: **EQUAL, NOT\$1EQUAL, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL, IS\$1DISTINCT\$1FROM, NULL\$1IF, IS\$1NULL + **Aritméticos:** ADICIONAR, SUBTRAIR, MULTIPLICAR, DIVIDIR, MÓDULO, NEGAR + **Outros:**LIKE\$1PATTERN, IN ### Exemplo de passagem direta combinada Para ter recursos aprimorados de consulta, combine os tipos de passagem direta, como no seguinte exemplo: ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') LIMIT 10; ``` # Autenticar com o Snowflake Você pode configurar o conector do Amazon Athena Snowflake para usar a autenticação por par de chaves ou o método de autenticação OAuth para se conectar ao data warehouse do Snowflake. Ambos os métodos fornecem acesso seguro ao Snowflake e eliminam a necessidade de armazenar senhas em cadeias de conexão. + **Autenticação por par de chaves**: esse método usa pares de chaves públicas ou privadas RSA para autenticar com o Snowflake. A chave privada assina digitalmente as solicitações de autenticação enquanto a chave pública correspondente é registrada no Snowflake para verificação. Esse método elimina o armazenamento de senhas. + **Autenticação OAuth**: esse método usa o token de autorização e o token de atualização para autenticar com o Snowflake. Ele oferece suporte à atualização automática de tokens, o que o torna adequado para aplicações de execução longa. Para obter mais informações, consulte [autenticação por par de chaves](https://docs.snowflake.com/en/user-guide/key-pair-auth) e [autenticação OAuth](https://docs.snowflake.com/en/user-guide/oauth-custom) no guia do usuário do Snowflake. ## Pré-requisitos Antes de começar, conclua os seguintes pré-requisitos: + Acesso à conta do Snowflake com privilégios administrativos. + Conta de usuário do Snowflake dedicada para o conector do Athena. + OpenSSL ou ferramentas equivalentes de geração de chaves para autenticação de pares de chaves. + Acesso ao AWS Secrets Manager para criar e gerenciar segredos. + Navegador da Web para concluir o fluxo do OAuth para a autenticação do OAuth. ## Configurar a autenticação por par de chaves Esse processo envolve gerar um par de chaves RSA, configurar sua conta do Snowflake com a chave pública e armazenar com segurança a chave privada no AWS Secrets Manager. As etapas a seguir guiarão você na criação das chaves criptográficas, na configuração das permissões necessárias do Snowflake e na configuração das credenciais da AWS para autenticação direta. 1. **Gerar pares de chaves RSA** Gere um par de chaves pública e privada usando o OpenSSL. + Para gerar uma versão não criptografada, use o comando a seguir em sua aplicação de linha de comando local. ``` openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt ``` + Para gerar uma versão criptografada, use o comando a seguir, que omite `-nocrypt`. ``` openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out rsa_key.p8 ``` + Para gerar uma chave pública com base em uma chave privada. ``` openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub # Set appropriate permissions (Unix/Linux) chmod 600 rsa_key.p8 chmod 644 rsa_key.pub ``` **nota** Não compartilhe sua chave privada. A chave privada só deve estar acessível à aplicação que precisa se autenticar com o Snowflake. 1. **Extrair conteúdo da chave pública sem delimitadores para o Snowflake** ``` # Extract public key content (remove BEGIN/END lines and newlines) cat rsa_key.pub | grep -v "BEGIN\|END" | tr -d '\n' ``` Salve essa saída, pois ela será necessária mais tarde na próxima etapa. 1. **Configurar um usuário do Snowflake** Siga estas etapas para configurar um usuário do Snowflake. 1. Crie um usuário dedicado para o conector do Athena, caso ele ainda não exista. ``` -- Create user for Athena connector CREATE USER athena_connector_user; -- Grant necessary privileges GRANT USAGE ON WAREHOUSE your_warehouse TO ROLE athena_connector_role; GRANT USAGE ON DATABASE your_database TO ROLE athena_connector_role; GRANT SELECT ON ALL TABLES IN DATABASE your_database TO ROLE athena_connector_role; ``` 1. Conceda privilégios de autenticação. Para atribuir uma chave pública a um usuário, é necessário ter um dos seguintes perfis ou privilégios. + O privilégio `MODIFY PROGRAMMATIC AUTHENTICATION METHODS` ou `OWNERSHIP` no usuário. + O perfil `SECURITYADMIN` ou superior. Conceda os privilégios necessários para atribuir chaves públicas usando o comando a seguir. ``` GRANT MODIFY PROGRAMMATIC AUTHENTICATION METHODS ON USER athena_connector_user TO ROLE your_admin_role; ``` 1. Atribua a chave pública ao usuário do Snowflake usando o comando a seguir. ``` ALTER USER athena_connector_user SET RSA_PUBLIC_KEY='RSAkey'; ``` Verifique se a chave pública foi atribuída com sucesso ao usuário com o comando a seguir. ``` DESC USER athena_connector_user; ``` 1. **Armazenar a chave privada em AWS Secrets Manager** 1. Converta a chave privada para o formato exigido pelo conector. ``` # Read private key content cat rsa_key.p8 ``` 1. Crie um segredo no AWS Secrets Manager com a estrutura a seguir. ``` { "sfUser": "your_snowflake_user", "pem_private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----", "pem_private_key_passphrase": "passphrase_in_case_of_encrypted_private_key(optional)" } ``` **nota** O cabeçalho e o rodapé são opcionais. A chave privada deve ser separada por `\n`. ## Configurar autenticação do OAuth Esse método de autenticação permite acesso seguro e baseado em tokens ao Snowflake com recursos de atualização automática de credenciais. O processo de configuração envolve a criação de uma integração de segurança no Snowflake, a recuperação das credenciais do cliente OAuth, a conclusão do fluxo de autorização necessário para obter um código de acesso e o armazenamento das credenciais do OAuth no AWS Secrets Manager para uso do conector. 1. **Criar uma integração de segurança no Snowflake** Execute o seguinte comando SQL no Snowflake para criar uma integração de segurança OAuth do Snowflake. ``` CREATE SECURITY INTEGRATION my_snowflake_oauth_integration_a TYPE = OAUTH ENABLED = TRUE OAUTH_CLIENT = CUSTOM OAUTH_CLIENT_TYPE = 'CONFIDENTIAL' OAUTH_REDIRECT_URI = 'https://localhost:8080/oauth/callback' OAUTH_ISSUE_REFRESH_TOKENS = TRUE OAUTH_REFRESH_TOKEN_VALIDITY = 7776000; ``` **Parâmetros de configuração** + `TYPE = OAUTH`: especifica o tipo de autenticação OAuth. + `ENABLED = TRUE`: permite a integração de segurança. + `OAUTH_CLIENT = CUSTOM`: usa a configuração personalizada do cliente OAuth. + `OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'`: define o tipo de cliente para aplicações seguras. + `OAUTH_REDIRECT_URI`: o URL de retorno de chamada para o fluxo do OAuth. Para fins de teste, ele pode ser o localhost. + `OAUTH_ISSUE_REFRESH_TOKENS = TRUE`: habilita a geração de tokens de atualização. + `OAUTH_REFRESH_TOKEN_VALIDITY = 7776000`: define a validade do token de atualização (90 dias em segundos). 1. **Recuperar segredos do cliente OAuth** 1. Execute o comando SQL a seguir para obter as credenciais do cliente. ``` DESC SECURITY INTEGRATION 'MY_SNOWFLAKE_OAUTH_INTEGRATION_A'; ``` 1. Recupere os segredos do cliente OAuth. ``` SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('MY_SNOWFLAKE_OAUTH_INTEGRATION_A'); ``` **Exemplo de resposta** ``` { "OAUTH_CLIENT_SECRET_2": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "OAUTH_CLIENT_SECRET": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY, "OAUTH_CLIENT_ID": "AIDACKCEVSQ6C2EXAMPLE" } ``` **nota** Mantenha essas credenciais em segurança e não as compartilhe. Elas serão usadas para configurar o cliente OAuth. 1. **Autorizar o usuário e recuperar o código de autorização** 1. Abra o URL a seguir no seu navegador. ``` https://.snowflakecomputing.com/oauth/authorize?client_id=&response_type=code&redirect_uri=https://localhost:8080/oauth/callback ``` 1. Conclua o fluxo de autorização. 1. Faça login usando suas credenciais do Snowflake. 1. Conceda as permissões solicitadas. Você será redirecionado para o URI de retorno de chamada com um código de autorização. 1. Extraia o código de autorização copiando o parâmetro de código do URL de redirecionamento. ``` https://localhost:8080/oauth/callback?code= ``` **nota** O código de autorização é válido por tempo limitado e só pode ser usado uma vez. 1. **Armazenar credenciais do OAuth no AWS Secrets Manager** Crie um segredo no AWS Secrets Manager com a estrutura a seguir. ``` { "redirect_uri": "https://localhost:8080/oauth/callback", "client_secret": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY", "token_url": "https://.snowflakecomputing.com/oauth/token-request", "client_id": "AIDACKCEVSQ6C2EXAMPLE, "username": "your_snowflake_username", "auth_code": "authorizationcode" } ``` **Campos obrigatórios** + `redirect_uri`: URI de redirecionamento do OAuth que você obteve na Etapa 1. + `client_secret`: segredo do cliente OAuth que você obteve na Etapa 2. + `token_url`: Snowflake. O endpoint do token OAuth. + `client_id`: o ID do cliente OAuth da Etapa 2. + `username`: o nome de usuário do Snowflake para o conector. + `auth_code`: o código de autorização que você obteve na Etapa 3. Após criar um segredo, você obtém um ARN de segredo que pode ser usado na sua conexão do Glue ao [criar uma conexão de fonte de dados](connect-to-a-data-source.md). ## Consultas de passagem O conector Snowflake é compatível com [consultas de passagem](federated-query-passthrough.md). As consultas de passagem usam uma função de tabela para enviar sua consulta completa para execução na fonte de dados. Para usar consultas de passagem com o Snowflake, você pode empregar a seguinte sintaxe: ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` O exemplo de consulta a seguir envia uma consulta para uma fonte de dados no Snowflake. A consulta seleciona todas as colunas na tabela `customer`, limitando os resultados a 10. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer LIMIT 10' )) ``` ## Informações de licença Ao usar esse conector, você reconhece a inclusão de componentes de terceiros, cuja lista pode ser encontrada no arquivo [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/pom.xml) desse conector, e concorda com os termos das respectivas licenças de terceiros fornecidas no arquivo [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/LICENSE.txt) em GitHub.com. ## Recursos adicionais Para obter as informações mais recentes sobre a versão do driver JDBC, consulte o arquivo [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/pom.xml) do conector Snowflake em GitHub.com. Para obter mais informações sobre esse conector, visite [o site correspondente](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-snowflake) em GitHub.com.