Automatisation de Snowpipe pour Amazon S3

Cette rubrique fournit des instructions pour déclencher automatiquement les chargements de données Snowpipe à l’aide de notifications Amazon SQS (Simple Queue Service) pour un compartiment S3.

Note

Cette fonctionnalité est limitée aux comptes Snowflake hébergés sur Amazon Web Services.

Dans ce chapitre :

Trafic réseau

Remarque aux clients de Virtual Private Snowflake (VPS) et AWS PrivateLink :

L’automatisation de Snowpipe à l’aide des notifications SQS d’Amazon fonctionne bien. Cependant, bien que le stockage dans le cloud AWS dans un VPC (y compris VPS) puisse communiquer avec ses propres services de messagerie (Amazon SQS, Amazon Simple Notification Service), ce trafic circule entre les serveurs sur le réseau sécurisé d’Amazon en dehors du VPC ; par conséquent, ce trafic n’est pas protégé par le VPC.

Configuration de l’accès sécurisé au stockage Cloud

Note

Si vous avez déjà configuré un accès sécurisé au compartiment S3 qui stocke vos fichiers de données, vous pouvez ignorer cette section.

Cette section décrit comment configurer un objet d’intégration de stockage Snowflake pour déléguer la responsabilité de l’authentification pour le stockage dans le Cloud à une entité Gestion des identités et des accès Snowflake (IAM).

Note

Nous vous recommandons vivement cette option, qui vous évite de fournir des informations d’identification IAM lors de l’accès à un stockage dans le Cloud. Voir Configuration de l’accès sécurisé à Amazon S3 pour des options d’accès au stockage supplémentaires.

Cette section explique comment utiliser des intégrations de stockage pour permettre à Snowflake de lire et d’écrire des données dans un compartiment Amazon S3 référencé dans une zone de préparation externe (c’est-à-dire S3). Les intégrations sont des objets Snowflake de première classe nommés, qui évitent de transmettre des informations d’identification explicites de fournisseur Cloud, telles que des clés secrètes ou des jetons d’accès. Les objets d’intégration stockent un ID d’utilisateur de gestion des identités et des accès (IAM) AWS. Un administrateur de votre organisation accorde les autorisations utilisateur IAM de l’intégration dans le compte AWS.

Une intégration peut également répertorier des compartiments (et des chemins facultatifs) qui limitent les emplacements que les utilisateurs peuvent spécifier lors de la création de zones de préparation externes utilisant l’intégration.

Note

Pour terminer les instructions de cette section, des autorisations sont nécessaires dans AWS pour créer et gérer des stratégies et des rôles IAM. Si vous n’êtes pas un administrateur AWS, demandez à votre administrateur AWS d’effectuer ces tâches.

Le diagramme suivant illustre le flux d’intégration d’une zone de préparation S3 :

Amazon S3 Stage Integration Flow
  1. Une zone de préparation externe (c.-à-d S3) fait référence à un objet d’intégration de stockage dans sa définition.

  2. Snowflake associe automatiquement l’intégration de stockage à un utilisateur IAM S3 créé pour votre compte. Snowflake crée un seul utilisateur IAM référencé par toutes les intégrations de stockage S3 de votre compte Snowflake.

  3. Un administrateur AWS de votre organisation accorde des autorisations à l’utilisateur IAM pour accéder au compartiment référencé dans la définition de la zone de préparation. Notez que de nombreux objets de zones de préparation externes peuvent référencer différents compartiments et chemins et utiliser la même intégration de stockage pour l’authentification.

Lorsqu’un utilisateur charge ou décharge des données depuis ou vers une zone de préparation, Snowflake vérifie les autorisations accordées à l’utilisateur IAM sur le compartiment avant d’autoriser ou de refuser l’accès.

Dans cette section :

Étape 1 : Configuration des autorisations d’accès pour le compartiment S3

Exigences en matière de contrôle d’accès AWS

Snowflake requiert les permissions suivantes sur un compartiment S3 et un dossier pour accéder aux fichiers dans le dossier (et tout sous-dossier) :

  • s3:GetObject

  • s3:GetObjectVersion

  • s3:ListBucket

Comme bonne pratique, Snowflake recommande la création d’une politique IAM pour l’accès de Snowflake au compartiment S3. Vous pouvez alors joindre la politique au rôle, et utiliser les identifiants de sécurité générés par AWS pour que le rôle puisse accéder aux fichiers dans le compartiment.

Création d’une politique IAM

