Configuration de l’ingestion de données pour vos données ServiceNow¶

Modification de l’ingestion de données à l’aide de Snowsight¶

Pour modifier les tables ServiceNow à ingérer ou le calendrier de synchronisation des tables, procédez comme suit :

1. Connectez-vous à Snowsight en tant qu’utilisateur ayant le rôle ACCOUNTADMIN.

2. Dans la navigation de gauche, sélectionnez Marketplace.

3. Recherchez le connecteur Snowflake pour ServiceNow, puis sélectionnez la vignette pour le connecteur.

4. Dans la page Snowflake Connector for ServiceNow, sélectionnez Edit.

5. Modifiez les tables que vous souhaitez ingérer :

   1. Recherchez la table que vous souhaitez ingérer.

   2. Cochez la case dans la colonne Status à côté de la table que vous souhaitez sélectionner ou désélectionner.

   3. Sous Synch Schedule, sélectionnez la fréquence à laquelle vous souhaitez synchroniser la table entre Snowflake et ServiceNow.

6. Sélectionnez Update.

Spécification du calendrier de synchronisation¶

Le connecteur Snowflake pour ServiceNow synchronise les données de toutes les tables ServiceNow avec Snowflake selon un calendrier spécifié. Par défaut, toutes les tables sont synchronisées une fois par heure (1h).

Pour modifier le calendrier de synchronisation par défaut pour toutes les tables, appelez la procédure stockée CONFIGURE_CONNECTOR avec les arguments suivants :

CALL CONFIGURE_CONNECTOR('data_ingestion_schedule', '<schedule>');

Où :

data_ingestion_schedule (le littéral de chaîne)

Spécifie que vous voulez configurer le calendrier de synchronisation.

schedule

Spécifie la fréquence de la synchronisation. Vous pouvez spécifier l’une des valeurs de chaîne suivantes :

• '30m'

• '1h'

• '3h'

• '6h'

• '12h'

• '1d'

Le connecteur vous permet également de spécifier un calendrier différent pour chaque table dont la synchronisation est activée. Pour modifier le calendrier de synchronisation pour un ensemble sélectionné de tables, appelez la procédure stockée CONFIGURE_TABLES_SCHEDULE avec les arguments suivants :

CALL CONFIGURE_TABLES_SCHEDULE(<table_names>, <schedule>);

Où :

table_names

Spécifie un tableau de noms de tables pour lesquelles vous souhaitez configurer le calendrier de synchronisation.

schedule

Spécifie la fréquence de la synchronisation. Vous pouvez spécifier l’une des valeurs JSON suivantes :

• { 'type': 'interval', 'value': '<valeur_intervalle>' }, où interval_value est l’une des valeurs de chaîne suivantes :

  • '30m'

  • '1h'

  • '3h'

  • '6h'

  • '12h'

  • '1d'

• { 'type': 'custom', 'value': { 'hour': <heure>, 'dayOfWeek': '<jour_de_la_semaine>' } }, où hour spécifie l’heure dans le fuseau horaire UTC à laquelle l’ingestion doit commencer, et day_of_week spécifie le jour de la semaine où l’ingestion doit être effectuée. Il est possible d’utiliser des expressions spéciales comme jours de la semaine :

  • '*' pour exécuter l’intégration tous les jours.

  • '1-3' pour exécuter l’intégration du lundi au mercredi.

  • '0,5,6' pour exécuter l’intégration le vendredi, le samedi et le dimanche.

  Les valeurs possibles pouvant être utilisées dans l’expression pour la configuration day_of_week sont :

  • '0' - Dimanche

  • '1' - Lundi

  • '2' - Mardi

  • '3' - Mercredi

  • '4' - Jeudi

  • '5' - Vendredi

  • '6' - Samedi

  Les autres valeurs non numériques telles que '5L' indiquant le dernier vendredi d’un mois ou 'FRI-SUN' indiquant la plage du vendredi au dimanche ne sont pas prises en charge.

