Préparation du chargement des données à l’aide de l’API REST Snowpipe

Ce chapitre décrit comment démarrer avec Snowpipe lorsque vous appelez l’API REST, y compris des instructions pour installer le SDK client requis, créer une zone de préparation (si nécessaire) et un canal, et la configuration de sécurité unique pour chaque utilisateur Snowpipe.

Dans ce chapitre :

Note

Les instructions de cette section supposent que vous disposez déjà d’une table cible dans votre base de données Snowflake où vos données seront chargées.

Exigence du client (SDK Java ou Python)

Le service Snowpipe nécessite soit le SDK Java soit le SDK Python. Ces SDKs sont fournis par Snowflake pour votre commodité.

Important

Les binaires sont fournis en tant que logiciels clients selon les termes de votre contrat de service-cadre (MSA) avec Snowflake.

Installation du SDK Java

  1. Téléchargez le programme d’installation du SDK Java à partir du Maven Central Repository :

    http://search.maven.org/ (ou https://repo1.maven.org/maven2/net/snowflake/snowflake-ingest-sdk)

  2. Intégrez le fichier JAR dans un projet existant.

Note

Les notes du développeur sont hébergées avec le code source sur GitHub.

Installation du SDK Python

Notez que le SDK Python requiert Python 3.6 ou supérieur.

Pour installer le SDK, exécutez la commande suivante :

pip install snowflake-ingest

Vous pouvez également télécharger le fichier de la roue à partir de PyPI et l’intégrer dans un projet existant.

Note

Les notes du développeur sont hébergées avec le code source sur GitHub.

Étape 1 : Créer une zone de préparation (si nécessaire)

Snowpipe prend en charge le chargement à partir des types de zones de préparation suivants :

  • Zones de préparation internes (Snowflake) ou externes (Amazon S3, Google Cloud Storage ou Microsoft Azure) nommées

  • Zones de préparation de la table

Créez une zone de préparation nommée en utilisant la commande CREATE STAGE, ou vous pouvez choisir d’utiliser une zone de préparation existante. Vous préparerez vos fichiers temporairement avant que Snowpipe les charge dans votre table cible.

Étape 2 : Créer un canal

Crée un canal dans le système pour définir l’instruction COPYINTO <table> utilisée par Snowpipe pour charger les données d’une file d’attente d’acquisition dans des tables. Pour plus d’informations, voir CREATE PIPE.

Note

La création d’un canal nécessite le privilège de contrôle d’accès CREATE PIPE, ainsi que le privilège USAGE sur la base de données et la zone de préparation.

Par exemple, créez un canal dans le schéma mydb.myschema qui charge toutes les données des fichiers de la zone de préparation mystage dans la table mytable :

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

Étape 3 : Configurer la sécurité (par utilisateur)

Pour chaque utilisateur qui exécutera des chargements de données continus à l’aide de Snowpipe, générez une paire de clés publiques-privées pour passer des appels vers les points de terminaison REST de Snowpipe. En outre, accordez suffisamment de privilèges aux objets pour la charge de données (c’est-à-dire la base de données, le schéma et la table cibles), à l’objet préparé et au canal.

Si vous prévoyez de limiter les charges de données Snowpipe à un seul utilisateur, vous n’avez besoin de configurer l’authentification par paire de clés qu’une seule fois pour cet utilisateur. Après cela, vous n’avez plus qu’à accorder des privilèges de contrôle d’accès sur les objets de base de données utilisés pour chaque chargement de données.

Note

Pour suivre le principe général du moindre privilège, nous recommandons de créer un utilisateur et un rôle séparés à utiliser pour l’intégration de fichiers à l’aide d’un canal. L’utilisateur doit être créé avec ce rôle comme rôle par défaut.

Utilisation de l’authentification par paires de clés et rotation des clés

Snowflake prend en charge l’utilisation de l’authentification par paire de clés et la rotation de la paire de clés.

L’authentification par paire de clés est une option d’authentification pour les clients Snowflake pris en charge.

La rotation des paires de clés offre une sécurité renforcée.

Pour configurer ces fonctionnalités, voir Authentification par paires de clés et rotation des paires de clés.

Octroi des privilèges d’accès

L’utilisation de Snowpipe nécessite un rôle avec les autorisations suivantes :

Objet

Privilège

Remarques

Canal nommé

OWNERSHIP

Zone de préparation nommée

USAGE (zones de préparation externes), READ (zones de préparation internes)

Format de fichier nommé

USAGE

Facultatif ; nécessaire uniquement si au choix la zone de préparation (voir Étape 1 : Créer une zone de préparation (si nécessaire)) ou le canal (voir Étape 2 : Créer un canal) fait référence à un format de fichier nommé.

Base de données cible

USAGE

Schéma cible

USAGE

Table cible

INSERT , SELECT

Utilisez la commande GRANT <privileges> … TO ROLE pour accorder ces privilèges au rôle.

Note

Seuls les administrateurs de sécurité (c.-à-d. les utilisateurs dotés du rôle SECURITYADMIN) ou un rôle supérieur, ou un autre rôle doté du privilège CREATE ROLE sur le compte et du privilège global MANAGE GRANTS, peuvent créer des rôles et octroyer des privilèges.

Par exemple, créez un rôle nommé snowpipe1 qui peut accéder à un ensemble d’objets de base de données mydb.myschema ainsi qu’à un canal nommé mypipe. Attribuez le rôle à un utilisateur.

 -- Create a role to contain the Snowpipe privileges
use role securityadmin;

create or replace role snowpipe1;

-- Grant the required privileges on the database objects
grant usage on database mydb to role snowpipe1;

grant usage on schema mydb.myschema to role snowpipe1;

grant insert, select on mydb.myschema.mytable to role snowpipe1;

grant usage, read on stage mydb.myschema.mystage to role snowpipe1;

-- Grant the OWNERSHIP privilege on the pipe object
grant ownership 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;

Étape 4 : mise en zones de préparation de fichiers de données

Copiez les fichiers de données vers la zone de préparation interne ou externe que vous avez créée pour le chargement des fichiers à l’aide de Snowpipe.

  • Copiez les fichiers dans une zone de préparation externe à l’aide des outils fournis par le service de stockage Cloud.

  • Copiez les fichiers dans une zone de préparation interne en utilisant la commande PUT.

    Note

    Si votre compte Snowflake est hébergé sur Amazon Web Services, nous vous recommandons de toujours utiliser la syntaxe PUT … OVERWRITE = TRUE.

    Amazon S3 assure la cohérence en lecture-après-écriture des nouveaux objets créés dans un compartiment. Cependant, si une requête HEAD ou GET est faite pour un objet avant sa création, alors S3 fournit une constance éventuelle pour l’objet. Cela signifie qu’une requête immédiate d’un nouvel objet après sa création pourrait renvoyer une exception file not found. Le réglage du paramètre OVERWRITE = TRUE permet d’éviter le lancement d’une demande HEAD avant la création de l’objet dans le compartiment S3.

    Pour plus d’informations sur le modèle de cohérence S3, voir la documentation S3.

Suivant : Apprendre comment appeler les points de terminaison REST publics pour charger les données et récupérer les rapports d’historique de chargement, dans la section Appeler des points de terminaison REST Snowpipe pour charger les données.