Actualisation automatique des tables de répertoire pour Amazon S3¶

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

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

Pour configurer les autorisations d’accès à Snowflake dans la Console de gestion AWS, procédez comme suit :

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

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

   

3. Dans le volet de navigation de gauche, sélectionnez Roles.

4. Sélectionnez Create role.

   

5. Sélectionnez Another AWS account comme type d’entité de confiance.

6. Dans le champ Account ID saisissez 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. Un ID externe est utilisé pour accorder l’accès à vos ressources AWS (telles que des compartiments S3) à un tiers comme Snowflake.

   Saisissez un ID de type caractère générique tel que 0000. À une étape ultérieure, vous modifierez la relation de confiance de votre rôle IAM et spécifierez l’ID externe de votre intégration de stockage.

8. Sélectionnez Next.

9. Sélectionnez la politique que vous avez créée à l”étape 1 : Configuration des autorisations d’accès au compartiment S3 (dans ce chapitre).

10. Sélectionnez Next.

    

11. Saisissez un nom et une description pour le rôle, puis sélectionnez 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. Sur la page de synthèse du rôle, recherchez et enregistrez la valeur Role ARN. Dans l’étape suivante, vous créerez une intégration Snowflake qui fait référence à ce rôle.

    

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

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

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

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

• bucket 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.

• path 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 autorise l’accès à tous les compartiments du compte, mais bloque l’accès aux dossiers sensitivedata définis.

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

Copy

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

1. Pour récupérer l’ARN de l’utilisateur IAM automatiquement créé pour votre compte Snowflake, utilisez DESCRIBE INTEGRATION.

   DESC INTEGRATION <integration_name>;
   

   Copy

   Où :

   • integration_name est le nom de l’intégration créée à l”étape 3 : Création d’une intégration Cloud Storage dans Snowflake (ce chapitre).

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

   Copy

2. Enregistrez les valeurs des propriétés suivantes :

   Propriété	Description
   STORAGE_AWS_IAM_USER_ARN	Utilisateur IAM AWS créé pour votre compte Snowflake, par exemple, arn:aws:iam::123456789001:user/abc1-b-self1234. Snowflake provisionne un seul utilisateur IAM pour l’intégralité de votre compte Snowflake. Toutes les intégrations de stockage S3 de votre compte utilisent cet utilisateur IAM.
   STORAGE_AWS_EXTERNAL_ID	ID externe que Snowflake utilise pour établir une relation de confiance avec AWS. Si vous n’avez pas spécifié d’ID externe (STORAGE_AWS_EXTERNAL_ID) lorsque vous avez créé l’intégration de stockage, Snowflake génère un ID à utiliser.

   Vous fournirez ces valeurs à 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. Sélectionnez Identity & Access Management (IAM) :

   

3. Dans le volet de navigation de gauche, sélectionnez Roles.

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

5. Sélectionnez l’onglet Trust relationships.

6. Sélectionnez 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>"
           }
         }
       }
     ]
   }
   

   Copy

   Où :

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

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

     Dans cet exemple, la valeur snowflake_external_id est MYACCOUNT_SFCRole=2_a123456/s0aBCDEfGHIJklmNoPq=.

     Note

     Pour des raisons de sécurité, si vous créez une nouvelle intégration de stockage (ou si vous recréez une intégration de stockage existante à l’aide de la syntaxe CREATE OR REPLACE STORAGE INTEGRATION) sans spécifier d’ID externe, la nouvelle intégration a un ID externe différent et ne peut donc résoudre la relation de confiance, sauf si vous mettez à jour la politique de confiance.

8. Sélectionnez le bouton Update Trust Policy. Les modifications sont enregistrées.

Étape 1 : Création d’une zone de préparation avec une table de répertoire incluse¶

Créez une zone de préparation externe qui fait référence à votre compartiment S3 à l’aide de la commande CREATE STAGE. Snowflake lit vos fichiers de données en zone de préparation dans les métadonnées de la table de répertoire. Vous pouvez aussi utiliser une zone de préparation externe existante.

-- External stage
CREATE [ OR REPLACE ] [ TEMPORARY ] STAGE [ IF NOT EXISTS ] <external_stage_name>
      <cloud_storage_access_settings>
    [ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
    [ directoryTable ]
    [ COPY_OPTIONS = ( copyOptions ) ]
    [ COMMENT = '<string_literal>' ]

Où :

directoryTable (for Amazon S3) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ AUTO_REFRESH = { TRUE | FALSE } ] ) ]

Copy

CREATE STAGE mystage
  URL='s3://load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (
    ENABLE = true
    AUTO_REFRESH = true
  );

Étape 2 : Configuration de notifications d’événement¶

Configurez les notifications d’événement pour votre compartiment S3 afin d’avertir Snowflake lorsque des données nouvelles ou mises à jour sont disponibles pour être lues dans les métadonnées de la table de répertoire. La fonctionnalité d’actualisation automatique s’appuie sur les files d’attente SQS pour transmettre les notifications d’événement de S3 à Snowflake.

Pour faciliter l’utilisation, ces files d’attente SQS sont créées et gérées par Snowflake. Le résultat de la commande DESCRIBE STAGE affiche le nom de ressource Amazon (ARN) de votre file d’attente SQS.

1. Exécutez la commande DESCRIBE STAGE :

   DESC STAGE <stage_name>;
   

   Copy

   Par exemple :

   DESC STAGE mystage;
   

   Copy

   Notez l’ARN de la file d’attente SQS de la table de répertoire dans le champ directory_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 de toutes les tables de répertoire lisant des fichiers de données à partir du même compartiment S3. Lorsqu’un fichier de données nouveau ou modifié est téléchargé dans le compartiment, toutes les définitions de table de répertoire correspondant au chemin du répertoire de la zone de préparation lisent les détails du fichier dans leurs métadonnées.

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

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 les options ObjectCreate (All) et ObjectRemoved.

   • 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 DESC STAGE.