Par exemple, pour ingérer les tables table_1 et table_2 chaque samedi et dimanche à 11:00 PM UTC, appelez la procédure stockée suivante :

CALL CONFIGURE_TABLES_SCHEDULE(['table_1', 'table_2'], { 'type': 'custom', 'value': { 'hour': 23, 'dayOfWeek': '0,6' } });

Copy

Par défaut, le connecteur tente de démarrer l’ingestion dans une fenêtre temporelle de trois heures à partir de l’heure de démarrage planifiée. S’il n’est pas possible de démarrer l’ingestion dans ce délai, par exemple lorsque le connecteur ingère d’autres tables, l’exécution planifiée actuelle n’est pas exécutée. Le connecteur tente d’exécuter l’ingestion à la prochaine période planifiée. Il est possible de modifier la durée de la période en appelant la procédure de stockage CONFIGURE_CONNECTOR :

CALL CONFIGURE_CONNECTOR('custom_schedule_start_ingestion_window', <window_length>);

Copy

où window_length est la durée de la fenêtre dans le format de durée ISO 8601. La durée doit être arrondie à une heure entière et doit durer au moins une heure. Par exemple, la valeur 'PT12H' indique une fenêtre qui dure 12 heures, et 'P2D' indique une fenêtre qui dure deux jours.

Si vous n’activez que des tables avec des planifications personnalisées, cette configuration n’affecte que le temps nécessaire à la création et à l’actualisation des vues aplaties pour les tables configurées. Les vues aplaties sont créées lors du premier cycle d’ingestion lorsque les conditions suivantes sont remplies :

• L’ingestion des tables de métadonnées est terminée

• L’ingestion de la table configurée a commencé.

Si les alertes par e-mail sont activées, Snowflake recommande de remplacer la fréquence des alertes par Once per day lors de l’utilisation de la planification personnalisée.

En outre, le connecteur expose la procédure stockée CONFIGURE_CONNECTOR_TABLES obsolète avec les arguments suivants :

CALL CONFIGURE_CONNECTOR_TABLES('schedule_interval', '<schedule>', '<table_names>');

Où :

schedule

Spécifie la fréquence de la synchronisation. Vous pouvez spécifier l’une des valeurs de chaîne suivantes :

• '30m'

• '1h'

• '3h'

• '6h'

• '12h'

• '1d'

table_names

Spécifie une liste de noms de tables délimitée par des virgules.

Pour ces tables, la planification que vous spécifiez dans le paramètre schedule remplace le calendrier par défaut que vous avez défini en appelant la procédure stockée CONFIGURE_CONNECTOR('data_ingestion_schedule', 'schedule').

Spécification des heures de début des plages de données¶

Par défaut, le connecteur Snowflake pour ServiceNow synchronise tous les enregistrements des tables ServiceNow correspondantes. Pour les tables comportant des colonnes sys_updated_on ou sys_created_on (désormais appelées colonnes de temps), il est possible de restreindre la plage de données synchronisées en définissant une heure de début de la plage de données, c’est-à-dire une limite inférieure pour la valeur de la colonne de temps correspondante des enregistrements.

Avec une telle configuration, les enregistrements dont la valeur de la colonne d’heure correspondante est antérieure à l”horodatage de début de la plage de données ne sont pas ingérés. La colonne de temps correspondante utilisée par cette procédure est déterminée de la même manière que pour les mises à jour incrémentales.

Pour modifier la valeur de l’heure de début de la plage de données, appelez la procédure stockée CONFIGURE_TABLES_RANGE_START avec les arguments suivants :

CALL CONFIGURE_TABLES_RANGE_START(<table_names>, <range_start>);

Copy

Où :

table_names

Spécifie un tableau de noms de tables pour lesquelles vous souhaitez configurer l’heure de début de la plage de données.

range_start

Horodatage spécifiant l”heure de début de la plage de données au format TIMESTAMP_TZ ou NULL pour annuler la valeur actuelle.

