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 :

    Sonatype (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
Copy

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;
Copy

É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

Les points de terminaison REST de Snowpipe exigent l’authentification par paire de clés avec un jeton Web JSON (JWT). Les JWTs sont signés à l’aide d’une paire de clés publiques/privées avec chiffrement RSA.

Dans le cadre de ce processus, vous devez :

  1. Générer une paire de clés publique-privée. La clé privée générée doit se trouver dans un fichier (par exemple, nommé rsa_key.p8).

  2. Attribuez la clé publique à votre utilisateur Snowflake. Après avoir attribué la clé à l’utilisateur, exécutez la commande DESCRIBE USER. Dans la sortie, la propriété RSA_PUBLIC_KEY_FP doit être définie comme l’empreinte de la clé publique attribuée à l’utilisateur.

Pour des instructions sur la façon de générer la paire de clés et d’attribuer une clé à un utilisateur, voir Authentification par paire de clés et rotation de paires de clés.

Pour des exemples de création d’une empreinte et de la génération d’un jeton JWT spécifiques à un langage, consultez les sections suivantes :

Octroi des privilèges d’accès

L’appel des points de terminaison REST Snowpipe nécessite un rôle doté des privilèges minimum suivants :

Objet

Privilège

Remarques

Canal nommé

OPERATE (point de terminaison insertFiles), MONITOR (points de terminaison insertReport, loadHistoryScan)

Zone de préparation nommée

USAGE (zone de préparation externe), READ (zone de préparation interne)

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 <privilèges> 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 charger des données via un canal nommé mypipe. Le canal fait référence à une zone de préparation externe :

 -- 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

É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 Présentation des points de terminaison REST Snowpipe pour charger les données.

Langage: Français