Les instructions étape par étape suivantes décrivent comment configurer les permissions d’accès pour Snowflake dans votre console de gestion AWS de sorte que vous puissiez utiliser un compartiment S3 pour charger et décharger les données :

  1. Connectez-vous à la console de gestion AWS.

  2. Dans le tableau de bord d’accueil, sélectionnez Identity & Access Management (IAM) :

    Identity & Access Management in AWS Management Console
  3. Cliquez sur Account settings dans le volet de navigation de gauche.

  4. Développez la liste Security Token Service Regions, recherchez la région AWS qui correspond à la région où se trouve votre compte et choisissez Activate si le statut est Inactive.

  5. Cliquez sur Policies dans le volet de navigation de gauche.

  6. Cliquez sur Create Policy :

    Create Policy button on Policies page
  7. Cliquez sur l’onglet JSON.

  8. Ajoutez le document de politique qui permettra à Snowflake d’accéder au compartiment et au dossier S3.

    La politique suivante (au format JSON) fournit à Snowflake les autorisations requises pour charger ou décharger des données à l’aide d’un seul chemin de dossier et de compartiment.

    Copiez et collez le texte dans l’éditeur de politiques :

    Note

    Assurez-vous de remplacer le compartiment et le préfixe par votre nom de compartiment actuel et le préfixe du chemin du dossier.

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                  "s3:GetObject",
                  "s3:GetObjectVersion",
                ],
                "Resource": "arn:aws:s3:::<bucket>/<prefix>/*"
            },
            {
                "Effect": "Allow",
                "Action": "s3:ListBucket",
                "Resource": "arn:aws:s3:::<bucket>",
                "Condition": {
                    "StringLike": {
                        "s3:prefix": [
                            "<prefix>/*"
                        ]
                    }
                }
            }
        ]
    }
    

    Important

    Définir la condition "s3:prefix": sur ["*"] accorde l’accès à tous les préfixes dans le compartiment spécifié. Si plus de 1 000 objets existent dans le compartiment, vous pourriez rencontrer l’erreur suivante : Access Denied (Status Code: 403; Error Code: AccessDenied).

    Pour éviter cette erreur, supprimez la condition de la politique IAM, par ex. :

    "Condition": {
          "StringLike": {
              "s3:prefix": [
                  "*"
              ]
          }
      }
    

    La politique accorde toujours l’accès aux fichiers du compartiment, mais S3 ne renvoie pas d’erreur si le compartiment contient plus de 1 000 objets.

    Notez que les politiques AWS prennent en charge une variété de cas d’utilisation de sécurité différents.

    La politique suivante fournit à Snowflake les permissions requises pour charger des données à partir d’un seul compartiment en lecture seule et chemin de dossier. La politique inclut les autorisations s3:GetObject, s3:GetObjectVersion et s3:ListBucket :

    Politique alternative : Chargement à partir d’un compartiment S3 en lecture seule

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                  "s3:GetObject",
                  "s3:GetObjectVersion"
                ],
                "Resource": "arn:aws:s3:::<bucket>/<prefix>/*"
            },
            {
                "Effect": "Allow",
                "Action": "s3:ListBucket",
                "Resource": "arn:aws:s3:::<bucket>",
                "Condition": {
                    "StringLike": {
                        "s3:prefix": [
                            "<prefix>/*"
                        ]
                    }
                }
            }
        ]
    }
    
  9. Cliquez sur Review policy.

  10. Entrez le nom de la stratégie (ex. : snowflake_access) et une description facultative. Cliquez sur Create policy.

    Create Policy button in Review Policy page

Étape 2 : Créer le rôle IAM dans AWS

Dans la console de gestion AWS, créez un rôle AWS IAM qui accorde des privilèges sur le compartiment S3 contenant vos fichiers de données.

  1. Connectez-vous à la console de gestion AWS.

  2. Dans le tableau de bord d’accueil, sélectionnez Identity & Access Management (IAM) :

    Identity & Access Management in AWS Management Console
  3. Cliquez sur Roles dans le volet de navigation de gauche.

  4. Cliquez sur le bouton Create role.

    Select Trusted Entity Page in AWS Management Console
  5. Sélectionnez Another AWS account comme type d’entité de confiance.

  6. Dans le champ Account ID, entrez votre propre ID de compte AWS temporaire. Plus tard, vous modifierez la relation de confiance et accorderez l’accès à Snowflake.

  7. Sélectionnez l’option Require external ID. Entrez un ID fictif tel que 0000. Plus tard, vous modifierez la relation de confiance et spécifierez l’ID externe pour votre zone de préparation Snowflake. Un ID externe est requis pour accorder l’accès à vos ressources AWS (c.-à-d. S3) à un tiers (p. ex Snowflake).

  8. Cliquez sur le bouton Next.

  9. Localisez la politique que vous avez créée lors de l” étape 1 : Configuration des autorisations d’accès au compartiment S3 (dans ce chapitre), puis sélectionnez cette stratégie.

  10. Cliquez sur le bouton Next.

    Review Page in AWS Management Console
  11. Entrez un nom et une description pour le rôle et cliquez sur le bouton Create role.

    Vous avez maintenant créé une stratégie IAM pour un compartiment, créé un rôle IAM et associé la stratégie au rôle.

  12. Enregistrez la valeur Role ARN située sur la page de résumé du rôle. Dans l’étape suivante, vous créerez une intégration Snowflake qui fait référence à ce rôle.

    IAM Role

