使用 SQL 命令安装和配置连接器¶

安装 Snowflake Connector for ServiceNow®V2¶

以下过程描述了如何安装连接器：

1. 以具有 ACCOUNTADMIN 角色的用户身份登录 Snowsight。

2. 在导航菜单中，选择 Data Products » Marketplace。

3. 搜索 Snowflake Connector for ServiceNow®V2，然后选择连接器的磁贴。

4. 在 Snowflake Connector for ServiceNow®V2 页面中，选择 Get。

   这将显示一个对话框，您可以使用该对话框开始安装过程的初始部分。

   在对话框中配置以下内容：

   1. 在 Database name 字段中，输入要用作连接器实例的数据库的数据库名称。该数据库是自动为您创建的。

   2. 在 Warehouse used for installation 字段中，选择要用于安装连接器的仓库。

      备注

      这与连接器用于同步来自 ServiceNow® 的数据的仓库不同。在后续步骤中，您将为此目的创建一个单独的仓库。

   3. 选择 Get。

5. 此时将显示一个通知对话框：Installing App After installation, an email will be sent to <user_email>。要继续使用 SQL 进行配置，请关闭对话框并转到 Worksheets。

设置 OAuth¶

您可以配置 Snowflake Connector for ServiceNow®V2 以使用 OAuth 来对 ServiceNow 实例进行身份验证：

• 在 ServiceNow 中，您必须将实例设置为支持与 `代码许可流程`_搭配使用 OAuth。

• 在 Snowflake Connector for ServiceNow®V2 中：

  • 该连接器使用 TYPE = API_AUTHENTICATION 安全集成将 Snowflake 连接到 ServiceNow® 实例。

    安全集成会指定 ServiceNow® OAuth 客户端 ID、客户端密钥以及端点 URL，以用于对 ServiceNow® 实例进行身份验证。

  • 该连接器使用 Snowflake 密钥对象来管理敏感信息，包括身份验证凭据。

    在使用 OAuth 进行身份验证的情况下，该连接器会将 ServiceNow® OAuth 刷新令牌、刷新令牌过期时间以及安全集成的名称存储在 Snowflake 密钥对象中。

要设置 Snowflake Connector for ServiceNow®V2 以使用 OAuth，请按照以下步骤操作：