• Si l’ingestion de la table n’a pas encore commencé, la valeur de l’heure de début de la plage de données est prise en compte lors de la première ingestion.

• Si l’ingestion de la table a déjà commencé (par exemple, un rechargement est en cours), la valeur de l’heure de début de la plage de données est ignorée et un (autre) rechargement de la (des) table(s) est nécessaire pour filtrer les enregistrements dont la valeur de la colonne de temps correspondante est trop ancienne.

Il est donc recommandé de définir l’heure de début de la plage de données avant de commencer la première ingestion d’une table (et donc aussi avant de l’activer).

Par exemple, si les tables table1 et table2 ont les colonnes d’heure requises, pour définir l”heure de début de la plage de données à 2022-11-23 07:00:00 UTC pour ces deux tables, exécutez la commande suivante :

CALL CONFIGURE_TABLES_RANGE_START(['table1', 'table2'], TO_TIMESTAMP_TZ('2022-11-23 07:00:00 +00:00'));

Copy

Ensuite :

• Pour la table table1, par exemple, si son ingestion n’a pas encore été lancée, tous les enregistrements dont la valeur de la colonne de temps est antérieure à 2022-11-23 07:00:00 ne sont pas ingérés.

• Pour la table table2, par exemple, si son ingestion a déjà commencé, la valeur de l”heure de début de la plage de données est ignorée dans toutes les synchronisations de données jusqu’au rechargement de cette table. Lors du rechargement, tous les enregistrements dont la valeur de la colonne de temps est antérieure à 2022-11-23 07:00:00 ne sont pas ingérés.

Il est également possible de désactiver l”heure de début de la plage de données. Par exemple, pour la désactiver pour la table table1, exécutez la commande suivante :

CALL CONFIGURE_TABLES_RANGE_START(['table1'], NULL);

Copy

Là encore, si une ingestion de la table table1 a déjà été lancée, le rechargement de cette table est nécessaire pour ingérer tous les enregistrements provenant de ServiceNow.

Activation ou désactivation de la synchronisation d’une table¶

Pour activer la synchronisation des données d’une table spécifique dans ServiceNow, appelez la procédure stockée ENABLE_TABLES avec les arguments suivants :

CALL ENABLE_TABLES(<tables_to_enable>);

Copy

Où :

tables_to_enable

Spécifie un tableau de noms de tables ServiceNow.

Utilisez le nom de la table, et non l’étiquette affichée dans l’UI de ServiceNow. Vous pouvez trouver le nom de la table dans les tables du dictionnaire de données dans ServiceNow. Dans l’UI de ServiceNow , allez à System Definition » Tables. La colonne Name affiche le nom de la table.

Par exemple, pour activer la synchronisation des tables nommées table1, table2, et table3, exécutez la commande suivante :

CALL ENABLE_TABLES(['table1', 'table2', 'table3']);

Copy

Pour désactiver la synchronisation des données d’une table spécifique dans ServiceNow, appelez la procédure stockée DISABLE_TABLES avec les arguments suivants :

CALL DISABLE_TABLES(<tables_to_disable>);

Copy

Où :

tables_to_disable

Spécifie un tableau de noms de tables ServiceNow.

Utilisez le nom de la table, et non l’étiquette affichée dans l’UI de ServiceNow. Vous pouvez trouver le nom de la table dans les tables du dictionnaire de données dans ServiceNow. Dans l’UI de ServiceNow , allez à System Definition » Tables. La colonne Name affiche le nom de la table.

Par exemple, pour désactiver la synchronisation des tables nommées table1 et table2, exécutez la commande suivante :

CALL DISABLE_TABLES(['table1', 'table2']);

Copy

La désactivation de la table arrête sa synchronisation. Lorsque la synchronisation des tables est réactivée, l’ingestion reprend là où elle avait été interrompue.