Étape 3 : Création d’une intégration Cloud Storage dans Snowflake

Créez une intégration de stockage à l’aide de la commande CREATE STORAGE INTEGRATION. Une intégration de stockage est un objet Snowflake qui stocke un utilisateur généré pour la gestion d’identité et d’accès (IAM) pour votre stockage Cloud S3, ainsi qu’un ensemble facultatif d’emplacements de stockage autorisés ou bloqués (c.-à-d. des compartiments). Les administrateurs de fournisseur de Cloud de votre entreprise accordent des autorisations sur les emplacements de stockage à l’utilisateur généré. Cette option permet aux utilisateurs d’éviter de fournir des informations d’identification lors de la création de zones de préparation ou du chargement de données.

Une seule intégration de stockage peut prendre en charge plusieurs zones de préparation externes (c’est-à-dire S3). L’URL dans la définition de zone de préparation doit correspondre aux compartiments S3 (et aux chemins facultatifs) spécifiés pour le paramètre STORAGE_ALLOWED_LOCATIONS.

Note

Seuls les administrateurs de compte (utilisateurs dotés du rôle ACCOUNTADMIN) ou un rôle disposant du privilège global CREATE INTEGRATION peuvent exécuter cette commande SQL.

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

Où :

  • nom_intégration est le nom de la nouvelle intégration.

  • iam_rôle est le nom Amazon Resource Name (ARN) du rôle que vous avez créé à l’ étape 2 : Créer le rôle IAM dans AWS (dans ce chapitre).

  • compartiment est le nom d’un compartiment S3 qui stocke vos fichiers de données (par exemple, mybucket). Les paramètres STORAGE_ALLOWED_LOCATIONS requis et STORAGE_BLOCKED_LOCATIONS facultatif limitent ou bloquent l’accès à ces compartiments, respectivement, lors de la création ou de la modification de zones de préparation faisant référence à cette intégration.

  • chemin est un chemin facultatif qui peut être utilisé pour fournir un contrôle granulaire sur les objets du compartiment.

L’exemple suivant crée une intégration qui limite explicitement les zones de préparation externes utilisant l’intégration pour faire référence à l’un des deux compartiments et des chemins. Dans une étape ultérieure, nous allons créer une zone de préparation externe qui fait référence à l’un de ces compartiments et chemins.

Les zones de préparation externes supplémentaires qui utilisent également cette intégration peuvent faire référence aux compartiments et aux chemins autorisés :

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 = ('s3://mybucket1/mypath1/', 's3://mybucket2/mypath2/')
  STORAGE_BLOCKED_LOCATIONS = ('s3://mybucket1/mypath1/sensitivedata/', 's3://mybucket2/mypath2/sensitivedata/');

Étape 4 : Récupération de l’utilisateur AWS IAM de votre compte Snowflake

  1. Exécutez la commande DESCRIBE INTEGRATION pour récupérer l’ARN de l’utilisateur AWS IAM créé automatiquement pour votre compte Snowflake :

    DESC INTEGRATION <integration_name>;
    

    Où :

    Par exemple :

    DESC INTEGRATION s3_int;
    
    +---------------------------+---------------+--------------------------------------------------------------------------------+------------------+
    | 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. Notez les valeurs suivantes :

    Valeur

    Description

    STORAGE_AWS_IAM_USER_ARN

    L’utilisateur AWS IAM créé pour votre compte Snowflake, arn:aws:iam::123456789001:user/abc1-b-self1234 dans cet exemple. Nous mettons à disposition un seul utilisateur IAM pour l’intégralité de votre compte Snowflake. Toutes les intégrations de stockage S3 utilisent cet utilisateur IAM.

    STORAGE_AWS_EXTERNAL_ID

    L’ID externe nécessaire pour établir une relation de confiance.

    Vous fournirez ces valeurs dans la section suivante.

Étape 5 : Octroi des autorisations utilisateur à IAM pour accéder à des objets de compartiment

Les instructions étape par étape suivantes décrivent comment configurer les permissions d’accès IAM pour Snowflake dans votre console de gestion AWS de sorte que vous puissiez utiliser un compartiment S3 pour charger et décharger les données :

  1. Connectez-vous à la console de gestion AWS.

  2. Dans le tableau de bord d’accueil, sélectionnez Identity & Access Management (IAM) :

    Identity & Access Management in AWS Management Console
  3. Cliquez sur Roles dans le volet de navigation de gauche.

  4. Cliquez sur le rôle que vous avez créé à l”étape 2 : Créer le rôle IAM dans AWS (dans ce chapitre).

  5. Cliquez sur l’onglet Trust relationships.

  6. Cliquez sur le bouton Edit trust relationship.

  7. Modifiez le document de politique avec les valeurs de sortie DESC STORAGE INTEGRATION que vous avez enregistrées dans l” étape 4 : Récupération de l’utilisateur AWS IAM de votre compte Snowflake (dans ce chapitre) :

    Document de politique pour le rôle IAM

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

    Où :

    • snowflake_external_id est la valeur STORAGE_AWS_EXTERNAL_ID que vous avez enregistrée.

    • snowflake_user_arn est la valeur STORAGE_AWS_IAM_USER_ARN que vous avez enregistrée.

  8. Cliquez sur le bouton Update Trust Policy. Les modifications sont enregistrées.

