Installation et configuration du connecteur via des commandes SQL¶

Installation de l”Snowflake Connector for ServiceNow®V2¶

La procédure suivante décrit comment installer le connecteur :

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

2. Dans le menu de navigation, sélectionnez Data Products » Marketplace.

3. Recherchez le Snowflake Connector for ServiceNow®V2, puis sélectionnez la vignette du connecteur.

4. Dans la page Snowflake Connector for ServiceNow®V2, sélectionnez Get.

   Une boîte de dialogue s’affiche pour lancer la partie initiale du processus d’installation.

   Dans la boîte de dialogue, configurez les éléments suivants :

   1. Dans le champ Application name saisissez le nom de la base de données à utiliser comme base de données pour l’instance de connecteur. Cette base de données est créée automatiquement pour vous.

   2. Dans le champ Warehouse used for installation sélectionnez l’entrepôt que vous souhaitez utiliser pour installer le connecteur.

      Note

      Il ne s’agit pas du même entrepôt que celui utilisé par le connecteur pour synchroniser les données depuis ServiceNow®. Dans une étape ultérieure, vous créerez un entrepôt distinct à cette fin.

   3. Sélectionnez Get.

5. Une boîte de dialogue apparaît avec la notification : Installing App After installation, an email will be sent to <e-mail_utilisateur>. Pour poursuivre la configuration à l’aide de SQL, fermez la boîte de dialogue et accédez à Worksheets.

Configuration de OAuth¶

Vous pouvez configurer Snowflake Connector for ServiceNow®V2 afin qu’il utilise OAuth pour s’authentifier auprès de l’instance ServiceNow® :

• Dans ServiceNow, vous devez configurer l’instance pour qu’elle prenne en charge l’utilisation de OAuth avec le flux d’accord de code.

• Dans le Snowflake Connector for ServiceNow®V2 :

  • Le connecteur utilise une intégration de sécurité avec TYPE = API_AUTHENTICATION pour connecter Snowflake à l’instance ServiceNow®.

    L’intégration de sécurité spécifie l’ID de client OAuth ServiceNow, le secret de client et l’URL de point de terminaison pour l’authentification auprès de l’instance ServiceNow®.

  • Le connecteur utilise un objet secret Snowflake pour gérer les informations sensibles, y compris les informations d’authentification.

    Dans le cas de l’utilisation de OAuth pour l’authentification, le connecteur stocke le jeton d’actualisation OAuth ServiceNow®, l’heure d’expiration du jeton d’actualisation et le nom de l’intégration de sécurité dans l’objet secret Snowflake.

Pour configurer le Snowflake Connector for ServiceNow®V2 de sorte à utiliser OAuth, procédez comme suit :

1. Configurez votre instance ServiceNow® de sorte à utiliser OAuth avec le flux d’octroi de code.

   • Si votre instance ServiceNow® utilise déjà le flux d’octroi de code OAuth et si vous souhaitez utiliser cette instance avec Snowflake Connector for ServiceNow®V2, notez l’ID de client, le secret de client et l’URL de point de terminaison qui correspond au jeton OAuth.

     Pour plus d’informations, voir Gérer les jetons OAuth. Après avoir pris note de ces informations, créez une intégration de sécurité à l’étape suivante.

   • Si vous souhaitez utiliser une instance ServiceNow® différente, accédez à l’instance ou créez-la et configurez-la pour qu’elle utilise OAuth avec le flux d’octroi de code comme indiqué dans Configurer OAuth et Créer un point de terminaison pour l’accès des clients à l’instance.

2. Créez un registre d’applications dans ServiceNow® et utilisez-le pour configurer le connecteur.

   1. Connectez-vous à votre instance ServiceNow®, puis sélectionnez Homepage.

   2. Recherchez OAuth, puis sélectionnez Application Registry.

   3. Sélectionnez New, puis sélectionnez Create an OAuth API endpoint for external clients.

      Une page de configuration du registre d’applications s’affiche, comme le montre l’image suivante :

      

   4. Dans ServiceNow, entrez un nom pour le registre d’applications OAuth dans le champ Name.

   5. Si nécessaire, dans ServiceNow, mettez à jour les valeurs des champs Refresh Token Lifespan et Access Token Lifespan.

      • Snowflake recommande de fixer la durée de vie du jeton d’accès à au moins 600 secondes.

      • Pour la durée de vie du jeton d’actualisation, indiquez une valeur de 7776000 (90 jours).

   6. Dans ServiceNow, sélectionnez Submit.

      Le registre d’applications OAuth apparaît dans la liste des registres d’applications.

   7. Dans ServiceNow, sélectionnez le registre d’applications que vous venez de créer.

      Notez que ServiceNow® a généré des valeurs pour les champs Client ID et Client Secret. Vous utiliserez ces valeurs dans la section suivante lors de la création d’une intégration de sécurité.

