Snowflake Connector for ServiceNow®V2 迁移指南¶

弃用通知¶

Snowflake Connector for ServiceNow®V2 已正式推出，因此，此处称为 V1 的 Snowflake Connector for ServiceNow® 现已弃用。如果您希望保留连接器的状态和配置，则必须在 2024 年 6 月 23 日 当天或之前完成迁移。在此日期之后，连接器的先前版本将无法使用，并且将无法再导出数据。

版本说明¶

请参阅 版本说明，了解新版本中有哪些变化。

根本变化¶

在连接器的先前版本和当前版本之间，进行了以下更改：

• 对 Native Apps V1 框架重新架构，得到 Native Apps V2。

• 连接器现在会自动更新，因此 RUN_UPGRADE 过程已移除。

• 引入的数据（包括扁平化视图）不再归数据所有者角色所有，而是归应用程序所有。从现在开始，默认情况下，您将可以通过 DATA_READER 应用程序角色访问 SELECT 权限。如果数据管道需要额外的权限，则需要在执行迁移 之前 将这些权限明确授予数据所有者角色。

• 连接器数据库共享的许多视图和过程的签名已更改。请在迁移前查看。如果您在自定义脚本或数据管道中使用了这些签名，请确保对其进行调整。

• 现在，所有公共程序都以结构化 JSON 格式返回数据。

• 删除了无服务器支持。必须始终提供虚拟仓库。

• 改进了 API 调用 ServiceNow® 的性能：

  • 连接器现在支持引入大型表。以前，整个响应的大小限制为 16 MB。现在为每行 16 MB。

  • 连接器重试机制更加准确，这使其能够确定正确的页面大小，以便更快地引入给定表。

• 查看新连接器版本的 已知限制 部分。特别是以下变更：

  • 连接器不支持 MANAGED ACCESS 目标架构。

  • 无法通过用户创建的任务执行某些过程。

当前版本的连接器还包括几项新功能：

• 全新 UI 体验和安装流程。

• 由于新的应用程序角色机制为用户提供了对 ADMIN、VIEWER 和 DATA_READER 角色的访问权限，因此可管理性有所提升。

• 连接器的状态和配置现在会定期保存在 __EXPORT_CONNECTOR_STATE 表中。

• 从工作表安装时，连接器支持 ServiceNow® 实例的虚拟 URLs。

升级您当前的连接器实例¶

我们要求连接器用户版本为 4.21.0 或更高版本。要查看应用程序版本，请打开 Snowsight，创建 SQL 工作表，然后在连接器数据库的上下文中，运行：

CALL <connector_v1_app>.PUBLIC.GET_VERSION();

如果版本是 4.21.0 或更高版本，则可以跳过此步骤。否则，请运行：

CALL <connector_v1_app>.PUBLIC.RUN_UPGRADE();

导出数据¶

此过程会在目标架构中创建一个具有导出状态的新 __CONNECTOR_STATE_EXPORT 表。要执行导出，必须满足以下条件：

• 连接器必须停止。

• 没有正在进行的表重新加载。

• 目标架构中不得存在 __CONNECTOR_STATE_EXPORT 表。如果存在，则必须在执行导出之前，删除或重命名该表。

1. 通过执行以下命令来确定正在运行哪些表重新加载：

   SELECT * FROM ENABLED_TABLES WHERE RELOADING = TRUE;
   

   Copy

   此命令可识别所有处于重新加载状态的表。您可以选择是等到重新加载完成还是通过运行以下命令取消重新加载：

   CALL CANCEL_RELOAD('<table_name>');
   

   Copy

   备注

   如果必要，您将需要在新版本中重新安装连接器后，再次重新加载表。不导出有关表重新加载的数据。

2. 运行以下命令以停止连接器：

   CALL STOP_CONNECTOR();
   

   Copy

   只能在连接器停止时导出连接器状态和配置。请勿之后恢复连接器，因为这样可以确保不会有两个连接器同时运行，尤其是在新安装中要重复使用目标数据库和架构的情况下。停止连接器将保护您免受因运行两个连接器而导致的访问失败和额外费用的影响。

3. 导出连接器的数据。可以通过以下过程导出数据：

   CALL EXPORT_CONNECTOR_STATE();
   

   Copy

   配置导出后，将不再更新。每次更改配置后或重新安装连接器之前，我们建议删除 __CONNECTOR_STATE_EXPORT 表并重新导出状态。

此时，包含连接器状态和配置的 __CONNECTOR_STATE_EXPORT 表应显示在目标架构中。

安装 Snowflake Connector for ServiceNow®V2¶

本节重点在于提供之前安装连接器时使用的配置值。

有关更多信息，请参阅 Snowflake Connector for ServiceNow®V2 文档中的 使用 Snowsight 安装和配置连接器。

1. 确保当前安装的连接器 V1 实例已停止。

2. （可选）保存后续步骤中需要的当前使用的配置值（不导出）。要检索

   • 连接器配置值（日志表、数据所有者角色、仓库、目标数据库、目标架构、ServiceNow® 实例），请运行：

     SELECT * FROM GLOBAL_CONFIG WHERE KEY IN ('journal_table_name', 'data_owner_role', 'warehouse_name', 'destination_db_and_schema', 'connection_config');
     

     Copy

   • 用于配置连接器的 ServiceNow® 用户名，请运行：

     SELECT value:secret FROM GLOBAL_CONFIG WHERE KEY = 'connection_config';
     DESCRIBE SECRET <secret_value>;
     

     Copy

     备注

     Snowflake 从不返回 PASSWORD 属性值。