Déterminer l’option correcte

Avant de poursuivre, déterminez si une notification d’événement S3 existe pour le chemin cible (ou le « préfixe » dans la terminologie AWS) dans votre compartiment S3 où se trouvent vos fichiers de données. Les règles d’AWS interdisent la création de notifications conflictuelles pour le même chemin.

Les options suivantes pour automatiser Snowpipe à l’aide d’Amazon SQS sont prises en charge :

  • Option 1. Nouvelle notification d’événement S3 : Créez une notification d’événement pour le chemin cible dans votre compartiment S3. La notification d’événement informe Snowpipe via une file d’attente SQS lorsque les fichiers sont prêts à être chargés.

    C’est l’option la plus courante.

    Important

    S’il existe une notification d’événement en conflit pour votre compartiment S3, utilisez l’option 2 à la place.

  • Option 2. Notification d’événement existante : Configurez Amazon Simple Notification Service (SNS) en tant que diffuseur pour partager les notifications d’un chemin donné avec plusieurs points de terminaison (ou « abonnés », par exemple files d’attente SQS ou charges de travail AWS Lambda), y compris la file d’attente SQS de Snowflake pour l’automatisation de Snowpipe. Une notification d’événement S3 publiée par SNS informe Snowpipe via une file d’attente SQS lorsque les fichiers sont prêts à être chargés.

Option 1 : Création d’une nouvelle notification d’événement S3 pour automatiser Snowpipe

Cette section décrit l’option la plus courante pour déclencher automatiquement les chargements de données Snowpipe à l’aide de notifications Amazon SQS (Simple Queue Service) pour un compartiment S3. Les étapes expliquent comment créer une notification d’événement pour le chemin cible (ou « préfixe » dans la terminologie AWS) dans votre compartiment S3 dans lequel vos fichiers de données sont stockés.

Important

S’il existe une notification d’événement en conflit pour votre compartiment S3, utilisez plutôt Option 2 : Configuration d’Amazon SNS pour automatiser Snowpipe à l’aide de notifications SQS (dans cette rubrique). Les règles AWS interdisent la création de notifications en conflit pour le même chemin cible.

Le diagramme suivant montre le déroulement du processus d’intégration automatique Snowpipe :

Snowpipe Auto-ingest Process Flow
  1. Les fichiers de données sont chargés dans une zone de préparation.

  2. Une notification d’événement S3 informe Snowpipe via une file d’attente SQS que les fichiers sont prêts à être chargés. Snowpipe copie les fichiers dans une file d’attente.

  3. Un entrepôt virtuel fourni par Snowflake charge les données des fichiers en file d’attente dans la table cible en fonction des paramètres définis dans le canal spécifié.

Note

Les instructions de cette rubrique supposent qu’une table cible existe déjà dans la base de données Snowflake où vos données seront chargées.

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

Créez une zone de préparation externe qui fait référence à votre compartiment S3 à l’aide de la commande CREATE STAGE. Snowpipe va chercher vos fichiers de données dans la zone de préparation et les mettre temporairement en file d’attente avant de les charger dans votre table cible. Vous pouvez aussi utiliser une zone de préparation externe.

Note

Pour configurer un accès sécurisé à l’emplacement de stockage Cloud, voir Configuration de l’accès sécurisé au stockage Cloud (dans cette rubrique).

L’exemple suivant crée une zone de préparation nommée mystage dans le schéma actif de la session utilisateur. L’URL de stockage Cloud inclut le chemin files. La zone de préparation fait référence à une intégration de stockage nommée myint :

USE SCHEMA snowpipe_db.public;

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

Étape 2 : créer un canal avec l’intégration automatique activée

Créez un canal à l’aide de la commande CREATE PIPE. Le canal définit l’instruction COPY INTO <table> utilisée par Snowpipe pour charger les données de la file d’attente d’acquisition dans la table cible.

L’exemple suivant crée un canal nommé mypipe dans le schéma actif de la session utilisateur. Le canal charge toutes les données des fichiers mis dans la zone de préparation mystage dans la table mytable :

create pipe snowpipe_db.public.mypipe auto_ingest=true as
  copy into snowpipe_db.public.mytable
  from @snowpipe_db.public.mystage
  file_format = (type = 'JSON');

Le paramètre AUTO_INGEST=true spécifie qu’il faut lire les notifications d’événements envoyées d’un compartiment S3 à une file d’attente SQS lorsque de nouvelles données sont prêtes à être chargées.