Création d’objets essentiels¶

CREATE SECURITY INTEGRATION <name>
 TYPE = API_AUTHENTICATION
 AUTH_TYPE = OAUTH2
 OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST
 OAUTH_CLIENT_ID = '<client_id>'
 OAUTH_CLIENT_SECRET = '<client_secret>'
 OAUTH_TOKEN_ENDPOINT = 'https://<my_instance>.service-now.com/oauth_token.do'
 ENABLED = TRUE;

USE ROLE accountadmin;
CREATE WAREHOUSE servicenow_conn_warehouse WAREHOUSE_SIZE = LARGE;

SHOW PARAMETERS LIKE 'STATEMENT_TIMEOUT_IN_SECONDS' FOR ACCOUNT;
SHOW PARAMETERS LIKE 'STATEMENT_TIMEOUT_IN_SECONDS' FOR WAREHOUSE <connector_warehouse>;

ALTER ACCOUNT SET STATEMENT_TIMEOUT_IN_SECONDS = 10800;
ALTER WAREHOUSE <connector_warehouse> SET STATEMENT_TIMEOUT_IN_SECONDS = 10800;

USE ROLE accountadmin;
CREATE DATABASE dest_db;
CREATE SCHEMA dest_schema;

CREATE NETWORK RULE <name>
  MODE = 'EGRESS'
  TYPE = 'HOST_PORT'
  VALUE_LIST = ('<servicenow_instance_name>.service-now.com');

USE ROLE secretadmin;
GRANT USAGE ON SECRET secretsdb.apiauth.<secret_name> TO ROLE ACCOUNTADMIN;

CREATE EXTERNAL ACCESS INTEGRATION <integration_name>
  ALLOWED_NETWORK_RULES = (<network_rule_name>)
  ALLOWED_AUTHENTICATION_SECRETS = (<secret_name>)
  ENABLED = TRUE;

Configuration de la journalisation du connecteur¶

Le Snowflake Connector for ServiceNow®V2 utilise des tables d’événements pour stocker les journaux d’erreurs du connecteur. Pour mettre en place une table d’événement, suivez le guide Configuration d’une table d’événements.

Configuration du connecteur installé¶

Pour configurer le connecteur :

1. Créez une base de données pour l’instance de connecteur en utilisant Snowsight. Pour plus d’informations sur la création de la base de données, consultez Installation et configuration du connecteur avec Snowsight.

2. Naviguez jusqu’à la feuille de calcul SQL.

3. Connectez-vous en tant qu’utilisateur ayant le rôle ACCOUNTADMIN. Par exemple :

   USE ROLE ACCOUNTADMIN;
   

   Copy