Le connecteur expose une version obsolète de la procédure ENABLE_TABLES qui prend deux arguments :

CALL ENABLE_TABLES('<tables_to_configure>', <enable>);

Copy

Où :

tables_to_configure

Spécifie une liste de noms de tables ServiceNow délimitée par des virgules.

enable

Spécifie si la synchronisation doit être activée ou désactivée pour ces tables. Spécifiez TRUE pour l’activer ou FALSE pour la désactiver.

Cette procédure est obsolète et sera supprimée dans une prochaine version du connecteur. Nous vous recommandons d’utiliser ENABLE_TABLES et DISABLE_TABLES avec un seul argument.

Les procédures ENABLE_TABLES et DISABLE_TABLES ajoutent les noms de tables spécifiés à la vue ENABLED_TABLES.

Si vous souhaitez ajouter toutes les tables disponibles dans ServiceNow à la vue ENABLED_TABLES, appelez la procédure stockée PREFILL_CONFIG_TABLE.

Pour appeler cette procédure, exécutez la commande suivante :

CALL PREFILL_CONFIG_TABLE();

Cette procédure ajoute toutes les tables ServiceNow à la vue ENABLED_TABLES et désactive l’ingestion des tables par défaut.

Pour activer la synchronisation des tables venant d’être ajoutées :

1. Exécutez les commandes suivantes pour produire une liste délimitée par des virgules des tables de la vue ENABLED_TABLES :

   SELECT LISTAGG(TABLE_NAME, ',') FROM ENABLED_TABLES;
   

   Copy

2. Dans la liste renvoyée par cette commande, supprimez toutes les tables qui ne doivent pas être synchronisées.

3. Appelez la procédure stockée ENABLE_TABLES et transmettez-lui cette liste.

Si de nouvelles tables ont été ajoutées récemment à ServiceNow, vous pouvez identifier les nouvelles tables et les activer pour la synchronisation en utilisant cette même approche (c’est-à-dire en générant la liste des tables, en modifiant la liste et en transmettant la liste à la procédure stockée ENABLE_TABLES).

Activation de la synchronisation d’une table avec filtrage des colonnes¶

Si vous n’avez pas besoin de toutes les colonnes d’une table ServiceNow dans Snowflake, vous pouvez les ignorer. Par exemple, vous pouvez souhaiter ignorer les colonnes si une seule ligne dépasse la taille maximale de 10 MB.

Pour activer l’ingestion de tables avec les colonnes spécifiées, exécutez la commande suivante :

CALL ENABLE_TABLE_WITH_COLUMNS('<table_to_enable>', <include_columns>, <exclude_columns>);

Copy

Où :

table_to_enable

Spécifie un nom de table ServiceNow.

include_columns

Spécifie un tableau de noms de colonnes à ingérer. Si sys_id, sys_created_on, et sys_updated_on existent, ils sont toujours inclus, même s’ils ne sont pas mentionnés dans ce tableau.

exclude_columns

Spécifie un tableau de noms de colonnes à exclure de l’ingestion. Vous ne pouvez pas exclure les colonnes sys_id, sys_created_on, ou sys_updated_on car le connecteur les utilise dans le processus d’ingestion.

Par exemple, avoir une table ServiceNow nommée u_table avec les colonnes sys_id, sys_updated_on, col_1 et col_2 et exécuter :

CALL ENABLE_TABLE_WITH_COLUMNS('u_table', ['sys_id', 'sys_updated_on'], []);

Copy

n’ingérera que les colonnes sys_id et sys_updated_on pour la table donnée, mais l’appel à :

CALL ENABLE_TABLE_WITH_COLUMNS('u_table', [], ['col_1']);

Copy

ingérera sys_id, sys_updated_on et aussi col_2.

