Activation des notifications d’erreur pour Snowpipe

Cette rubrique fournit des instructions pour configurer la prise en charge des notifications d’erreur pour Snowpipe. Lorsque Snowpipe rencontre des erreurs lors du chargement des données d’un fichier en zone de préparation, cette fonctionnalité déclenche une notification qui décrit les erreurs à l’aide de la messagerie dans le Cloud, ce qui permet une analyse plus approfondie des données du fichier.

Note

Cette fonctionnalité est actuellement limitée aux comptes Snowflake hébergés sur Amazon Web Services (AWS). Les objets Pipe d’un compte peuvent charger des données à partir de fichiers dans n’importe quel service de stockage Cloud pris en charge. Toutefois, Snowpipe ne peut envoyer des notifications d’erreur qu’à Amazon Simple Notification Service (SNS).

La prise en charge des comptes Snowflake hébergés sur Google Cloud ou Microsoft Azure et des services de messagerie dans le Cloud respectifs est prévue.

Cette fonctionnalité prend en charge les appels vers l’API REST de Snowpipe ainsi que Snowpipe automatisé (auto-ingest) à l’aide d’un service de messagerie dans le Cloud.

Dans ce chapitre :

Remarques

  • Snowflake fait de son mieux pour assurer la livraison des messages de notification d’erreur, mais ne peut pas garantir la livraison pendant cette avant-première.

  • Cette fonctionnalité est mise en œuvre à l’aide de l’objet d’intégration de notification. Une intégration de notification est un objet Snowflake qui fournit une interface entre Snowflake et des services tiers de mise en file d’attente de messages dans le Cloud. Une seule intégration de notification peut prendre en charge plusieurs canaux.

Activation des notifications d’erreur pour Amazon S3

Cette section fournit des instructions pour la configuration des notifications d’erreur à l’aide du service Amazon Simple Notification Service (SNS). SNS est un service de messagerie de type publication/abonnement.

Étape 1 : Créer un sujet SNS Amazon

Créez un sujet SNS dans votre compte AWS pour gérer tous les messages d’erreur. Enregistrez le nom de la ressource Amazon (ARN) pour la file d’attente SNS.

Pour réduire la latence et éviter des frais de sortie de données pour l’envoi de notifications entre régions, nous vous recommandons de créer le sujet SNS dans la même région que votre compte Snowflake.

Pour obtenir des instructions, consultez la rubrique Création d’un sujet SNS Amazon dans la documentation SNS.

Étape 2 : Création de la politique IAM

Créez une politique de gestion des identités et des accès AWS (IAM) qui accorde des autorisations pour appeler le sujet SNS. La politique définit les actions suivantes :

  • sns:publish

    Publiez dans le sujet SNS.

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

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

  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.

  7. Cliquez sur l’onglet JSON.

  8. Ajoutez un document de politique qui définit les actions qui peuvent être prises sur votre sujet SNS.

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

    {
        "Version": "2012-10-17",
        "Statement": [
          {
             "Effect": "Allow",
             "Action": [
                 "sns:Publish"
             ],
             "Resource": "<sns_topic_arn>"
          }
        ]
     }
    

    Remplacez sns_topic_arn par l’ARN du sujet SNS que vous avez créé à l”étape 1 : Création d’un sujet SNS Amazon (dans cette rubrique).

  9. Cliquez sur Review policy.

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

Étape 3 : Création du rôle IAM AWS

Créez un rôle AWS IAM auquel attribuer des privilèges sur le sujet SNS.

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

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

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

  4. Cliquez sur le bouton Create role.

  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.

  7. Sélectionnez l’option Require external ID. Cette option vous permet d’accorder des autorisations sur les ressources de votre compte Amazon (c’est-à-dire SNS) à un tiers (c’est-à-dire Snowflake).

    Pour le moment, entrez un ID fictif tel que 0000. Plus tard, vous modifierez la relation de confiance et remplacerez l’ID fictif par l’ID externe pour l’utilisateur IAM de Snowflake généré pour votre compte. Une condition dans la politique de confiance pour votre rôle IAM permet à vos utilisateurs Snowflake d’assumer le rôle en utilisant l’objet d’intégration de notification que vous créerez plus tard.

  8. Cliquez sur le bouton Next.

  9. Localisez la politique que vous avez créée lors de l”étape 2 : Création de la politique IAM (dans cette rubrique), et sélectionnez cette politique.

  10. Cliquez sur le bouton Next.

  11. Entrez un nom et une description pour le rôle et cliquez sur le bouton Create role.

  12. Enregistrez la valeur Role ARN située sur la page de résumé du rôle. Vous préciserez cette valeur dans une ou plusieurs étapes ultérieures.