Important

Comparez la référence de la zone de préparation dans la définition de canal avec les canaux existants. Vérifiez que les chemins de répertoire du même compartiment S3 ne se chevauchent pas. Sinon, plusieurs canaux pourraient charger le même ensemble de fichiers de données plusieurs fois dans une ou plusieurs tables cibles. Cela peut se produire, par exemple, lorsque plusieurs zones de préparation font référence au même compartiment S3 avec différents niveaux de granularité, tels que s3://mybucket/path1 et s3://mybucket/path1/path2. Dans ce cas d’utilisation, si les fichiers sont stockés dans s3://mybucket/path1/path2, les canaux pour les deux zones de préparation chargeraient une copie des fichiers.

Cela diffère de la configuration manuelle de Snowpipe (avec l’intégration automatique désactivée), qui oblige les utilisateurs à soumettre un ensemble de fichiers nommé à une API REST pour mettre en file d’attente les fichiers à charger. Lorsque l’intégration automatique est activée, chaque canal reçoit une liste de fichiers générée à partir des notifications d’événement S3. Des précautions supplémentaires sont nécessaires pour éviter la duplication des données.

Note

Le clonage d’une base de données ou d’un schéma clone tous les objets, y compris les canaux qui font référence à des zones de préparation externes, dans la base de données ou le schéma source. Lorsqu’un fichier de données est créé à un emplacement de zone de stockage (par exemple, un compartiment S3), une copie de la notification est envoyée à chaque canal correspondant à l’emplacement de la zone de préparation. Cela entraîne le comportement suivant :

  • Si une table est pleinement qualifiée dans l’instruction COPY de la définition de canal (sous la forme nom_bdd.nom_schéma.nom_table ou nom_schéma.nom_table), alors Snowpipe charge les données dupliquées dans la table source (c’est-à-dire base de données.schéma.table de l’instruction COPY) pour chaque canal.

  • Si une table n’est pas pleinement qualifiée dans la définition du canal, alors Snowpipe charge les données dans la même table (par exemple, mytable) dans les bases de données/schémas sources et clonés.

Étape 3 : Configurer la sécurité

Pour chaque utilisateur qui exécutera des chargements de données continus avec Snowpipe, 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).

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.

L’utilisation de Snowpipe nécessite un rôle avec les privilèges suivants :

Objet

Privilège

Remarques

Canal nommé

OWNERSHIP

Zone de préparation nommée

USAGE , READ

Format de fichier nommé

USAGE

Facultatif ; nécessaire uniquement si la zone de préparation que vous avez créée dans Étape 1 : Étape 1 : Créer une zone de préparation (si nécessaire) 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”snowpipe_db.public objets de base de données ainsi qu’à un canal nommé mypipe ; puis, accordez 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 snowpipe_db to role snowpipe1;

grant usage on schema snowpipe_db.public to role snowpipe1;

grant insert, select on snowpipe_db.public.mytable to role snowpipe1;

grant usage on stage snowpipe_db.public.mystage to role snowpipe1;

-- Grant the OWNERSHIP privilege on the pipe object
grant ownership on pipe snowpipe_db.public.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 : Configurer des notifications d’événement

Configurez les notifications d’événement pour votre compartiment S3 afin d’avertir Snowpipe lorsque de nouvelles données sont disponibles au chargement. La fonction d’intégration automatique repose sur des files d’attente SQS pour transmettre des notifications d’événement de S3 à Snowpipe.

Pour faciliter les choses, les files d’attente SQS de Snowpipe sont créées et gérées par Snowflake. Le résultat de la commande SHOW PIPES affiche le nom de ressource Amazon (ARN) de votre file d’attente SQS.

  1. Exécutez la commande SHOW PIPES :

    SHOW PIPES;
    

    Notez l’ARN de la file d’attente SQS pour la zone de préparation de la colonne notification_channel. Copiez l’ARN dans un emplacement approprié.

    Note

    Conformément aux consignes d’AWS, Snowflake ne désigne pas plus d’une file d’attente SQS par compartiment S3. Cette file d’attente SQS peut être partagée entre plusieurs compartiments du même compte AWS. La file d’attente SQS coordonne les notifications pour tous les canaux connectant les zones de préparation externes du compartiment S3 aux tables cibles. Lorsqu’un fichier de données est chargé dans le compartiment, tous les canaux correspondant au chemin du répertoire de la zone de préparation effectuent un chargement unique du fichier dans les tables cibles correspondantes.

  2. Connectez-vous à la console Amazon S3.

  3. Configurez une notification d’événement pour votre compartiment S3 à l’aide des instructions fournies dans la documentation Amazon S3. Remplissez les champs comme suit :

    • Name : nom de la notification d’événement (par exemple Auto-ingest Snowflake).

    • Events : sélectionnez l’option ObjectCreate (All).

    • Send to : sélectionnez SQS Queue dans la liste déroulante.

    • SQS : sélectionnez Add SQS queue ARN dans la liste déroulante.

    • SQS queue ARN : collez le nom de la file d’attente SQS à partir de la sortie SHOW PIPES.