1. 将 ServiceNow® 实例配置为将 OAuth 与代码许可授权一起使用。

   • 如果 ServiceNow® 实例已使用 OAuth 代码授权流程，并且您希望将该实例与 Snowflake Connector for ServiceNow®V2 一起使用，请记下与 OAuth 令牌对应的客户端 ID、客户端密钥和端点 URL。

     有关更多信息，请参阅 管理 OAuth 令牌 (https://docs.servicenow.com/bundle/washingtondc-platform-security/page/administer/security/task/t_ManageTokens.html)。记下此信息后，在下一步中创建安全集成。

   • 如果您要使用其他 ServiceNow® 实例，请访问或创建实例，并将实例配置为使用 OAuth 与代码授权流程，如 设置 OAuth 和 创建端点供客户端访问实例 (https://docs.servicenow.com/bundle/washingtondc-platform-security/page/administer/security/task/t_CreateEndpointforExternalClients.html) 中所示。

2. 在 ServiceNow® 中创建一个应用程序注册表，并使用它来配置连接器。

   1. 登录到 ServiceNow® 实例，然后选择 Homepage。

   2. 搜索 OAuth，然后选择 Application Registry。

   3. 依次选择 New、Create an OAuth API endpoint for external clients。

      系统会显示应用程序注册表的配置页，如下图所示：

      

   4. 在 ServiceNow 中的字段 Name 中，输入 OAuth 应用程序注册表的名称。

   5. 如果需要，请在 ServiceNow 中更新字段 Refresh Token Lifespan 和 Access Token Lifespan 的值。

      • Snowflake 建议将访问令牌的有效期设置为至少 600 秒。

      • 对于刷新令牌的有效期，请指定值为 7776000（90 天）。

   6. 在 ServiceNow 中，选择 Submit。

      OAuth 应用程序注册表显示在应用程序注册表列表中。

   7. 在 ServiceNow 中，选择您刚刚创建的应用程序注册表。

      请注意，ServiceNow® 已为 Client ID 和 Client Secret 字段生成值。在下一节中，您可以在 创建安全集成 时使用这些值。

创建基本对象¶

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;

为连接器配置日志记录¶

Snowflake Connector for ServiceNow®V2 使用事件表来存储连接器的错误日志。要设置事件表，请遵循 设置事件表 指南。

设置已安装的连接器¶

要设置连接器，请执行以下操作：

1. 使用 Snowsight 为连接器实例创建数据库。有关如何创建数据库的详细信息，请参阅 使用 Snowsight 安装和配置连接器。

2. 导航到 SQL 工作表。

3. 以具有 ACCOUNTADMIN 角色的用户身份登录。例如：

   USE ROLE ACCOUNTADMIN;
   

   Copy

4. 向 用作连接器实例的数据库 授予连接器所需的全部权限。

   • 账户的 EXECUTE TASK 权限

   • 账户的 EXECUTE MANAGED TASK 权限

   • 对 为连接器创建的仓库 的 USAGE 权限。

   • 对 为 ServiceNow® 数据创建的数据库 的 USAGE 权限

   • 对 为 ServiceNow® 数据创建的架构 的 USAGE、CREATE TABLE 和 CREATE VIEW 权限

   • 对 为 ServiceNow® 创建的外部访问集成 的 USAGE 权限

   • 为密钥创建的数据库的 USAGE 权限

   • 为密钥创建的架构的 USAGE 权限

   • :ref:`创建的密钥的 <label-servicenow_connector_prereqs_secret_create_v2>`的 READ 权限

   例如，向名为 my_connector_servicenow 的连接器授予以下权限：

   • 账户的 EXECUTE TASK 权限

   • 账户的 EXECUTE MANAGED TASK 权限

   • 仓库 servicenow_conn_warehouse 的 USAGE 权限

   • dest_db 数据库的 USAGE 权限

   • 架构 dest_db.dest_schema 的 USAGE、CREATE TABLE 和 CREATE VIEW 权限

   • 集成 servicenow_external_access_integration 的 USAGE 权限

   • secretsdb 数据库的 USAGE 权限

   • 架构 secretsdb.apiauth 的 USAGE 权限

   • 密钥 secretsdb.apiauth.servicenow_creds_oauth_code secret 的 READ 权限

   请运行以下命令：

   USE ROLE accountadmin;
   
   GRANT EXECUTE 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. 在目标架构中转移表和视图的所有权（可选）

   如果重新安装了连接器，并且重复使用了以前的目标架构，则必须将目标架构中所有表和视图的所有权转移到连接器。连接器需要所有权权限才能管理对架构中对象的授权，并在引入表的架构发生更改时重新创建扁平化视图。

   要转让所有权，请调用 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 是 Snowflake 提供的一种系统函数，它允许将指定数据库或架构中的表和视图的所有权转移给应用程序。只会转移常规表和常规视图的所有权，例如不会转移动态表、外部表、物化视图等的所有权。

   该函数具有以下签名：

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

   Copy

   其中：

   to_app

   指定应向其转移对象所有权的应用程序的名称。

   should_copy_grants

   如果为 TRUE，则复制现有授权，否则撤销。复制授权要求调用方具有 MANAGE GRANTS 权限。

   from_database

   包含应更改其所有权的对象的数据库的名称。

   from_schema

   （可选）包含应更改其所有权的对象的架构的名称。如未指定架构，则在所提供的数据库中的所有架构中的表和视图上转移所有权。托管架构中的对象在所有权转移期间会被省略。

   要执行该函数，调用方须满足以下条件之一：

   • 它具有 MANAGE GRANTS 权限（例如 ACCOUNTADMIN 或 SECURITYADMIN 角色），或者

   • 它包含拥有应用程序实例的角色和拥有所有对象的角色，以便转移所有权。缺少所有权的对象将被函数省略。

   例如，转移以下连接器的所有权时：

   • 作为名为 my_connector_servicenow 的应用程序安装

   • 对 Snowflake 中的 ServiceNow 数据使用名为 dest_db.dest_schema 的架构

   运行以下命令：

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

   Copy

   如果需要，请将 DATA_READER 应用程序角色授予先前拥有数据的角色，以使用数据防止现有管道中断：

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

   Copy

   请注意，在 CONFIGURE_CONNECTOR 过程运行之前，DATA_READER 应用程序角色在目标架构中的表和视图上不会获得任何授权。

6. 运行命令 USE DATABASE 以将数据库用于连接器。例如：

   USE DATABASE my_connector_servicenow;
   

   Copy

7. 通过使用 CALL 命令调用名为 CONFIGURE_CONNECTOR 的存储过程来配置连接器：

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

   Copy

   其中：

   warehouse_name

   指定连接器的仓库名称。

   仓库的名称必须是有效的 对象标识符。

   dest_db

   为 Snowflake 中的 ServiceNow® 数据指定数据库（您之前创建的数据库） 的名称。

   数据库的名称必须是有效的 对象标识符。

   dest_schema

   为 Snowflake 中的 ServiceNow® 数据指定架构（您之前创建的架构） 的名称。

   架构的名称必须是有效的 对象标识符。

   例如，要配置连接器，请执行以下步骤：

   • 使用仓库 servicenow_conn_warehouse。

   • 对 Snowflake 中的 ServiceNow 数据使用名为 dest_db.dest_schema 的架构

   运行以下命令：

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

   Copy

   如果连接器已成功启动，则此存储过程会返回以下响应：

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

   Copy

   备注

   启动连接器后，将无法为连接器重命名已传递的仓库、目标数据库和目标架构。因为连接器通过名称来引用它们。因此，如果尝试删除或修改这些对象的名称，将会导致连接器失效并停止正常工作。

   请使用 UPDATE_WAREHOUSE 存储过程来更改连接器使用的仓库，而不是重命名仓库。

8. 使用 CALL 命令配置与 ServiceNow® 实例的连接，以调用名为 SET_CONNECTION_CONFIGURATION 的存储过程：

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

   Copy

   其中：

   servicenow_base_url

   指定连接器应使用的 ServiceNow® 实例的 URL。URL 应采用以下格式：

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

   Copy

   secret_name

   指定包含 ServiceNow® 身份验证凭据的 密钥（您之前创建的密钥）对象 的完全限定名称。

   您必须按以下格式指定密钥对象的完称：

   <database_name>.<schema_name>.<secret_name>
   

   Copy

   数据库、架构和密钥的名称必须是有效的 对象标识符。

   external_access_integration_name

   指定 ServiceNow® 的外部访问集成（您之前创建的外部访问集成） 的名称。

   集成的名称必须是有效的 对象标识符。

   例如，要配置与 ServiceNow® 实例的连接，请执行以下操作：

   • 包含 URL https://myinstance.service-now.com。

   • 使用存储在 secretsdb.apiauth.servicenow_creds_oauth_code 中的密钥。

   • 使用名为 servicenow_external_access_integration 的外部访问集成。

   运行以下命令：

   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

   如果连接配置成功，则此存储过程将返回以下响应：

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

   Copy

   备注

   配置连接后，将无法更改已传递的密钥和外部访问集成的名称。因为连接器通过名称来引用它们。因此，如果尝试删除或修改这些对象的名称，将会导致连接器失效并停止正常工作。

9. 使用 CALL 命令完成连接器的配置，以调用名为 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

   其中：

   name_of_journal_table

   指定包含有关已删除记录信息的表的名称。有关更多信息，请参阅 准备 ServiceNow® 实例。

   请注意，有关已删除记录的信息仅适用于那些设置为传播删除操作的表。

   要阻止传播已删除记录，请为此实参指定 null。

   name_of_audited_table

   （可选）指定应存在于日志表中并且连接器应有权访问的已审计表的名称。在对日志表的访问权限进行验证期间，连接器将查找与该表相关的审计条目。在对 ServiceNow® 的查询成功，但未给出任何结果，并导致过程失败时提供此选项。确保连接器的 ServiceNow® 用户有权访问指定表的所有条目。

   此选项不能与 sys_id 参数一起使用。

   sys_id_of_audited_entry

   （可选）指定来自某个已审计表（该表应存在于日志表中，并且连接器应有权访问该表）的条目的 sys_id。在对日志表的访问权限进行验证期间，连接器将查找与此 sys_id 相关的审计条目。在对 ServiceNow® 的查询成功，但未给出任何结果，并导致过程失败时提供此选项。确保连接器的 ServiceNow® 用户有权访问指定的条目。

   此选项不能与 table_name 参数一起使用。

   如果连接器已成功启动，则此存储过程会返回以下响应：

   {
       "responseCode": "OK",
   }
   

   Copy

   在完成连接器配置期间，连接器将尝试检查目标架构中是否存在之前导出的连接器状态。如果 __CONNECTOR_STATE_EXPORT 表存在且可供连接器访问，则该连接器将尝试导入状态。成功完成导入后，导出表将被删除。如果在导入过程中发生错误，则可在修复错误后再次运行 FINALIZE_CONNECTOR_CONFIGURATION 过程。如果不想导入状态或不想修复导入错误，请从连接器转移表的所有权并删除该表。

新创建的数据库是连接器实例，包含以下内容：

• 用于配置连接器的存储过程。有关更多信息，请参阅 使用 SQL 语句设置数据引入。

• 包含连接器记录的消息和统计信息的视图。有关更多信息，请参阅 关于监控连接器。

连接器应用程序角色¶

作为原生应用程序，Snowflake Connector for ServiceNow®V2 会定义 应用程序角色。可在 连接器基于角色的访问控制 中查看它们。

后续步骤¶

安装并配置连接器后，执行“ 为 ServiceNow® 数据设置数据引入”中描述的步骤。