Étape 4 : Création de l’intégration des notifications

Créez une intégration de notification en utilisant CREATE NOTIFICATION INTEGRATION. Une intégration est un objet Snowflake qui fait référence au sujet SNS que vous avez créé.

Une seule intégration de notification peut prendre en charge plusieurs canaux.

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 NOTIFICATION INTEGRATION <integration_name>
  ENABLED = true
  TYPE = QUEUE
  NOTIFICATION_PROVIDER = AWS_SNS
  DIRECTION = OUTBOUND
  AWS_SNS_TOPIC_ARN = '<topic_arn>'
  AWS_SNS_ROLE_ARN = '<iam_role_arn>'

Où :

<nom_intégration>

Nom de la nouvelle intégration.

DIRECTION = OUTBOUND

Direction de la messagerie Cloud par rapport à Snowflake. Requis uniquement lors de la configuration des notifications d’erreur.

<sujet_arn>

ARN du sujet SNS que vous avez enregistré à l”étape 1 : Création d’un sujet Amazon SNS (dans cette rubrique).

<arn_rôle_iam>

ARN du rôle IAM que vous avez enregistré à l’étape 3 : Création du rôle IAM AWS (dans cette rubrique).

Par exemple :

CREATE NOTIFICATION INTEGRATION my_notification_int
  ENABLED = true
  TYPE = QUEUE
  NOTIFICATION_PROVIDER = AWS_SNS
  DIRECTION = OUTBOUND
  AWS_SNS_TOPIC_ARN = 'arn:aws:sns:us-east-2:111122223333:sns_topic'
  AWS_SNS_ROLE_ARN = 'arn:aws:iam::111122223333:role/error_sns_role';

Étape 5 : Accord d’un accès à Snowflake au sujet SNS

Récupérer l’ARN de l’utilisateur IAM et l’ID externe du sujet SNS

  1. Exécutez DESCRIBE INTEGRATION :

    DESC NOTIFICATION INTEGRATION <integration_name>;
    

    Où :

    • nom_intégration est le nom de l’intégration de notification créée à l”étape 4 : Création de l’intégration des notifications (dans cette rubrique).

    Par exemple :

    DESC NOTIFICATION INTEGRATION my_notification_int;
    
    +---------------------------+-------------------+------------------------------------------------------+----------------------+
    |   property                |   property_type   |   property_value                                     |   property_default   |
    +---------------------------+-------------------+------------------------------------------------------+----------------------+
    |   ENABLED                 |   Boolean         |   true                                               |   false              |
    |   NOTIFICATION_PROVIDER   |   String          |   AWS_SNS                                            |                      |
    |   DIRECTION               |   String          |   OUTBOUND                                           |   INBOUND            |
    |   AWS_SNS_TOPIC_ARN       |   String          |   arn:aws:sns:us-east-2:111122223333:myaccount       |                      |
    |   AWS_SNS_ROLE_ARN        |   String          |   arn:aws:iam::111122223333:role/myrole              |                      |
    |   SF_AWS_IAM_USER_ARN     |   String          |   arn:aws:iam::123456789001:user/c_myaccount         |                      |
    |   SF_AWS_EXTERNAL_ID      |   String          |   MYACCOUNT_SFCRole=2_a123456/s0aBCDEfGHIJklmNoPq=   |                      |
    +---------------------------+-------------------+------------------------------------------------------+----------------------+
    
  2. Enregistrez les valeurs générées suivantes :

    SF_AWS_IAM_USER_ARN

    ARN pour l’utilisateur IAM Snowflake créé pour votre compte. Les utilisateurs de votre compte Snowflake assumeront le rôle IAM que vous avez créé à l’étape 3 : Création du rôle IAM AWS en soumettant l’ID externe pour cet utilisateur en utilisant votre intégration de notification.

    SF_AWS_EXTERNAL_ID

    ID externe pour l’utilisateur IAM Snowflake créé pour votre compte.

    Dans l’étape suivante, vous allez mettre à jour la relation de confiance pour le rôle IAM avec ces valeurs.