3. 在导航菜单中，选择 Data Products » Marketplace 并搜索“Snowflake Connector for ServiceNow®V2”。确保找到的列表是 :ui:`GZSTZTP0KL1`（可以在 URL 中查看此值）。

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

   此时将显示 Installation 对话框，您可以开始安装过程。

   在 Options 可折叠项下，配置以下内容：

   • Application name – 更改连接器的默认名称。

     备注

     新连接器的名称必须不同于与之前的名称。如果您之前使用的是连接器名称的默认值 SNOWFLAKE_CONNECTOR_FOR_SERVICENOW，则必须为新连接器指定不同的名称。记得调整自定义脚本或数据管道中的值。

   • Warehouse used for installation – 选择要用于安装连接器的仓库。

     备注

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

   1. 选择 Get。

Installing App 对话框将会显示，安装完成后，标题会更改为 Successfully Installed。

要继续配置，请选择 Configure。

完成后，对话框会关闭，并且 Snowflake Connector for ServiceNow®V2 页面显示用于配置和管理连接器的 UI。

备注

您可以提前关闭安装对话框，并之后在安装过程完成后再返回。此外，系统还将发送一封电子邮件，通知您安装状态。

1. 连接器配置

   1. 配置

      在 Configure 对话框中，指定以下内容：

      • 对于 Warehouse、Destination Database 和 Destination Schema，使用 Select existing 选项，并提供与连接器的先前版本使用的值完全相同的值。

      • 对于 Role，选择在连接器 V1 中用作数据所有者角色的现有角色。此角色将被授予 DATA_READER 应用程序角色。

        备注

        如果您依赖数据管道中的其他角色，则可以：

        • 将数据管道切换为依赖此单一角色，该角色将用作 :ui:`DATA_READER`（推荐）；

        • 手动向这些附加角色授予 DATA_READER 应用程序角色。查看如何 授予应用程序角色。

      选择 Configure。

   2. 身份验证

      以下过程描述如何设置与 ServiceNow 的连接。您可以选择基本身份验证（用户名和密码）或 OAuth。

      1. 选择之前选择的方法：Basic authentication 或 OAuth2。

      2. 基本身份验证流程

         1. 对于 ServiceNow Instance、ServiceNow Username 和 ServiceNow Password 字段，提供与之前所用完全相同的值。

         2. 选择 Connect。

      3. OAuth 流

         1. 对于 ServiceNow Instance 字段，输入与之前所用相同的值。

            这是 ServiceNow® 实例主机名的第一部分。例如，如果指向 ServiceNow® 实例的 URL 为：

            https://myinstance.service-now.com
            

            Copy

            实例的名称将是 myinstance。

         2. 重用应用程序注册表：

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

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

            3. 选择以前使用的注册表并将 Client ID 和 Client Secret 的值复制到 Snowflake 中的相应字段。

            4. 选择 Connect。

            5. 此时会出现一个对话框，要求您使用用户名和密码登录到 ServiceNow® 实例。提供您希望连接器进行身份验证的用户的凭据，它需要 准备 ServiceNow® 实例 中列出的权限。

            6. 登录后，确认要允许连接器连接到 ServiceNow® 账户。选择 Allow。

               备注

               如果您在不需要提供凭据的情况下被直接重定向到此对话框，则表示您已经登录到 ServiceNow® 实例。确保使用连接器应使用的用户登录，并且该用户具有必要的权限。

               注意：当前登录的用户显示在对话框的右上角。

   3. 验证来源

      • 在 Journal Table 字段中，输入与之前所用相同的值（前提是已进行配置；如果未配置，则将此字段留空）。

此时，您应该已经成功配置了连接器的新版本，而连接器正在将数据引入到先前指定的目标架构中。连接器使用导出的配置（例如启用了哪些表），并继续根据先前配置的计划引入数据。

要验证导入是否成功，请检查：

• 之前启用的表是否仍处于启用状态，以及连接器是否仍在为该表引入数据（可在 CONFIGURED_TABLES 视图中找到）；

• 其引入计划或页面大小是否正确（例如没有默认值）（可在 CONFIGURED_TABLES 视图中找到）；

• 连接器的默认引入计划或页面大小是否保持不变（可在 CONNECTOR_CONFIGURATION 视图中找到）。

有关可用视图的更多信息，请参阅 关于监控连接器。

卸载 V1 连接器¶

1. （可选）在安装 V1 连接器期间，创建了许多需要手动删除的对象。这些对象是（括号中是通过 Snowsight 安装时的对象名称）：

   • 安全集成 (SERVICENOW_GZSTZTP0KHD_INTEGRATION)；

   • API 集成 (SERVICENOW_GZSTZTP0KHD_API)；

   • 密钥 (CONNECTORS_UI.SERVICENOW_GZSTZTP0KHD.SECRET)。

   要手动查找 API 集成和密钥，您可以从连接器 V1 数据库的上下文中运行以下查询：

   SELECT value:apiIntegrationName, value:secret FROM GLOBAL_CONFIG WHERE key = 'connection_config';
   

   Copy

   完成 卸载 V1 连接器 步骤后，您可以安全删除这些对象。

2. 在导航菜单中，选择 Data » Databases，并找到用于 V1 连接器安装的共享数据库。

   重要

   不要混淆连接器的安装数据库与目标数据库。如果在 V2 安装中重复使用了目标数据库和架构，则 不得 将其删除。

3. 在右上角，选择三点菜单并按 Drop。确认后，已弃用的连接器版本将被移除。

此时将只能安装一个版本的连接器。