Atualizar tabelas externas automaticamente para o Amazon S3¶

Etapa 1: configurar permissões de acesso para o bucket S3¶

Etapa 2: crie a função IAM no AWS¶

Para configurar permissões de acesso para Snowflake no AWS Management Console, faça o seguinte:

1. Na seção de navegação à esquerda do painel de gerenciamento de identidade e acesso (IAM), selecione Roles.

2. Selecione Create role.

3. Selecione AWS account como o tipo de entidade confiável.

4. Selecione Another AWS account

   

5. No campo Account ID, digite temporariamente sua própria ID de conta AWS. Mais tarde, você modificará a relação de confiança e concederá acesso ao Snowflake.

6. Selecione a opção Require external ID. Um ID externo é usado para conceder acesso aos seus recursos AWS (como buckets S3) a terceiros, como o Snowflake.

   Insira um ID de espaço reservado como 0000. Em uma etapa posterior, você modificará a relação de confiança para sua função IAM e especificará o ID externo de sua integração de armazenamento.

7. Selecione Next.

8. Selecione a política que você criou em Etapa 1: configure permissões de acesso ao bucket S3 (neste tópico).

9. Selecione Next.

   

10. Digite um nome e descrição para a função e selecione Create role.

    Agora você criou uma política IAM para um bucket, criou uma função IAM e anexou a política à função.

11. Na página de resumo da função, localize e registre o valor Role ARN. Na próxima etapa, você criará uma integração do Snowflake que faz referência a essa função.

Etapa 3: crie uma integração de armazenamento em nuvem no Snowflake¶

Crie uma integração de armazenamento usando o comando CREATE STORAGE INTEGRATION. Uma integração de armazenamento é um objeto Snowflake que armazena um usuário de gerenciamento de identidade e acesso gerado (IAM) para seu armazenamento em nuvem S3, juntamente com um conjunto opcional de locais de armazenamento permitidos ou bloqueados (ou seja, buckets). Os administradores do provedor de nuvem em sua organização concedem permissões para os locais de armazenamento ao usuário gerado. Esta opção permite que os usuários evitem fornecer credenciais ao criar estágios ou carregar dados.

Uma única integração de armazenamento pode oferecer suporte a vários estágios externos (ou seja, S3). A URL na definição do estágio deve estar alinhada com os buckets S3 (e caminhos opcionais) especificados para o parâmetro STORAGE_ALLOWED_LOCATIONS.

CREATE STORAGE INTEGRATION <integration_name>
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'S3'
  ENABLED = TRUE
  STORAGE_AWS_ROLE_ARN = '<iam_role>'
  STORAGE_ALLOWED_LOCATIONS = ('<protocol>://<bucket>/<path>/', '<protocol>://<bucket>/<path>/')
  [ STORAGE_BLOCKED_LOCATIONS = ('<protocol>://<bucket>/<path>/', '<protocol>://<bucket>/<path>/') ]

Onde:

• integration_name é o nome da nova integração.

• iam_role é o nome do recurso da Amazon (ARN) da função que você criou na Etapa 2: crie a função IAM no AWS (neste tópico).

• protocol é um dos seguintes:

  • s3 refere-se ao armazenamento S3 em regiões AWS públicas fora da China.

  • s3china refere-se ao armazenamento S3 em regiões AWS públicas na China.

  • s3gov refere-se ao armazenamento S3 em regiões governamentais.

• bucket é o nome de um bucket S3 que armazena seus arquivos de dados (por exemplo, mybucket). O parâmetro STORAGE_ALLOWED_LOCATIONS obrigatório e o parâmetro STORAGE_BLOCKED_LOCATIONS opcional restringem ou bloqueiam o acesso a estes buckets, respectivamente, quando os estágios que fazem referência a esta integração são criados ou modificados.

• path é um caminho opcional que pode ser usado para proporcionar um controle granular sobre objetos no bucket.

O exemplo a seguir cria uma integração que permite acesso a todos os buckets da conta, mas bloqueia o acesso às pastas sensitivedata definidas.

Os estágios externos adicionais que também utilizam esta integração podem fazer referência aos buckets e caminhos permitidos:

