Activation des notifications d’erreur Snowpipe pour Amazon SNS

Cette rubrique fournit des instructions pour envoyer des notifications d’erreur Snowpipe au service Amazon Simple Notification Service (SNS). SNS est un service de messagerie de type publication/abonnement.

Cette fonction permet d’envoyer des notifications d’erreur pour les types de chargements suivants :

  • Auto-intégration Snowpipe.

  • Appels vers le point de terminaison de l’API REST insertFiles Snowpipe.

  • Chargements à partir d’Apache Kafka en utilisant le connecteur Snowflake pour Kafka avec la méthode d’ingestion Snowpipe uniquement.

Dans ce chapitre :

Prise en charge de la plateforme Cloud

Cette fonctionnalité est actuellement limitée aux comptes Snowflake hébergés sur Amazon Web Services (AWS). Snowpipe peut charger des données à partir de fichiers dans n’importe quel service de stockage dans le Cloud pris en charge ; cependant, les notifications push vers SNS ne sont prises en charge que dans les comptes Snowflake hébergés sur AWS.

Remarques

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

  • Snowflake garantit la livraison des messages d’erreur au moins une fois (c’est-à-dire que plusieurs tentatives sont faites pour livrer les messages afin de s’assurer qu’au moins une tentative réussisse, ce qui peut entraîner des messages en double).

Activation des notifications d’erreur

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

Note

Seules les rubriques SNS standard sont prises en charge. Ne pas créer de sujets SNS FIFO (premier entré, premier sorti) pour les notifications d’erreur. Actuellement, les notifications d’erreur envoyées aux sujets FIFO échouent en silence.

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

    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 saisissez 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 intégration de notification peut prendre en charge plusieurs tâches et 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>'
Copy

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

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

    Où :

    • integration_name 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=   |                      |
    +---------------------------+-------------------+------------------------------------------------------+----------------------+
    
    Copy
  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>"
            }
          }
        }
      ]
    }
    
    Copy

    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.

Notez que l’exploitation d’un objet dans un schéma requiert également le privilège USAGE sur la base de données et le schéma parents.

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

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

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

Canal existant

Modifiez un canal existant en utilisant ALTER PIPE :

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

<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 mypipe SET ERROR_INTEGRATION = my_notification_int;
Copy

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

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