4. Accordez tous les privilèges requis au connecteur à la base de données qui sert d’instance du connecteur.

   • EXECUTE TASK sur le compte

   • EXECUTE MANAGED TASK sur le compte

   • USAGE sur l’entrepôt que vous avez créé pour le connecteur.

   • USAGE sur la base de données que vous avez créée pour les données ServiceNow®

   • USAGE, CREATE TABLE et CREATE VIEW sur le schéma que vous avez créé pour les données ServiceNow®

   • USAGE sur l’intégration d’accès externe que vous avez créée pour ServiceNow®

   • USAGE sur la base de données que vous avez créée pour le secret

   • USAGE sur le schéma que vous avez créé pour le secret

   • READ sur le secret que vous avez créé

   Par exemple, pour accorder les privilèges suivants au connecteur nommé my_connector_servicenow :

   • EXECUTE TASK sur le compte

   • EXECUTE MANAGED TASK sur le compte

   • USAGE sur l’entrepôt servicenow_conn_warehouse

   • USAGE sur la base de données dest_db

   • USAGE, CREATE TABLE et CREATE VIEW sur le schéma dest_db.dest_schema

   • USAGE sur l’intégration servicenow_external_access_integration

   • USAGE sur la base de données secretsdb

   • USAGE sur le schéma secretsdb.apiauth

   • READ sur le secret secretsdb.apiauth.servicenow_creds_oauth_code secret

   Exécutez les commandes suivantes :

   USE ROLE accountadmin;
   
   GRANT EXECUTE TASK ON ACCOUNT TO APPLICATION my_connector_servicenow;
   GRANT EXECUTE MANAGED TASK ON ACCOUNT TO APPLICATION my_connector_servicenow;
   
   GRANT USAGE ON WAREHOUSE servicenow_conn_warehouse TO APPLICATION my_connector_servicenow;
   
   GRANT USAGE ON DATABASE dest_db TO APPLICATION my_connector_servicenow;
   GRANT USAGE ON SCHEMA dest_db.dest_schema TO APPLICATION my_connector_servicenow;
   GRANT CREATE TABLE ON SCHEMA dest_db.dest_schema TO APPLICATION my_connector_servicenow;
   GRANT CREATE VIEW ON SCHEMA dest_db.dest_schema TO APPLICATION my_connector_servicenow;
   
   GRANT USAGE ON INTEGRATION servicenow_external_access_integration TO APPLICATION my_connector_servicenow;
   
   GRANT USAGE ON DATABASE secretsdb TO APPLICATION my_connector_servicenow;
   GRANT USAGE ON SCHEMA secretsdb.apiauth TO APPLICATION my_connector_servicenow;
   GRANT READ ON SECRET secretsdb.apiauth.servicenow_creds_oauth_code TO APPLICATION my_connector_servicenow;
   

   Copy

5. Transférer la possession des tables et des vues dans le schéma de destination (facultatif)

   Si le connecteur a été réinstallé et que le schéma de destination précédent est réutilisé, la possession de toutes les tables et vues du schéma de destination doit être transférée au connecteur. Le connecteur nécessite un privilège de possession pour gérer les droits sur les objets du schéma et pour recréer les vues aplaties lorsque le schéma de la table ingérée est modifié.

   Pour transférer la possession, appelez la fonction SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION.

   USE ROLE accountadmin;
   CALL SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION(<connector_app>, true, <destination_database>, <destination_schema>);
   

   Copy

   SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION est une fonction système fournie par Snowflake qui permet de transférer à l’application la possession des tables et des vues d’une base de données ou d’un schéma spécifié. Seule la possession des tables et des vues normales est transférée, c’est-à-dire que les tables dynamiques, les tables externes, les vues matérialisées, etc., ne changeront pas de propriétaire.

   Cette fonction présente la signature suivante :

   SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION(<to_app>, <should_copy_grants>, <from_database>, <from_schema>)
   

   Copy

   Où :

   to_app

   Spécifie le nom de l’application à laquelle la possession des objets doit être transférée.

   should_copy_grants

   Si TRUE, copiez les droits existants ; sinon, révoquez-les. La copie des droits nécessite l’autorisation MANAGE GRANTS sur l’appelant.

   from_database

   Nom de la base de données contenant les objets qui doivent changer de propriétaire.

   from_schema

   (Facultatif) Nom du schéma contenant les objets qui doivent changer de propriétaire. Si aucun schéma n’est spécifié, la possession est transférée sur les tables et les vues de tous les schémas de la base de données fournie. Les objets des schémas gérés sont omis lors du transfert de possession.

   Pour exécuter la fonction, l’appelant doit remplir l’une des conditions suivantes :

   • Disposer de l’autorisation MANAGE GRANTS (par exemple, du rôle ACCOUNTADMIN ou SECURITYADMIN), ou

   • Contenir le rôle de propriétaire de l’instance d’application et le rôle de propriétaire de tous les objets afin de transférer la possession. Les objets sans propriétaire sont omis par la fonction.

   Par exemple, pour transférer la possession, le connecteur qui :

   • A été installé en tant qu’application nommée my_connector_servicenow

   • Utilise le schéma nommé dest_db.dest_schema pour les données ServiceNow® dans Snowflake

   Exécutez la commande suivante :

   USE ROLE accountadmin;
   CALL SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION('my_connector_servicenow', true, 'dest_db', 'dest_schema');
   

   Copy

   Si nécessaire, accordez le rôle d’application DATA_READER au rôle précédemment propriétaire des données afin d’éviter toute perturbation des pipelines existants qui utilisent les données :

   GRANT APPLICATION ROLE <connector_app>.DATA_READER TO ROLE <previous_data_owner_role>;
   

   Copy

   Notez que le rôle d’application DATA_READER n’aura aucun droit sur les tables et les vues du schéma de destination tant que la procédure CONFIGURE_CONNECTOR n’aura pas été exécutée.