Notez la propriété DIRECTION , qui indique la direction de la messagerie Cloud par rapport à Snowflake.

Modifier la relation de confiance dans le rôle IAM

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

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

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

  4. Cliquez sur le rôle que vous avez créé à l’étape 3 : Création du rôle IAM 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 NOTIFICATION INTEGRATION que vous avez enregistrées dans Récupérer l’ARN de l’utilisateur IAM et l’ID externe du sujet SNS (dans cette rubrique) :

    Document de politique pour le rôle IAM

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

    Où :

    • sf_aws_iam_user_arn est la valeur SF_AWS_IAM_USER_ARN que vous avez enregistrée.

    • sf_aws_external_id est la valeur SF_AWS_EXTERNAL_ID que vous avez enregistrée.

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

Étape 6 : Activation des notifications d’erreur dans les canaux

Une seule intégration de notification peut être partagée par plusieurs canaux. Le corps des messages d’erreur identifie le canal, la zone de préparation externe et le chemin, ainsi que le fichier d’où provient l’erreur, entre autres détails.

Pour activer les notifications d’erreur pour un canal, spécifiez une valeur de paramètre ERROR_INTEGRATION.

Note

La création ou la modification d’un canal qui fait référence à une intégration de notification nécessite un rôle qui possède le privilège USAGE sur l’intégration de notification. En outre, le rôle doit avoir le privilège CREATE PIPE sur le schéma ou le privilège OWNERSHIP sur le canal, respectivement.

Nouveau canal

Créez un nouveau canal en utilisant CREATE PIPE. Notez que la configuration des chargements de données automatisés (c’est-à-dire l’auto-ingestion Snowpipe) nécessite des paramètres de canal supplémentaires. Pour obtenir des instructions, voir Automatisation du chargement continu des données à l’aide de la messagerie Cloud.

CREATE PIPE <name>
  [ AUTO_INGEST = TRUE | FALSE  ]
  ERROR_INTEGRATION = <integration_name>
  AS <copy_statement>

Où :

ERROR_INTEGRATION = <nom_intégration>

Nom de l’intégration de notification créée à l”étape 4 : Création de l’intégration des notifications (dans cette rubrique).

L’exemple suivant montre une instruction CREATE PIPE qui prend en charge à la fois les notifications d’erreur et les chargements de données automatisés :

CREATE PIPE mypipe
  AUTO_INGEST = TRUE
  ERROR_INTEGRATION = my_notification_int
  AS
  COPY INTO mydb.public.mytable
  FROM @mydb.public.mystage;

Canal existant

Modifiez un canal existant en utilisant ALTER PIPE :

ALTER PIPE <name> SET ERROR_INTEGRATION = <integration_name>;

<nom_intégration> est le nom de l’intégration de notification créée à l”étape 4 : Création de l’intégration des notifications (dans cette rubrique).

Par exemple :

ALTER PIPE my_notification_int SET ERROR_INTEGRATION = my_notification_int;

Charge utile du message de notification d’erreur

Le corps des messages d’erreur identifie le canal et les erreurs rencontrées lors d’un chargement.

Voici un exemple de charge utile de message décrivant une erreur Snowpipe. Notez que la charge utile peut inclure un ou plusieurs messages d’erreur.

{\"version\":\"1.0\",\"messageId\":\"a62e34bc-6141-4e95-92d8-f04fe43b43f5\",\"messageType\":\"INGEST_FAILED_FILE\",\"timestamp\":\"2021-10-22T19:15:29.471Z\",\"accountName\":\"MYACCOUNT\",\"pipeName\":\"MYDB.MYSCHEMA.MYPIPE\",\"tableName\":\"MYDB.MYSCHEMA.MYTABLE\",\"stageLocation\":\"s3://mybucket/mypath\",\"messages\":[{\"fileName\":\"/file1.csv_0_0_0.csv.gz\",\"firstError\":\"Numeric value 'abc' is not recognized\"}]}

Notez que vous devez analyser la chaîne dans un objet JSON pour traiter les valeurs dans la charge utile.