Le connecteur valide les colonnes fournies et rejette la demande d’activation si l’une des colonnes n’est pas disponible sur ServiceNow. Comme l’API ServiceNow ne prend en charge que le mode inclusion, le connecteur transforme les tableaux de colonnes fournis en liste de colonnes incluses et les envoie avec chaque requête à ServiceNow. L’URL avec les colonnes incluses peut être trop longue pour être traitée par ServiceNow. Le connecteur valide cette limitation lorsque ENABLE_TABLE_WITH_COLUMNS est invoqué.

La configuration des colonnes incluses pour chaque table se trouve dans la colonne INCLUDED_COLUMNS de la vue ENABLED_TABLES. Pour modifier la liste des colonnes ingérées, vous devez d’abord désactiver la table concernée. Si le filtrage des colonnes est configuré pour une table, vous pouvez activer les colonnes uniquement à l’aide de la procédure ENABLE_TABLE_WITH_COLUMNS. Vous ne pouvez pas utiliser ENABLE_TABLES dans ce cas.

Le changement de configuration n’affecte pas les données déjà ingérées. Le filtrage des colonnes ne s’applique qu’aux enregistrements nouvellement ingérés.

Les vues aplaties ne comprennent que les colonnes spécifiées lors de l’activation de la table. Elles sont mises à jour chaque fois que la liste des colonnes incluses est modifiée. Si aucun filtrage des colonnes n’est configuré, une vue est constituée de toutes les colonnes disponibles.

Rechargement de données dans une table¶

Pour recharger les données d’une table particulière, appelez la procédure stockée RELOAD_TABLE :

CALL RELOAD_TABLE('<table_name>');

Où :

table_name

Spécifie le nom de la table à recharger.

Lorsque vous appelez la procédure stockée RELOAD_TABLE, le connecteur exécute l’exemple suivant :

1. Le connecteur suspend temporairement la table d’origine pour l’ingestion.

   Note

   Pendant que la table est rechargée, vous ne pouvez pas réactiver la table pour l’ingestion.

2. Le connecteur crée une table temporaire distincte pour l’ingestion.

3. Le connecteur ingère les données dans cette nouvelle table temporaire. Cette table est visible dans la vue CONNECTOR_STATS sous la forme d’une table nommée avec un suffixe __tmp.

   Note

   Chaque rechargement prend en compte la valeur de l’heure de début de la plage de données , ce qui peut restreindre les enregistrements ingérés.

4. Une fois les données ingérées, le connecteur remplace les données de la table d’origine par les données de la table temporaire.

5. Le connecteur supprime la table temporaire.

6. Le connecteur réactive la table d’origine pour l’ingestion.

Pendant ce processus, vous pouvez continuer à interroger les données existantes dans la table d’origine. Cependant, les modifications apportées aux données de la table ServiceNow ne seront pas répercutées dans la table Snowflake tant que le processus d’ingestion ne sera pas terminé.

Pour éviter de surcharger votre instance ServiceNow, ne rechargez qu’une seule table à la fois.

Annulation du rechargement de la table¶

Pour annuler le processus de rechargement des données d’une table, utilisez la procédure stockée CANCEL_RELOAD_TABLE comme indiqué dans l’exemple suivant :

CALL CANCEL_RELOAD_TABLE('<table_name>');

Où :

table_name

Spécifie le nom de la table dont vous souhaitez annuler le rechargement.

Lorsque vous annulez le rechargement, le connecteur supprime tous les objets temporaires créés pendant le rechargement. La table est alors disponible pour l’ingestion dans le cadre du programme de synchronisation normal.

Configuration de la taille d’une recherche de page unique pour une table¶

Le connecteur récupère les données d’une table en les divisant en morceaux plus petits appelés pages. Chaque requête d’API vers ServiceNow permet de récupérer une page. En raison des limitations présentes sur les APIs REST Snowflake et ServiceNow, la taille de la réponse provenant de l’API ServiceNow ne peut pas dépasser 10 MB et la réponse devrait être renvoyée en moins d’une minute.

Pour en tenir compte, le connecteur limite le nombre de lignes extraites au cours d’une seule requête API. Cette limite correspond à la taille de la page.