Note

Ces instructions créent une notification d’événement unique qui surveille l’activité de l’ensemble du compartiment S3. C’est l’approche la plus simple. Cette notification traite tous les canaux configurés à un niveau plus granulaire dans le répertoire de compartiment S3. Snowpipe charge uniquement les fichiers de données comme spécifié dans les définitions de canaux. Notez cependant qu’un nombre élevé de notifications d’activité en dehors d’une définition de canal pourrait avoir un impact négatif sur la vitesse à laquelle Snowpipe filtre les notifications et se met en marche.

Dans les étapes ci-dessus, vous pouvez également configurer un ou plusieurs chemins et/ou extensions de fichiers (ou préfixes et suffixes, dans la terminologie AWS) pour filtrer l’activité des événements. Pour obtenir des instructions, voir les informations de filtrage du nom de la clé d’objet dans la rubrique concernée de la documentation AWS. Répétez ces étapes pour chaque chemin ou extension de fichier supplémentaire que vous souhaitez que la notification surveille.

Notez que AWS limite le nombre de ces configurations de file d’attente de notification à un maximum de 100 par compartiment S3.

Notez également que AWS n’autorise pas les configurations de file d’attente qui se chevauchent (entre les notifications d’événement) pour le même compartiment S3. Par exemple, si une notification existante est configurée pour s3://mybucket/load/path1, vous ne pouvez pas en créer une autre à un niveau supérieur, tel que s3://mybucket/load, ou inversement.

Snowpipe avec l’intégration automatique est maintenant configuré !

Lorsque de nouveaux fichiers de données sont ajoutés au compartiment S3, la notification d’événement indique à Snowpipe de les charger dans la table cible définie dans le canal.

Étape 5 : Charger des fichiers historiques

Pour charger les retards de traitement des fichiers de données qui existaient dans la zone de préparation externe avant que les notifications SQS aient été configurées, voir Chargement de données historiques.

Option 2 : Configuration d’Amazon SNS pour automatiser Snowpipe à l’aide de notifications SQS

Cette section explique comment déclencher automatiquement les chargements de données Snowpipe à l’aide de notifications Amazon SQS (Simple Queue Service) pour un compartiment S3. Les étapes expliquent comment configurer Amazon Simple Notification Service (SNS) en tant que diffuseur afin de publier des notifications d’événement pour votre compartiment S3 à plusieurs abonnés (par exemple, files d’attente SQS ou charges de travail AWS Lambda), y compris la file d’attente SQS de Snowflake pour l’automatisation de Snowpipe.

Note

Ces instructions supposent qu’une notification d’événement existe pour le chemin cible dans votre compartiment S3 où se trouvent vos fichiers de données. Si aucune notification d’événement n’existe, vous avez deux possibilités :

Le diagramme suivant illustre le flux de processus pour l’intégration automatique de Snowpipe avec Amazon SNS :

Snowpipe Auto-ingest Process Flow with Amazon SNS
  1. Les fichiers de données sont chargés dans une zone de préparation.

  2. Une notification d’événement S3 publiée par SNS informe Snowpipe via une file d’attente SQS que les fichiers sont prêts à être chargés. Snowpipe copie les fichiers dans une file d’attente.

  3. Un entrepôt virtuel fourni par Snowflake charge les données des fichiers en file d’attente dans la table cible en fonction des paramètres définis dans le canal spécifié.

Note

Les instructions supposent qu’une table cible existe déjà dans la base de données Snowflake où vos données seront chargées.

Conditions préalables : Créer un sujet et un abonnement Amazon SNS

  1. Créez un sujet SNS dans votre compte AWS pour gérer tous les messages de l’emplacement de zone de préparation Snowflake sur votre compartiment S3.

  2. Souscrivez vos destinations cibles aux notifications d’événement S3 (par exemple, autres files d’attente SQS ou charges de travail Lambda AWS) à cette rubrique. SNS publie des notifications d’événement pour votre compartiment à tous les abonnés du sujet.

Pour obtenir des instructions, reportez-vous à la documentation SNS.