La zone de préparation externe avec actualisation automatique est maintenant configurée !

Lorsque des fichiers de données nouveaux ou mis à jour sont ajoutés au compartiment S3, la notification d’événement demande à Snowflake de les analyser dans les métadonnées de la table de répertoire.

Étape 3 : Actualisation manuelle des métadonnées d’une table de répertoire¶

Actualiser manuellement les métadonnées d’une table de répertoire à l’aide de la commande ALTER STAGE.

ALTER STAGE [ IF EXISTS ] <name> REFRESH [ SUBPATH = '<relative-path>' ]

Où :

REFRESH

Accède aux fichiers de données mis en zone de préparation, et référencés dans la définition de table de répertoire et met à jour les métadonnées de la table :

• Les nouveaux fichiers dans le chemin sont ajoutés aux métadonnées de la table.

• Les modifications apportées aux fichiers dans le chemin sont mises à jour dans les métadonnées de la table.

• Les fichiers qui ne figurent plus dans le chemin sont supprimés des métadonnées de la table.

Actuellement, il est nécessaire d’exécuter cette commande chaque fois que des fichiers sont ajoutés à la zone de préparation, mis à jour ou détruits. Cette étape synchronise les métadonnées avec le dernier ensemble de fichiers associés dans la définition de la zone de préparation pour la table de répertoire.

SUBPATH = '<relative-path>'

Spécifiez éventuellement un chemin relatif pour actualiser les métadonnées pour un sous-ensemble spécifique des fichiers de données.

Par exemple, actualisez manuellement les métadonnées de la table de répertoire dans une zone de préparation nommée mystage :

ALTER STAGE mystage REFRESH;

Étape 4 : Configuration de la sécurité¶

Pour chaque rôle supplémentaire qui sera utilisé pour interroger la table de répertoire, accordez des privilèges de contrôle d’accès suffisants sur les différents objets (c.-à-d. la ou les bases de données, le ou les schémas, la zone de préparation et la table) avec GRANT <privilèges> :

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>');
   

   Copy

   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"]}]}                 |
   +---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   

   Copy

6. Revenez à la console de gestion AWS. Cliquez sur Topics dans le volet de navigation de gauche.

7. Sélectionnez le sujet de votre compartiment S3 et cliquez sur le bouton Edit. La page Edit s’ouvre.

8. Cliquez sur Access policy - Optional pour développer cette zone de la page.

9. 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":"*"
           }
           ..
        }
      ]
    }
   

   Copy

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

   Copy

10. 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"
           }
        }
     }
    

    Copy

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

    Copy

11. Cliquez sur le bouton Save changes.

Étape 2 : Création d’une zone de préparation incluant une table de répertoire¶

Créez une zone de préparation externe qui fait référence à votre compartiment S3 à l’aide de la commande CREATE STAGE. Snowflake lit vos fichiers de données en zone de préparation dans les métadonnées de la table de répertoire. Vous pouvez aussi utiliser une zone de préparation externe existante.

-- External stage
CREATE [ OR REPLACE ] [ TEMPORARY ] STAGE [ IF NOT EXISTS ] <external_stage_name>
      <cloud_storage_access_settings>
    [ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
    [ directoryTable ]
    [ COPY_OPTIONS = ( copyOptions ) ]
    [ COMMENT = '<string_literal>' ]

Où :

directoryTable (for Amazon S3) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ AUTO_REFRESH = { TRUE | FALSE } ]
                  [ AWS_SNS_TOPIC = '<sns_topic_arn>' ] ) ]

Copy

CREATE STAGE mystage
  URL='s3://load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (
    ENABLE = true
    AUTO_REFRESH = true
    AWS_SNS_TOPIC = 'arn:aws:sns:us-west-2:001234567890:s3_mybucket'
  );

Étape 3 : Actualisation manuelle des métadonnées d’une table de répertoire¶

Actualiser manuellement les métadonnées d’une table de répertoire à l’aide de la commande ALTER STAGE.

ALTER STAGE [ IF EXISTS ] <name> REFRESH [ SUBPATH = '<relative-path>' ]

Où :

REFRESH

Accède aux fichiers de données mis en zone de préparation, et référencés dans la définition de table de répertoire et met à jour les métadonnées de la table :

• Les nouveaux fichiers dans le chemin sont ajoutés aux métadonnées de la table.

• Les modifications apportées aux fichiers dans le chemin sont mises à jour dans les métadonnées de la table.

• Les fichiers qui ne figurent plus dans le chemin sont supprimés des métadonnées de la table.

Actuellement, il est nécessaire d’exécuter cette commande chaque fois que des fichiers sont ajoutés à la zone de préparation, mis à jour ou détruits. Cette étape synchronise les métadonnées avec le dernier ensemble de fichiers associés dans la définition de la zone de préparation pour la table de répertoire.

SUBPATH = '<relative-path>'

Spécifiez éventuellement un chemin relatif pour actualiser les métadonnées pour un sous-ensemble spécifique des fichiers de données.

Par exemple, actualisez manuellement les métadonnées de la table de répertoire dans une zone de préparation nommée mystage :

ALTER STAGE mystage REFRESH;

Étape 4 : Configuration de la sécurité¶

Pour chaque rôle supplémentaire qui sera utilisé pour interroger la table de répertoire, accordez des privilèges de contrôle d’accès suffisants sur les différents objets (c.-à-d. la ou les bases de données, le ou les schémas, la zone de préparation et la table) avec GRANT <privilèges> :