Le connecteur utilise le processus suivant pour déterminer la taille de la page :

1. Initialement, la taille de page par défaut est fixée à 10 000 lignes.

2. Si la demande d’extraction échoue pendant l’ingestion parce que la taille de la réponse est dépassée, la taille de la page est progressivement réduite de 1 000, 100, 10 et 1 jusqu’à ce que la demande aboutisse ou que la taille finale de la page soit définie sur 1.

3. La taille de page obtenue est enregistrée dans l’état du connecteur et cette valeur est utilisée par les demandes suivantes.

La taille de page actuelle d’une table est disponible dans la vue ENABLED_TABLES. Pour connaître la taille de la page, exécutez la commande suivante :

SELECT PAGE_SIZE FROM ENABLED_TABLES WHERE TABLE_NAME = '<table_name>';

Où :

table_name

Spécifie le nom de la table ServiceNow en cours d’ingestion.

Le processus utilisé par le connecteur pour déterminer la taille de la page peut être source d’inefficacité. Ce processus ne fait que réduire la taille de la page. Il n’augmente pas la taille de la page. Cela peut se produire lorsqu’une table comporte une seule ligne importante qui entraîne la définition d’une valeur inférieure pour la taille de la page.

Pour éviter cette situation, vous pouvez définir manuellement la taille de la page en appelant la procédure stockée RESET_PAGE_SIZE comme le montre l’exemple suivant :

CALL RESET_PAGE_SIZE('<table_name>');

Où :

table_name

Spécifie le nom de la table ServiceNow en cours d’ingestion.

Cycle d’ingestion¶

Les cycles d’ingestion pour une table donnée sont déclenchés selon le calendrier configuré. Un cycle télécharge en boucle toutes les lignes pertinentes divisées en pages mentionnées dans le paragraphe précédent à partir de la table source.

Chargement initial et mises à jour

Dès qu’une page de données est récupérée, elle est insérée dans la table correspondante du journal des événements. À ce stade, les modifications récemment récupérées ne sont pas encore disponibles dans la table de synchronisation ou dans les vues aplaties. Lorsque c’est fait, la demande suivante avec des critères mis à jour est émise tant que des données sont renvoyées. Lorsque le cycle d’ingestion est terminé et qu’il n’y a plus de données à récupérer dans la table source, une tâche de fusion asynchrone est déclenchée, qui prend toutes les modifications du journal des événements insérées depuis la dernière fusion et les applique à la table de synchronisation. Une fois terminé, les données sont disponibles sous forme de tables de synchronisation et de vues aplaties.

Tronquer et charger

En mode Tronquer et charger, une table temporaire est créée pour chaque cycle d’ingestion. Chaque page de lignes récupérée est d’abord insérée dans cette table temporaire (cette table existe dans le schéma interne du connecteur et n’est pas accessible aux utilisateurs du connecteur). À ce stade, les modifications récemment récupérées ne sont pas encore disponibles dans la table de synchronisation ou dans les vues aplaties ; elles affichent toujours les données récupérées lors de l’exécution précédente. Lorsque le cycle d’ingestion est terminé et qu’il n’y a plus de données disponibles dans la table source, les données de la table temporaire remplacent les données existantes dans la table de synchronisation. Toutes les lignes extraites sont également ajoutées au journal des événements. À la fin, la table temporaire est supprimée.

Suivi des progrès

Pour vérifier le statut d’un cycle d’ingestion en cours ou passé, vous pouvez effectuer une requête dans la vue CONNECTOR_STATS. Elle est visible dans la colonne STATUS. La valeur DONE n’est attribuée que si les données ont été récupérées avec succès et que toutes les modifications ont été appliquées à la table de synchronisation. Lorsque l’ingestion est en cours ou que la fusion vers la table de synchronisation/le remplacement des lignes dans la table de synchronisation n’est pas encore terminé, le statut est RUNNING.