Étape 1 : S’abonner à la file d’attente SQS de Snowflake dans le sujet SNS

  1. Connectez-vous à la console de gestion AWS.

  2. Dans le tableau de bord d’accueil, sélectionnez Simple Notification Service (SNS).

  3. Cliquez sur Topics dans le volet de navigation de gauche.

  4. Recherchez le sujet de votre compartiment S3. Notez le sujet ARN.

  5. À l’aide d’un client Snowflake, interrogez la fonction système SYSTEM$GET_AWS_SNS_IAM_POLICY avec l’ARN de votre sujet SNS :

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

    La fonction renvoie une stratégie IAM accordant à la file d’attente SQS de Snowflake l’autorisation de s’abonner au sujet SNS.

    Par exemple :

    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"]}]}                 |
    +---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    
  6. Revenez à la console de gestion AWS. Cliquez sur Topics dans le volet de navigation de gauche.

  7. Cochez la case en regard du sujet de votre compartiment S3, puis cliquez sur Edit topic policy dans le menu Actions. Cliquez sur l’onglet Advanced view pour modifier le format JSON de la stratégie.

  8. Fusionnez l’ajout de stratégie IAM des résultats de la fonction SYSTEM$GET_AWS_SNS_IAM_POLICY dans le document JSON.

    Par exemple :

    Politique IAM originale (abrégée) :

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

    Politique IAM fusionnée :

    {
      "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"
             ]
         }
       ]
     }
    
  9. Ajoutez une autorisation de politique supplémentaire pour permettre à S3 de publier des notifications d’événement pour le compartiment dans le sujet SNS.

    Par exemple (en utilisant le sujet ARN SNS et le compartiment S3 utilisés dans ces instructions) :

    {
        "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"
           }
        }
     }
    

    Politique IAM fusionnée :

    {
      "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"
               }
            }
          }
       ]
     }
    
  10. Cliquez sur le bouton Update policy.

Étape 2 : créer une zone de préparation (si nécessaire)

Créez une zone de préparation externe qui fait référence à votre compartiment S3 à l’aide de la commande CREATE STAGE. Snowpipe va chercher vos fichiers de données dans la zone de préparation et les mettre temporairement en file d’attente avant de les charger dans votre table cible.

Vous pouvez aussi utiliser une zone de préparation externe.

Note

Pour configurer un accès sécurisé à l’emplacement de stockage Cloud, voir Configuration de l’accès sécurisé au stockage Cloud (dans cette rubrique).

L’exemple suivant crée une zone de préparation nommée mystage dans le schéma actif de la session utilisateur. L’URL de stockage Cloud inclut le chemin files. La zone de préparation fait référence à une intégration de stockage nommée myint :

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

Étape 3 : créer un canal avec l’intégration automatique activée

Créez un canal à l’aide de la commande CREATE PIPE. Le canal définit l’instruction COPY INTO <table> utilisée par Snowpipe pour charger les données de la file d’attente d’acquisition dans la table cible. Dans l’instruction COPY, identifiez l’ARN du sujet SNS depuis Conditions préalables : Créer un sujet et un abonnement Amazon SNS.

L’exemple suivant crée un canal nommé mypipe dans le schéma actif de la session utilisateur. Le canal charge toutes les données des fichiers mis dans la zone de préparation mystage dans la table mytable :

create pipe snowpipe_db.public.mypipe
  auto_ingest=true
  aws_sns_topic='<sns_topic_arn>'
  as
    copy into snowpipe_db.public.mytable
    from @snowpipe_db.public.mystage
  file_format = (type = 'JSON');

Où :

AUTO_INGEST = true

Spécifie de lire les notifications d’événements envoyées d’un compartiment S3 à une file d’attente SQS lorsque de nouvelles données sont prêtes à être chargées.

AWS_SNS_TOPIC = '<sns_sujet_arn>'

Spécifie l’ARN du sujet SNS de votre compartiment S3, par exemple arn:aws:sns:us-west-2:001234567890:s3_mybucket dans l’exemple actuel. L’instruction CREATE PIPE souscrit la file d’attente Snowflake SQS à la rubrique SNS spécifiée. Notez que le canal ne copiera que les fichiers dans la file d’attente d’intégration déclenchée par des notifications d’événement via le sujet SNS.

Pour supprimer l’un des paramètres d’un canal, il est actuellement nécessaire de recréer le canal à l’aide de la syntaxe CREATE OR REPLACE PIPE.

Important

Comparez la référence de la zone de préparation dans la définition de canal avec les canaux existants. Vérifiez que les chemins de répertoire du même compartiment S3 ne se chevauchent pas. Sinon, plusieurs canaux pourraient charger le même ensemble de fichiers de données plusieurs fois dans une ou plusieurs tables cibles. Cela peut se produire, par exemple, lorsque plusieurs zones de préparation font référence au même compartiment S3 avec différents niveaux de granularité, tels que s3://mybucket/path1 et s3://mybucket/path1/path2. Dans ce cas d’utilisation, si les fichiers sont stockés dans s3://mybucket/path1/path2, les canaux pour les deux zones de préparation chargeraient une copie des fichiers.

Cela diffère de la configuration manuelle de Snowpipe (avec l’intégration automatique désactivée), qui oblige les utilisateurs à soumettre un ensemble de fichiers nommé à une API REST pour mettre en file d’attente les fichiers à charger. Lorsque l’intégration automatique est activée, chaque canal reçoit une liste de fichiers générée à partir des notifications d’événement S3. Des précautions supplémentaires sont nécessaires pour éviter la duplication des données.

