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.5 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 paire de clés

Snowflake utilise l’authentification par paire de clés plutôt que l’authentification par nom d’utilisateur/mot de passe typique. Cette méthode d’authentification nécessite une paire de clés de 2048 bits (minimum) RSA. Générez la paire de clés publiques-privées PEM (Privacy Enhanced Mail) via OpenSSL. La clé publique est attribuée à l’utilisateur Snowflake qui utilisera le service Snowpipe.

Pour configurer la paire de clés publiques/privées :

  1. Depuis la ligne de commande d’une fenêtre de terminal, générez une clé privée.

    Vous pouvez générer une version chiffrée de la clé privée ou une version non chiffrée de la clé privée.

    Pour générer une version non chiffrée, utilisez la commande suivante :

    $ openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
    

    Pour générer une version chiffrée, utilisez la commande suivante (qui omet « -nocrypt ») :

    $ openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8
    

    Il est généralement plus sûr de générer une version chiffrée.

    Si vous utilisez la deuxième commande pour chiffrer la clé privée, OpenSSL vous invite à indiquer une phrase secrète utilisée pour chiffrer le fichier de clé privée. Nous vous recommandons d’utiliser une phrase de chiffrement forte pour protéger la clé privée. Enregistrez cette phrase secrète dans un emplacement sécurisé. Vous l’entrerez lorsque vous vous connecterez à Snowflake. Notez que la phrase de chiffrement n’est utilisée que pour protéger la clé privée et ne sera jamais envoyée à Snowflake.

    Exemple de clé privée PEM

    -----BEGIN ENCRYPTED PRIVATE KEY-----
    MIIE6TAbBgkqhkiG9w0BBQMwDgQILYPyCppzOwECAggABIIEyLiGSpeeGSe3xHP1
    wHLjfCYycUPennlX2bd8yX8xOxGSGfvB+99+PmSlex0FmY9ov1J8H1H9Y3lMWXbL
    ...
    -----END ENCRYPTED PRIVATE KEY-----
    
  2. Depuis la ligne de commande, générez la clé publique en faisant référence à la clé privée :

    En supposant que la clé privée soit contenue dans le fichier nommé « rsa_key.p8 », utilisez la commande suivante :

    $ openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
    

    Exemple de clé publique PEM

    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy+Fw2qv4Roud3l6tjPH4
    zxybHjmZ5rhtCz9jppCV8UTWvEXxa88IGRIHbJ/PwKW/mR8LXdfI7l/9vCMXX4mk
    ...
    -----END PUBLIC KEY-----
    
  3. Copiez les fichiers de clés publiques et privées dans un répertoire local en vue de leur stockage. Enregistrez le chemin d’accès aux fichiers. Notez que la clé privée est stockée au format PKCS#8 (Public Key Cryptography Standards) et est chiffrée à l’aide de la phrase de chiffrement que vous avez spécifiée à l’étape précédente ; toutefois, le fichier doit toujours être protégé contre tout accès non autorisé au moyen du mécanisme d’autorisation de fichier fourni par votre système d’exploitation. Il est de votre responsabilité de sécuriser le fichier lorsqu’il n’est pas utilisé.

  4. Attribuez la clé publique à l’utilisateur Snowflake en utilisant ALTER USER. Par exemple :

    ALTER USER jsmith SET RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
    

    Note

    • Seuls les administrateurs de sécurité (c’est-à-dire les utilisateurs ayant le rôle SECURITYADMIN) ou ayant un rôle supérieur peuvent modifier un utilisateur.

    • Excluez l’en-tête et le pied de page de la clé publique dans l’instruction SQL.

    Vérifiez l’empreinte de la clé publique de l’utilisateur en utilisant DESCRIBE USER :

    DESC USER jsmith;
    +-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------+
    | property                      | value                                               | default | description                                                                   |
    |-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------|
    | NAME                          | JSMITH                                              | null    | Name                                                                          |
    ...
    ...
    | RSA_PUBLIC_KEY_FP             | SHA256:nvnONUsfiuycCLMXIEWG4eTp4FjhVUZQUQbNpbSHXiA= | null    | Fingerprint of user's RSA public key.                                         |
    | RSA_PUBLIC_KEY_2_FP           | null                                                | null    | Fingerprint of user's second RSA public key.                                  |
    +-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------+
    

    Note

    La propriété RSA_PUBLIC_KEY_2_FP est décrite dans Rotation de clé (dans ce chapitre).

Rotation de clé

Snowflake accepte plusieurs clés actives pour permettre une rotation ininterrompue. Faites pivoter et remplacez vos clés publiques et privées en fonction du calendrier d’expiration que vous suivez en interne.

Actuellement, vous pouvez utiliser les paramètres RSA_PUBLIC_KEY et RSA_PUBLIC_KEY_2 pour ALTER USER afin d’associer jusqu’à 2 clés publiques à un seul utilisateur.

Pour faire tourner vos clés :

  1. Effectuez les étapes de la section Utilisation de l’authentification par paire de clés pour :

    • Générer un nouvel ensemble de clés privées et publiques.

    • Attribuer la clé publique à l’utilisateur. Définir la valeur de la clé publique sur RSA_PUBLIC_KEY ou RSA_PUBLIC_KEY_2 (la valeur de la clé qui n’est pas actuellement utilisée). Par exemple :

      alter user jsmith set rsa_public_key_2='JERUEHtcve...';
      
  2. Mettez à jour le code pour vous connecter à Snowflake. Spécifiez la nouvelle clé privée.

    Snowflake vérifie la bonne clé publique active pour l’authentification sur la base de la clé privée soumise avec vos informations de connexion.

  3. Retirez l’ancienne clé publique du profil utilisateur. Par exemple :

    alter user jsmith unset rsa_public_key;
    

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;

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.