CREATE STORAGE INTEGRATION s3_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'S3'
  ENABLED = TRUE
  STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::001234567890:role/myrole'
  STORAGE_ALLOWED_LOCATIONS = ('*')
  STORAGE_BLOCKED_LOCATIONS = ('s3://mybucket1/mypath1/sensitivedata/', 's3://mybucket2/mypath2/sensitivedata/');

Etapa 4: recupere o usuário de AWS IAM para sua conta Snowflake¶

1. Para recuperar o ARN do usuário IAM que foi criado automaticamente para sua conta Snowflake, use o DESCRIBE INTEGRATION.

   DESC INTEGRATION <integration_name>;
   

   Copy

   Onde:

   • integration_name é o nome da integração que você criou em Etapa 3: Criar uma integração de armazenamento em nuvem no Snowflake (neste tópico).

   Por exemplo:

   DESC INTEGRATION s3_int;
   

   Copy

   +---------------------------+---------------+--------------------------------------------------------------------------------+------------------+
   | property                  | property_type | property_value                                                                 | property_default |
   +---------------------------+---------------+--------------------------------------------------------------------------------+------------------|
   | ENABLED                   | Boolean       | true                                                                           | false            |
   | STORAGE_ALLOWED_LOCATIONS | List          | s3://mybucket1/mypath1/,s3://mybucket2/mypath2/                                | []               |
   | STORAGE_BLOCKED_LOCATIONS | List          | s3://mybucket1/mypath1/sensitivedata/,s3://mybucket2/mypath2/sensitivedata/    | []               |
   | STORAGE_AWS_IAM_USER_ARN  | String        | arn:aws:iam::123456789001:user/abc1-b-self1234                                 |                  |
   | STORAGE_AWS_ROLE_ARN      | String        | arn:aws:iam::001234567890:role/myrole                                          |                  |
   | STORAGE_AWS_EXTERNAL_ID   | String        | MYACCOUNT_SFCRole=2_a123456/s0aBCDEfGHIJklmNoPq=                               |                  |
   +---------------------------+---------------+--------------------------------------------------------------------------------+------------------+
   

2. Registre os valores para as seguintes propriedades:

   Propriedade	Descrição
   STORAGE_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. Todas as integrações de armazenamento S3 na sua conta usam esse usuário IAM.
   STORAGE_AWS_EXTERNAL_ID	O ID externo que o Snowflake usa para estabelecer uma relação de confiança com AWS. Se você não especificou um ID externo (STORAGE_AWS_EXTERNAL_ID) ao criar a integração de armazenamento, o Snowflake gerará um ID para você usar.

   Você fornece esses valores na próxima seção.

Etapa 5: Conceda ao usuário IAM permissões do usuário para acessar objetos de bucket¶

As seguintes instruções passo a passo descrevem como configurar as permissões de acesso IAM ao Snowflake em seu Console de gerenciamento AWS para que você possa usar um bucket S3 para carregar e descarregar dados:

1. Entre no Console de Gerenciamento da AWS.

2. Selecione IAM.

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

4. Selecione a função que você criou na Etapa 2: crie a função IAM no AWS (neste tópico).

5. Selecione a guia Trust relationships.

6. Selecione Edit trust policy.

7. Modifique o documento da política com os valores de saída DESC STORAGE INTEGRATION que você registrou na Etapa 4: recupere o usuário AWS IAM para sua conta Snowflake (neste tópico):

   Documento de política da função IAM

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "AWS": "<snowflake_user_arn>"
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "<snowflake_external_id>"
           }
         }
       }
     ]
   }
   

   Copy

   Onde:

   • snowflake_user_arn é o valor STORAGE_AWS_IAM_USER_ARN que você registrou.

   • snowflake_external_id é o valor STORAGE_AWS_EXTERNAL_ID que você registrou.

     Neste exemplo, o valor snowflake_external_id é MYACCOUNT_SFCRole=2_a123456/s0aBCDEfGHIJklmNoPq=.

     Nota

     Por razões de segurança, se você criar uma nova integração de armazenamento (ou recriar uma integração de armazenamento existente usando a sintaxe CREATE OR REPLACE STORAGE INTEGRATION) sem especificar um ID externo, a nova integração tem um ID externo diferente e não poderá resolver a relação de confiança a menos que a política de confiança seja atualizada.