Étape 4 : Configurer la sécurité

Pour chaque utilisateur qui exécutera des chargements de données continus avec Snowpipe, 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).

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.

L’utilisation de Snowpipe nécessite un rôle avec les privilèges suivants :

Objet

Privilège

Remarques

Canal nommé

OWNERSHIP

Zone de préparation nommée

USAGE , READ

Format de fichier nommé

USAGE

Facultatif ; nécessaire uniquement si la zone de préparation que vous avez créée dans Étape 2 : Créer une zone de préparation (si nécessaire) 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’est-à-dire les utilisateurs ayant le rôle SECURITYADMIN) ou ayant un rôle supérieur peuvent créer des rôles.

Par exemple, créez un rôle nommé snowpipe1 qui peut accéder à un ensemble d”snowpipe_db.public objets de base de données ainsi qu’à un canal nommé mypipe ; puis, accordez 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 snowpipe_db to role snowpipe1;

grant usage on schema snowpipe_db.public to role snowpipe1;

grant insert, select on snowpipe_db.public.mytable to role snowpipe1;

grant usage, read on stage snowpipe_db.public.mystage to role snowpipe1;

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

Snowpipe avec l’intégration automatique est maintenant configuré !

Lorsque de nouveaux fichiers de données sont ajoutés au compartiment S3, la notification d’événement indique à Snowpipe de les charger dans la table cible définie dans le canal.

Étape 5 : Charger des fichiers historiques

Pour charger les retards de traitement des fichiers de données qui existaient dans la zone de préparation externe avant que les notifications SQS aient été configurées, voir Chargement de données historiques.

SYSTEM$PIPE_STATUS Sortie

La fonction SYSTEM$PIPE_STATUS récupère une représentation JSON du statut actuel d’un canal.

Pour les canaux avec AUTO_INGEST défini sur TRUE, la fonction renvoie un objet JSON contenant les paires nom/valeur suivantes (si applicable au statut actuel du canal) :

{« executionState »: »<valeur> », »oldestFileTimestamp »:<valeur>, »pendingFileCount »:<valeur>, »notificationChannelName »: »<valeur> », »numOutstandingMessagesOnChannel »:<valeur>, »lastReceivedMessageTimestamp »: »<valeur> », »lastForwardedMessageTimestamp »: »<valeur> », »error »:<valeur>, »fault »:<valeur>}

Où :

executionState

État d’exécution actuel du canal ; pourrait être l’un des éléments suivants :

  • RUNNING (c’est-à-dire que tout est normal ; Snowflake peut ou non traiter activement les fichiers de ce canal)

  • STOPPED_FEATURE_DISABLED

  • STOPPED_STAGE_DROPPED

  • STOPPED_FILE_FORMAT_DROPPED

  • STOPPED_MISSING_PIPE

  • STOPPED_MISSING_TABLE

  • STALLED_COMPILATION_ERROR

  • STALLED_INITIALIZATION_ERROR

  • STALLED_EXECUTION_ERROR

  • STALLED_INTERNAL_ERROR

  • PAUSED

  • PAUSED_BY_SNOWFLAKE_ADMIN

  • PAUSED_BY_ACCOUNT_ADMIN

oldestFileTimestamp

Le plus ancien horodatage parmi les fichiers de données en file d’attente (le cas échéant), l’horodatage étant défini lors de l’ajout du fichier à la file d’attente.

pendingFileCount

Nombre de fichiers en cours de traitement par le canal. Si le canal est mis en pause, cette valeur diminue à mesure que tous les fichiers en file d’attente avant que le canal a été mis en pause sont traités. Lorsque cette valeur est 0, aucun fichier n’est en file d’attente pour ce canal ou le canal est effectivement mis en pause.

notificationChannelName

File d’attente Amazon SQS associée au canal.

numOutstandingMessagesOnChannel

Nombre de messages dans la file d’attente SQS qui ont été mis en file d’attente mais pas encore reçus.

lastReceivedMessageTimestamp

Horodatage du dernier message reçu de la file d’attente SQS. Notez que ce message peut ne pas s’appliquer au canal spécifique, par exemple si le chemin/préfixe associé au message ne correspond pas au chemin/préfixe de la définition du canal. De plus, seuls les messages déclenchés par des objets de données créés sont consommés par les canaux d’intégration automatique.

lastForwardedMessageTimestamp

Horodatage du dernier message d’événement « créer un objet » avec un chemin/préfixe correspondant qui a été transmis au canal.

error

Message d’erreur généré lors de la dernière compilation du canal en vue de son exécution (le cas échéant) ; souvent causé par des problèmes d’accès aux objets requis (par exemple, une table, une zone de préparation, le format de fichier) en raison de problèmes d’autorisation ou d’objets perdus.

fault

La plus récente erreur interne liée au processus Snowflake (le cas échéant). Utilisé principalement par Snowflake à des fins de débogage.