Preparação para carregamento de dados usando a API REST Snowpipe¶

Este tópico descreve como começar a usar o Snowpipe ao chamar a API REST, incluindo instruções para instalar o SDK cliente necessário, criando um estágio (se necessário) e canal, e a configuração única de segurança para cada usuário do Snowpipe.

Neste tópico:

Nota

As instruções nesta seção assumem que você já tem uma tabela de destino em seu banco de dados Snowflake onde seus dados serão carregados.

Requisitos do cliente (SDK Java ou Python)¶

O serviço Snowpipe requer ou o SDK Java ou o SDK Python. Esses SDKs são fornecidos pela Snowflake para sua conveniência.

Importante

Os binários são fornecidos como software cliente de acordo com os termos de seu contrato de serviço principal (MSA) com o Snowflake.

Instalação do SDK Java¶

Baixe o instalador do SDK Java do Repositório Central Maven:

Sonatype (ou https://repo1.maven.org/maven2/net/snowflake/snowflake-ingest-sdk)
Integre o arquivo JAR em um projeto existente.

Nota

As notas do desenvolvedor são hospedadas com o código-fonte em GitHub.

Instalação do SDK Python¶

Note que o SDK Python requer o Python 3.6 ou superior.

Para instalar o SDK, execute o seguinte comando:

pip install snowflake-ingest

Copy

Alternativamente, baixe o arquivo wheel a partir de PyPI e integre-o a um projeto existente.

Nota

As notas do desenvolvedor são hospedadas com o código-fonte em GitHub.

Etapa 1: criar um estágio (se necessário)¶

O Snowpipe oferece suporte ao carregamento dos seguintes tipos de estágios:

Estágios internos (Snowflake) ou externos (Amazon S3, Google Cloud Storage ou Microsoft Azure)
Estágios da tabela

Crie um estágio nomeado usando o comando CREATE STAGE ou você pode optar por usar um estágio já existente. Você fará o preparo de seus arquivos temporariamente antes que o Snowpipe os carregue para sua tabela de destino.

Etapa 2: criar um canal¶

Crie um novo canal no sistema para definir a instrução COPY INTO <tabela> usada pelo Snowpipe para carregar dados em tabelas a partir de uma fila de ingestão. Para obter mais informações, consulte CREATE PIPE.

Nota

A criação de um canal requer o privilégio CREATE PIPE de controle de acesso, bem como o privilégio USAGE sobre o banco de dados, esquema e estágio.

Por exemplo, crie um canal no esquema mydb.myschema que carregue todos os dados dos arquivos preparados no estágio mystage para a tabela mytable:

create pipe mydb.myschema.mypipe if not exists as copy into mydb.myschema.mytable from @mydb.myschema.mystage;

Copy

Etapa 3: configurar a segurança (por usuário)¶

Para cada usuário que executará carregamentos contínuos de dados usando o Snowpipe, gere um par de chaves públicas-privadas para fazer chamadas para os pontos de extremidade REST do Snowpipe. Além disso, conceda privilégios suficientes sobre os objetos para o carregamento de dados (isto é, o banco de dados, o esquema e a tabela de destino), o objeto de preparação e o canal.

Se você planeja restringir os carregamentos de dados do Snowpipe a um único usuário, você só precisa configurar a autenticação do par de chaves para o usuário uma única vez. Depois disso, você só precisa conceder privilégios de controle de acesso nos objetos de banco de dados usados para cada carregamento de dados.

Nota

Para seguir o princípio geral do menor privilégio, recomendamos a criação de um usuário e função separados a serem usados para a ingestão de arquivos usando um canal. O usuário deve ser criado com esta função padrão.

Uso da autenticação de par de chaves e rodízio de chaves¶

Os pontos de extremidade REST do Snowpipe requerem a autenticação de par de chaves com Web Token JSON (JWT). JWTs são assinados usando um par de chaves públicas/privadas com criptografia RSA.

Como parte desse processo, você deve:

Gerar um par de chaves público-privado. A chave privada gerada deve estar em um arquivo (por exemplo, chamado rsa_key.p8).
Atribua a chave pública a seu usuário do Snowflake. Depois de atribuir a chave ao usuário, execute o comando DESCRIBE USER. Na saída, a propriedade RSA_PUBLIC_KEY_FP deve ser definida como a impressão digital da chave pública atribuída ao usuário.

Para obter instruções sobre como gerar o par de chaves e atribuir uma chave a um usuário, consulte Autenticação de pares de chaves e rotação de pares de chaves.

Para exemplos específicos de como criar uma impressão digital e gerar um token JWT, consulte as seções seguintes:

Python

Java

Node.js

Concessão de privilégios de acesso¶

Chamar os pontos de extremidade REST Snowpipe requer uma função com os seguintes privilégios mínimos:

Objeto	Privilégio	Notas
Canal nomeado	OPERATE (`insertFiles` ponto de extremidade), MONITOR (`insertReport`, `loadHistoryScan` pontos de extremidade)
Estágio nomeado	USAGE (estágio externo) , READ (estágio interno)
Formato de arquivo nomeado	USAGE	Opcional; só é necessário se ou o estágio (consulte Etapa 1: Criar um estágio (se necessário)) ou o canal (consulte Etapa 2: Criar um canal) fizer referência a um formato de arquivo nomeado.
Banco de dados de destino	USAGE
Esquema de destino	USAGE
Tabela de destino	INSERT , SELECT

Use o comando GRANT <privilégios> para conceder esses privilégios à função.

Nota

Somente administradores de segurança (ou seja, usuários com a função SECURITYADMIN) ou superior, ou outra função com o privilégio CREATE ROLE para a conta e o privilégio global MANAGE GRANTS, podem criar funções e conceder privilégios.

Por exemplo, crie uma função nomeada snowpipe1 que possa carregar dados por meio de um canal nomeado mypipe. O canal faz referência a um estágio externo:

 -- Create a role for the Snowpipe privileges.
use role securityadmin;

create or replace role snowpipe1;

-- Grant the USAGE privilege on the database and schema that contain the pipe object.
grant usage on database mydb to role snowpipe1;
grant usage on schema mydb.myschema to role snowpipe1;

-- Grant the INSERT and SELECT privileges on the target table.
grant insert, select on mydb.myschema.mytable to role snowpipe1;

-- Grant the USAGE privilege on the external stage.
grant usage on stage mydb.myschema.mystage to role snowpipe1;

-- Grant the OPERATE and MONITOR privileges on the pipe object.
grant operate, monitor on pipe mydb.myschema.mypipe to role snowpipe1;

-- Grant the role to a user
grant role snowpipe1 to user jsmith;

-- Set the role as the default role for the user
alter user jsmith set default_role = snowpipe1;

Copy

Etapa 4: preparar arquivo de dados¶

Copie os arquivos de dados para o estágio interno ou externo que você criou para carregar arquivos usando o Snowpipe.

Copie arquivos para um estágio externo utilizando as ferramentas fornecidas pelo serviço de armazenamento em nuvem.
Copie arquivos para um estágio interno usando o comando PUT.

Nota

Se sua conta Snowflake estiver hospedada na Amazon Web Services, recomendamos sempre usar a sintaxe PUT … OVERWRITE = TRUE.

O Amazon S3 oferece consistência de leitura após gravação para novos objetos criados em um bucket. Entretanto, se uma solicitação HEAD ou GET de um objeto for feita antes de sua criação, então o S3 fornece consistência eventual para o objeto. Isso significa que uma solicitação imediata de um novo objeto após sua criação pode retornar uma exceção file not found. A definição do parâmetro OVERWRITE = TRUE evita o início de uma solicitação HEAD antes da criação do objeto no bucket S3.

Para obter mais informações sobre o modelo de consistência do S3, consulte a documentação do S3.

Próximo: Aprenda como chamar os pontos de extremidade REST públicos para carregar dados e recuperar relatórios do histórico de carregamento, em Visão geral dos pontos de extremidade REST do Snowpipe para carregar dados.