8. Selecione Update policy para salvar suas alterações.

(Opcional) Etapa 1: criar uma área¶

Crie uma área de preparação externa que faça referência ao seu bucket S3 usando o comando CREATE STAGE. O Snowflake lê seus arquivos de dados preparados nos metadados da tabela externa. Você também pode usar um estágio externo já existente.

O exemplo a seguir cria um estágio chamado mystage no esquema ativo para a sessão do usuário. O URL de armazenamento em nuvem inclui o caminho files. O estágio faz referência a uma integração de armazenamento chamada my_storage_int.

USE SCHEMA mydb.public;

CREATE STAGE mystage
  URL = 's3://mybucket/files'
  STORAGE_INTEGRATION = my_storage_int;

Copy

Etapa 2: criar uma tabela externa¶

Crie uma tabela externa usando o comando CREATE EXTERNAL TABLE. Por exemplo, crie uma tabela externa no esquema mydb.public que leia dados JSON de arquivos preparados.

A referência do estágio inclui um caminho de pasta chamado path1. A tabela externa anexa esse caminho à definição do estágio, ou seja, a tabela externa faz referência aos arquivos de dados em @mystage/files/path1.

O parâmetro AUTO_REFRESH é TRUE por padrão:

CREATE OR REPLACE EXTERNAL TABLE ext_table
 WITH LOCATION = @mystage/path1/
 FILE_FORMAT = (TYPE = JSON);

Copy

Etapa 3: configurar notificações de eventos¶

Configure notificações de eventos para seu bucket S3 para notificar o Snowflake quando dados novos ou atualizados estiverem disponíveis para leitura nos metadados da tabela externa. O recurso de atualização automática depende de filas SQS para entregar notificações de eventos do S3 para o Snowflake.

Para facilidade de uso, estas filas SQS são criadas e gerenciadas pelo Snowflake. A saída do comando SHOW EXTERNAL TABLES exibe o Nome de recurso da Amazon (ARN) de sua fila SQS.

1. Execute o comando SHOW EXTERNAL TABLES:

   SHOW EXTERNAL TABLES;
   

   Copy

2. Na coluna notification_channel, encontre o ARN da fila do SQS para a tabela externa e copie o ARN para um local de fácil acesso.

   Nota

   Seguindo as diretrizes do AWS, o Snowflake designa no máximo uma fila SQS por região do AWS S3. Essa fila SQS pode ser compartilhada entre vários buckets na mesma conta AWS. A fila SQS coordena notificações para todas as tabelas externas que leem arquivos de dados do mesmo bucket S3. Quando um arquivo de dados novo ou modificado é carregado no bucket, todas as definições da tabela externa que correspondem ao caminho do diretório de estágios leem os detalhes do arquivo em seus metadados.

3. Entre no Console de Gerenciamento da AWS.

4. Configure uma notificação de evento para o seu bucket S3 usando as instruções fornecidas na documentação do Amazon S3. Preencha os campos conforme mostrado na lista a seguir:

   • Name: nome da notificação do evento (por exemplo, Auto-ingest Snowflake).

   • Events: Selecione as opções ObjectCreate (All) e ObjectRemoved.

   • Send to: Selecione SQS Queue a partir da lista suspensa.

   • SQS: Selecione Add SQS queue ARN a partir da lista suspensa.

   • SQS queue ARN: Cole o nome da fila SQS da saída SHOW EXTERNALTABLES.

Após concluir essa etapa, a área de preparação externa com atualização automática é configurada.

Quando arquivos de dados novos ou atualizados são adicionados ao bucket S3, a notificação de evento informa ao Snowflake para verificá-los nos metadados da tabela externa.

Etapa 4: atualizar manualmente os metadados da tabela externa¶

Atualize manualmente os metadados de tabela externa uma vez usando ALTER EXTERNAL TABLE com o parâmetro REFRESH; por exemplo:

ALTER EXTERNAL TABLE ext_table REFRESH;

Copy

Esta etapa garante que os metadados sejam sincronizados com quaisquer alterações na lista de arquivos ocorridas após a Etapa 2. Depois disso, as notificações de eventos S3 acionam automaticamente a atualização dos metadados.