6. Exécutez la commande USE DATABASE pour utiliser la base de données pour le connecteur. Par exemple :

   USE DATABASE my_connector_servicenow;
   

   Copy

7. Configurez le connecteur en utilisant la commande CALL pour appeler la procédure stockée nommée CONFIGURE_CONNECTOR :

   CALL CONFIGURE_CONNECTOR({
     'warehouse': '<warehouse_name>',
     'destination_database': '<dest_db>',
     'destination_schema': '<dest_schema>'
   })
   

   Copy

   Où :

   warehouse_name

   Spécifie le nom de l’entrepôt pour le connecteur.

   Le nom de l’entrepôt doit être un identificateur d’objet valide.

   dest_db

   Spécifie le nom de la base de données des données ServiceNow® dans Snowflake (la base de données que vous avez précédemment créée).

   Le nom de la base de données doit être un identificateur d’objet valide.

   dest_schema

   Spécifie le nom du schéma des données ServiceNow® dans Snowflake (le schéma que vous avez précédemment créé).

   Le nom du schéma doit être un identificateur d’objet valide.

   Par exemple, pour configurer le connecteur qui :

   • Utilise l’entrepôt servicenow_conn_warehouse.

   • Utilise le schéma nommé dest_db.dest_schema pour les données ServiceNow® dans Snowflake

   Exécutez la commande suivante :

   CALL CONFIGURE_CONNECTOR({
     'warehouse': 'servicenow_conn_warehouse',
     'destination_database': 'dest_db',
     'destination_schema': 'dest_schema'
   });
   

   Copy

   Si le connecteur a été correctement démarré, cette procédure stockée renvoie la réponse suivante :

   {
     "responseCode": "OK",
     "message": "Connector successfully configured.",
   }
   

   Copy

   Note

   Une fois le connecteur démarré, il n’est pas possible de renommer l’entrepôt, la base de données de destination ni le schéma de destination transmis pour le connecteur. Le connecteur les référence par leur nom. Par conséquent, toute tentative de suppression ou de modification du nom de ces objets coupe le connecteur et l’empêche de fonctionner.

   Au lieu de renommer l’entrepôt, utilisez la procédure stockée UPDATE_WAREHOUSE pour modifier l’entrepôt utilisé par le connecteur.

8. Configurez la connexion à l’instance ServiceNow® en utilisant la commande CALL pour appeler la procédure stockée nommée SET_CONNECTION_CONFIGURATION :

   CALL SET_CONNECTION_CONFIGURATION({
     'service_now_url': '<servicenow_base_url>',
     'secret': '<secret_name>',
     'external_access_integration': '<external_access_integration_name>'
   })
   

   Copy

   Où :

   servicenow_base_url

   Spécifie l’URL de l’instance ServiceNow® que le connecteur doit utiliser. L’URL doit avoir le format suivant :

   https://<servicenow_instance_name>.service-now.com
   

   Copy

   secret_name

   Spécifie le nom complet de l’objet secret contenant les identifiants de connexion pour s’authentifier auprès de ServiceNow® (le secret que vous avez précédemment créé).

   Vous devez spécifier le nom complet de l’objet secret au format suivant :

   <database_name>.<schema_name>.<secret_name>
   

   Copy

   Les noms de la base de données, du schéma et du secret doivent être des identificateurs d’objets valides.

   external_access_integration_name

   Spécifie le nom de l”intégration d’accès externe pour ServiceNow® (l’intégration d’accès externe que vous avez précédemment créée).

   Le nom de l’intégration doit être un identificateur d’objet valide.

   Par exemple, pour configurer la connexion à une instance ServiceNow® qui :

   • Possède l’URL https://myinstance.service-now.com.

   • Utilise le secret stocké dans secretsdb.apiauth.servicenow_creds_oauth_code.

   • Utilise l’intégration d’accès externe nommée servicenow_external_access_integration.

   Exécutez la commande suivante :

   CALL SET_CONNECTION_CONFIGURATION({
     'service_now_url': 'https://myinstance.service-now.com',
     'secret': 'SECRETSDB.APIAUTH.SERVICENOW_CREDS_OAUTH_CODE',
     'external_access_integration': 'SERVICENOW_API_INTEGRATION'
   });
   

   Copy

   Si la connexion a été correctement configurée, cette procédure stockée renvoie la réponse suivante :

   {
     "responseCode": "OK",
     "message": "Test request to ServiceNow® succeeded.",
   }
   

   Copy

   Note

   Une fois le connecteur configuré, il n’est pas possible de modifier le nom du secret ni de l’intégration d’accès externe transmis. Le connecteur les référence par leur nom. Par conséquent, toute tentative de suppression ou de modification du nom de ces objets coupe le connecteur et l’empêche de fonctionner.

