Activation des notifications d’erreur Snowpipe pour Microsoft Azure Event Grid

Cette rubrique fournit des instructions pour envoyer des notifications d’erreur Snowpipe à Microsoft Azure Event Grid (Event Grid).

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 plate-forme Cloud

Cette fonctionnalité est actuellement limitée aux comptes Snowflake hébergés sur Microsoft Azure. Snowpipe peut charger des données à partir de fichiers dans n’importe quel service de stockage dans le Cloud pris en charge. Toutefois, les notifications push vers Event Grid ne sont prises en charge que dans les comptes Snowflake hébergés sur Azure.

Remarques

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

  • 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

Étape 1 : Création d’une rubrique Event Grid personnalisée

Une rubrique Event Grid fournit un point de terminaison où la source envoie des notifications d’événements. Créez une rubrique dédiée pour recevoir les notifications d’erreur publiées par Snowflake. Vous pouvez utiliser un seul sujet pour recevoir des notifications d’erreur pour tous les canaux (pour les notifications d’erreur Snowpipe) ou pour toutes les tâches (pour les notifications d’erreur de tâches) dans votre compte Snowflake.

Pour obtenir des instructions sur la création de rubriques Event Grid, consultez la documentation Event Grid. Enregistrez le point de terminaison de la rubrique Event Grid, dont vous aurez besoin plus tard dans ces instructions.

Vous pouvez également vous abonner à la rubrique pour indiquer à Event Grid les événements que vous souhaitez suivre et où envoyer ces événements.

Étape 2 : Création d’une intégration de notification dans Snowflake

Récupérer l’ID du client

Récupérez votre ID de client Azure, dont vous aurez besoin plus tard dans ces instructions.

  1. Connectez-vous au portail Microsoft Azure.

  2. Accédez à Azure Active Directory » Properties. Enregistrez la valeur Tenant ID pour référence plus tard. L’ID de répertoire , ou ID de client, est nécessaire pour générer l’URL de consentement qui accorde à Snowflake l’accès à la rubrique Event Grid.

Créer l’intégration des notifications

Créez une intégration à l’aide de la commande CREATE NOTIFICATION INTEGRATION. une intégration est un objet Snowflake qui fait référence à la file d’attente du stockage Azure que vous avez créée.

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 = AZURE_EVENT_GRID
  DIRECTION = OUTBOUND
  AZURE_EVENT_GRID_TOPIC_ENDPOINT = '<event_grid_topic_endpoint>'
  AZURE_TENANT_ID = '<azure_tenant_id>'
Copy

Par exemple :

CREATE NOTIFICATION INTEGRATION myint
  ENABLED = true
  TYPE = QUEUE
  NOTIFICATION_PROVIDER = AZURE_EVENT_GRID
  DIRECTION = OUTBOUND
  AZURE_EVENT_GRID_TOPIC_ENDPOINT = 'https://myaccount.region-1.eventgrid.azure.net/api/events'
  AZURE_TENANT_ID = 'mytenantid';
Copy

Où :

  • event_grid_topic_endpoint est le point de terminaison de la rubrique Event Grid que vous avez enregistré à l’étape 1 de la section.

  • azure_tenant_id est votre ID de répertoire Azure, ou ID de client, que vous avez enregistré plus tôt dans cette section.

Accorder un accès à Snowflake à la rubrique

  1. Exécutez la commande DESCRIBE INTEGRATION pour récupérer l’URL de consentement :

    DESC NOTIFICATION INTEGRATION <integration_name>;
    
    Copy

    Où :

    Notez les valeurs dans les colonnes suivantes :

    AZURE_CONSENT_URL

    URL vers la page de demande d’autorisations de Microsoft.

    AZURE_MULTI_TENANT_APP_NAME

    Nom de l’application client Snowflake créée pour votre compte. Plus loin dans cette section, vous devrez accorder à cette application les autorisations nécessaires pour obtenir un jeton d’accès sur votre sujet autorisé.

  2. Dans un navigateur Web, accédez à l’URL dans la colonne AZURE_CONSENT_URL . La page affiche une page de demande d’autorisations Microsoft.

  3. Cliquez sur le bouton Accept. Cette action permet au principal du service Azure créé pour votre compte Snowflake d’obtenir un jeton d’accès sur des ressources spécifiées à l’intérieur de votre client. L’obtention d’un jeton d’accès ne réussit que si vous accordez au principal du service les autorisations appropriées sur le conteneur (voir l’étape suivante).

    La page de demande d’autorisations Microsoft redirige vers le site d’entreprise de Snowflake (snowflake.com).

  4. Connectez-vous au portail Microsoft Azure.

  5. Accédez à Azure Active Directory » Enterprise applications. Vérifiez que l’identificateur de l’application Snowflake que vous avez enregistré à l’étape 2 de cette section est répertorié.

    Important

    Si vous supprimez l’application Snowflake dans Azure Active Directory plus tard, l’intégration des notifications cesse de fonctionner.

  6. Naviguez jusqu’à Event Grid Topics » topic_name, où topic_name est le nom de la rubrique que vous avez créée pour recevoir les notifications d’événements.

  7. Cliquez sur Access Control (IAM) » Add role assignment.

  8. Recherchez le principal de service Snowflake. Il s’agit de l’identité de la propriété AZURE_MULTI_TENANT_APP_NAME dans la sortie DESC NOTIFICATION INTEGRATION (à l’étape 1). Recherchez la chaîne avant le trait de soulignement dans la propriété AZURE_MULTI_TENANT_APP_NAME.

    Important

    • Azure peut prendre une heure ou plus pour créer le principal de service Snowflake demandé via la page de demande Microsoft dans cette section. Si le principal de service n’est pas disponible immédiatement, nous vous recommandons d’attendre une heure ou deux, puis de relancer la recherche.

    • Si vous supprimez le principal de service, l’intégration de notification cesse de fonctionner.

  9. Accordez à l’application Snowflake l’autorisation EventGrid Data Sender.

Étape 3 : 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 :

CREATE PIPE <name>
  AUTO_INGEST = TRUE
  [ INTEGRATION = '<string>' ]
  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).

Par exemple :

CREATE PIPE mypipe
  AUTO_INGEST = TRUE
  INTEGRATION = 'my_storage_int'
  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\":\"azure://myaccount.blob.core.windows.net/mycontainer/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.