Etapa 5: configurar a segurança¶

Para cada função adicional que você usará para consultar a tabela externa, conceda privilégios de controle de acesso suficientes aos vários objetos (ou seja, bancos de dados, esquemas, áreas e tabelas) usando GRANT <privilégios> … TO ROLE:

Pré-requisito: Criar um tópico e assinatura do Amazon SNS¶

1. Crie um tópico do SNS em sua conta AWS para tratar todas as mensagens para o local do estágio do Snowflake em seu bucket S3.

2. Inscreva seus destinos de destino para as notificações de eventos do S3 (por exemplo, outras filas do SQS ou cargas de trabalho do AWS Lambda) nesse tópico. O SNS publica notificações de eventos para seu bucket para todos os assinantes do tópico.

Para instruções, consulte a documentação do SNS.

Etapa 1: Inscreva a fila SQS do Snowflake no tópico do SNS¶

1. Entre no Console de Gerenciamento da AWS.

2. No painel inicial, escolha Simple Notification Service (SNS).

3. Escolha Topics no painel de navegação à esquerda.

4. Localize o tópico para seu bucket S3. Observe o ARN do tópico.

5. Usando um cliente Snowflake, consulte a função SYSTEM$GET_AWS_SNS_IAM_POLICY do sistema com seu ARN do tópico SNS:

   select system$get_aws_sns_iam_policy('<sns_topic_arn>');
   

   Copy

   A função retorna uma política IAM que concede a uma fila SQS do Snowflake permissão para se inscrever no tópico SNS.

   Por exemplo:

   select system$get_aws_sns_iam_policy('arn:aws:sns:us-west-2:001234567890:s3_mybucket');
   
   +---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | SYSTEM$GET_AWS_SNS_IAM_POLICY('ARN:AWS:SNS:US-WEST-2:001234567890:S3_MYBUCKET')                                                                                                                                                                   |
   +---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | {"Version":"2012-10-17","Statement":[{"Sid":"1","Effect":"Allow","Principal":{"AWS":"arn:aws:iam::123456789001:user/vj4g-a-abcd1234"},"Action":["sns:Subscribe"],"Resource":["arn:aws:sns:us-west-2:001234567890:s3_mybucket"]}]}                 |
   +---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   

   Copy

6. Volte para o Console de gerenciamento AWS. Escolha Topics no painel de navegação à esquerda.

7. Selecione o tópico para seu bucket S3 e clique no botão Edit. A página Edit é aberta.

8. Clique em Access policy - Optional para expandir esta área da página.

9. Mesclar a adição da política IAM da função SYSTEM$GET_AWS_SNS_IAM_POLICY resulta no documento JSON.

   Por exemplo:

   Política IAM original (abreviada):

   {
     "Version":"2008-10-17",
     "Id":"__default_policy_ID",
     "Statement":[
        {
           "Sid":"__default_statement_ID",
           "Effect":"Allow",
           "Principal":{
              "AWS":"*"
           }
           ..
        }
      ]
    }
   

   Copy

   Política IAM mesclada:

   {
     "Version":"2008-10-17",
     "Id":"__default_policy_ID",
     "Statement":[
        {
           "Sid":"__default_statement_ID",
           "Effect":"Allow",
           "Principal":{
              "AWS":"*"
           }
           ..
        },
        {
           "Sid":"1",
           "Effect":"Allow",
           "Principal":{
             "AWS":"arn:aws:iam::123456789001:user/vj4g-a-abcd1234"
            },
            "Action":[
              "sns:Subscribe"
            ],
            "Resource":[
              "arn:aws:sns:us-west-2:001234567890:s3_mybucket"
            ]
        }
      ]
    }
   

   Copy