9. Finalisez la configuration du connecteur en utilisant la commande CALL pour appeler la procédure stockée nommée FINALIZE_CONNECTOR_CONFIGURATION :

   CALL FINALIZE_CONNECTOR_CONFIGURATION({
     'journal_table': '<name_of_journal_table>',
     'table_name': '<name_of_audited_table>',
     'sys_id': '<sys_id_of_audited_entry>'
   })
   

   Copy

   Où :

   name_of_journal_table

   Spécifie le nom de la table qui contient des informations sur les enregistrements supprimés. Reportez-vous à Préparation de votre instance ServiceNow® pour plus d’informations.

   Notez que les informations sur les enregistrements supprimés ne sont disponibles que pour les tables que vous avez configurées pour propager les enregistrements supprimés.

   Pour empêcher la propagation des enregistrements supprimés, spécifiez null pour cet argument.

   name_of_audited_table

   (facultatif) Spécifie le nom de la table auditée qui doit être présente dans la table de journal et à laquelle le connecteur doit avoir accès. Lors de la validation de l’accès à la table de journal, le connecteur recherche les entrées d’audit liées à cette table. Fournissez cette option lorsqu’une requête auprès de ServiceNow® aboutit, mais ne donne aucun résultat, faisant échouer la procédure. Assurez-vous que l’utilisateur ServiceNow® du connecteur a accès à toutes les entrées de la table spécifiée.

   Cette option ne peut pas être utilisée avec le paramètre sys_id.

   sys_id_of_audited_entry

   (facultatif) Spécifie la valeur sys_id de l’entrée d’une table auditée qui doit être présente dans la table de journal et à laquelle le connecteur doit avoir accès. Lors de la validation de l’accès à la table de journal, le connecteur recherche les entrées d’audit liées à cette valeur sys_id. Fournissez cette option lorsqu’une requête auprès de ServiceNow® aboutit, mais ne donne aucun résultat, faisant échouer la procédure. Assurez-vous que l’utilisateur ServiceNow® du connecteur a accès à l’entrée spécifiée.

   Cette option ne peut pas être utilisée avec le paramètre table_name.

   Si le connecteur a été correctement démarré, cette procédure stockée renvoie la réponse suivante :

   {
       "responseCode": "OK",
   }
   

   Copy

   Lors de la finalisation de la configuration du connecteur, ce dernier tentera de vérifier si un état de connecteur précédemment exporté est présent dans le schéma de destination. Si la table __CONNECTOR_STATE_EXPORT est présente et accessible par le connecteur, ce dernier tentera d’importer l’état. Lorsque l’importation se termine correctement, la table d’exportation est supprimée. Si une erreur se produit lors de l’importation, il est possible de réexécuter la procédure FINALIZE_CONNECTOR_CONFIGURATION après avoir corrigé l’erreur. Si vous ne souhaitez pas importer l’état ou si vous ne voulez pas corriger l’erreur d’importation, transférez la possession de la table depuis le connecteur et supprimez la table.

La base de données nouvellement créée est une instance du connecteur et contient les éléments suivants :

• Procédures stockées que vous utilisez pour configurer le connecteur. Pour plus d’informations, voir Configuration de l’ingestion de données à l’aide d’instructions SQL.

• Vues contenant les messages enregistrés et les statistiques pour le connecteur. Pour plus d’informations, voir À propos de la surveillance du connecteur.

Rôles d’application du connecteur¶

En tant qu’application native, Snowflake Connector for ServiceNow®V2 définit des rôles d’application. Ils peuvent être consultés à la section Contrôle d’accès basé sur les rôles des connecteurs.

Prochaines étapes¶

Après avoir installé et configuré le connecteur, effectuez les étapes décrites dans Configuration de l’ingestion de données pour vos données ServiceNow®.