10. Adicione mais uma concessão de política para permitir que o S3 publique notificações de eventos para o bucket no tópico SNS.

    Por exemplo (usando o ARN do tópico SNS e o bucket S3 usado ao longo destas instruções):

    {
        "Sid":"s3-event-notifier",
        "Effect":"Allow",
        "Principal":{
           "Service":"s3.amazonaws.com"
        },
        "Action":"SNS:Publish",
        "Resource":"arn:aws:sns:us-west-2:001234567890:s3_mybucket",
        "Condition":{
           "ArnLike":{
              "aws:SourceArn":"arn:aws:s3:*:*:s3_mybucket"
           }
        }
     }
    

    Copy

    Política IAM mesclada:

    {
      "Version":"2008-10-17",
      "Id":"__default_policy_ID",
      "Statement":[
         {
            "Sid":"__default_statement_ID",
            "Effect":"Allow",
            "Principal":{
               "AWS":"*"
            }
            ..
         },
         {
            "Sid":"1",
            "Effect":"Allow",
            "Principal":{
              "AWS":"arn:aws:iam::123456789001:user/vj4g-a-abcd1234"
             },
             "Action":[
               "sns:Subscribe"
             ],
             "Resource":[
               "arn:aws:sns:us-west-2:001234567890:s3_mybucket"
             ]
         },
         {
            "Sid":"s3-event-notifier",
            "Effect":"Allow",
            "Principal":{
               "Service":"s3.amazonaws.com"
            },
            "Action":"SNS:Publish",
            "Resource":"arn:aws:sns:us-west-2:001234567890:s3_mybucket",
            "Condition":{
               "ArnLike":{
                  "aws:SourceArn":"arn:aws:s3:*:*:s3_mybucket"
               }
            }
          }
       ]
     }
    

    Copy

11. Clique em Save changes.

(Opcional) Etapa 2: Criar uma área¶

Crie uma área de preparação externa que faça referência ao seu bucket S3 usando o comando CREATE STAGE. O Snowflake lê seus arquivos de dados preparados nos metadados da tabela externa.

Você também pode usar um estágio externo já existente.

O exemplo a seguir cria um estágio chamado mystage no esquema ativo para a sessão do usuário. O URL de armazenamento em nuvem inclui o caminho files. O estágio faz referência a uma integração de armazenamento chamada my_storage_int:

USE SCHEMA mydb.public;

CREATE STAGE mystage
  URL = 's3://mybucket/files'
  STORAGE_INTEGRATION = my_storage_int;

Copy

Etapa 3: criar uma tabela externa¶

Crie uma tabela externa usando CREATE EXTERNAL TABLE. Identifique o tópico ARN do SNS em Pré-requisito: Criar um tópico e assinatura do Amazon SNS:

CREATE EXTERNAL TABLE <table_name>
 ..
 AWS_SNS_TOPIC = '<sns_topic_arn>';

Onde:

AWS_SNS_TOPIC = '<arn_tópico_sns>'

Especifica o ARN para o tópico SNS do seu bucket S3. A instrução CREATE EXTERNALTABLE inscreve a fila SQS do Snowflake no tópico SNS especificado.

Por exemplo, crie uma tabela externa no esquema mydb.public que leia dados JSON de arquivos preparados. A referência do estágio inclui um caminho de pasta chamado path1. A tabela externa anexa esse caminho à definição da área, ou seja, a tabela externa faz referência aos arquivos de dados em @mystage/files/path1. O parâmetro AUTO_REFRESH é TRUE por padrão:

CREATE EXTERNAL TABLE ext_table
 WITH LOCATION = @mystage/path1/
 FILE_FORMAT = (TYPE = JSON)
 AWS_SNS_TOPIC = 'arn:aws:sns:us-west-2:001234567890:s3_mybucket';

Para remover este parâmetro de uma tabela externa, você deve recriar a tabela externa usando a sintaxe CREATE OR REPLACE EXTERNAL TABLE.

Etapa 4: atualizar manualmente os metadados da tabela externa¶

Atualize manualmente os metadados de tabela externa uma vez usando ALTER EXTERNAL TABLE com o parâmetro REFRESH; por exemplo:

ALTER EXTERNAL TABLE ext_table REFRESH;

Copy

Esta etapa garante que os metadados sejam sincronizados com todas as alterações na lista de arquivos ocorridas após a Etapa 3. Depois disso, as notificações de eventos S3 acionam automaticamente a atualização dos metadados.

Etapa 5: configurar a segurança¶

Para cada função adicional que você usará para consultar a tabela externa, conceda privilégios de controle de acesso suficientes aos vários objetos (ou seja, bancos de dados, esquemas, áreas e tabelas) usando GRANT <privilégios> … TO ROLE: