为 ServiceNow® 数据设置数据引入¶

使用 Snowsight 修改数据引入¶

要修改要引入的 ServiceNow 表或该表的同步计划，请执行以下操作：

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

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

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

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

5. 修改要引入的表：

   1. 搜索要引入的表。

   2. 在要选择或取消选择的表旁边，选中 Status 列中的复选框。

   3. 在 Synch Schedule 下方，选择要在 Snowflake 和 ServiceNow 之间同步表的频率。

6. 选择 Update。

指定同步计划¶

Snowflake Connector for ServiceNow® 会按指定计划将所有 ServiceNow 表中的数据同步至 Snowflake。默认情况下，所有表每小时 (1h) 同步一次。

若要更改所有表的默认同步计划，请使用以下实参调用 CONFIGURE_CONNECTOR 存储过程：

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

其中：

:samp:`{data_ingestion_schedule}`（字符串的字面量）

指明要配置同步计划。

schedule

指定同步的频率。您可以指定以下字符串值中的一个：

• '30m'

• '1h'

• '3h'

• '6h'

• '12h'

• '1d'

连接器还允许您为启用了同步的表指定不同的计划。若要变更一组选定的表的同步计划，请使用以下实参调用 CONFIGURE_TABLES_SCHEDULE 存储过程：

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

其中：

table_names

指定要配置同步计划的表名称数组。

schedule

指定同步的频率。您可以指定以下 JSON 值中的一个：

• { 'type': 'interval', 'value': '<interval_value>' }，其中 interval_value 为以下字符串值中的一个：

  • '30m'

  • '1h'

  • '3h'

  • '6h'

  • '12h'

  • '1d'

• { 'type': 'custom', 'value': { 'hour': <hour>, 'dayOfWeek': '<day_of_week>' } }，其中使用 hour 来指定应开始引入时的 UTC 时区小时数，并使用 day_of_week 指定应执行引入时是星期几。可以使用特殊表达式来表示是星期几：

  • '*' 表示每天运行引入。

  • '1-3' 表示从星期一到星期三运行引入。

  • '0,5,6' 表示在星期五、星期六和星期日运行引入。

  可用于 day_of_week 配置表达式的可能值为：

  • '0' – 星期日

  • '1' – 星期一

  • '2' – 星期二

  • '3' – 星期三

  • '4' – 星期四

  • '5' – 星期五

  • '6' – 星期六

  不支持其他非数字值，例如使用 '5L' 指示每月的最后一个星期五或使用 'FRI-SUN' 指示从星期五到星期日的范围。

例如，若要在每个星期六和星期日的 11:00 PM (UTC) 引入表 table_1 和 table_2，则调用以下存储过程：

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

Copy

默认情况下，连接器会尝试在计划开始时间起的 3 小时内开始引入。如果无法在该时间范围内开始引入（例如，连接器在引入其他表），则不会执行当前运行计划。连接器会尝试在下一个计划时间范围引入。可以通过调用 CONFIGURE_CONNECTOR 存储过程来更改时间范围的持续时间：

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

Copy

其中，window_length 是 ISO 8601 持续时间格式的时间窗口长度。持续时间必须四舍五入为整小时，并且必须持续至少 1 小时。例如，值 'PT12H' 指定的是持续 12 小时的时间窗口，'P2D' 指定的则是持续 2 天的时间窗口。

如果仅启用使用自定义计划的表，则此配置只会影响为已配置表创建和刷新展平视图所需的时间。满足以下条件后，将在首个引入周期中创建展平视图：

• 已完成元数据表的引入

• 已开始已配置表的引入。

如果启用了电子邮件警报，Snowflake 建议在使用自定义计划时将警报频率更改为 Once per day。

此外，连接器会使用以下实参公开已弃用的 CONFIGURE_CONNECTOR_TABLES 存储过程：

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

其中：

schedule

指定同步的频率。您可以指定以下字符串值中的一个：

• '30m'

• '1h'

• '3h'

• '6h'

• '12h'

• '1d'

table_names

指定以逗号分隔的表名列表。

对于这些表，您在参数中 schedule 中指定的计划将替换通过调用 CONFIGURE_CONNECTOR('data_ingestion_schedule', 'schedule') 存储过程设置的默认计划。

指定数据范围开始时间¶

默认情况下，Snowflake Connector for ServiceNow® 会同步相应 ServiceNow 表中的所有记录。对于具有 sys_updated_on 或 sys_created_on 列（从现在开始称为 时间列）的表，可以通过设置 数据范围开始时间 来限制同步数据的范围 – 即记录的相应 时间列 值的下限。

在这种配置下，相应 时间列 值早于 数据范围开始时间戳 的记录将 不会 被引入。此过程使用的相应 时间列 的确定方式与增量更新的确定方式 相同。

要更改 数据范围开始时间 值，请使用以下实参调用存储过程 CONFIGURE_TABLES_RANGE_START：

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

Copy

其中：

table_names

指定要配置 数据范围开始时间 的表名称数组。

range_start

时间戳，以 TIMESTAMP_TZ 格式指定 数据范围开始时间，或用 NULL 取消设置当前值。

• 如果表的引入尚未开始，则在第一次引入时将考虑 数据范围开始时间 值。

• 如果表的引入已经开始（例如，正在进行重新加载），则 数据范围开始时间 值将被忽略，并且需要（再次） 重新加载表，以过滤掉相应 时间列 值过旧的记录。

因此，建议在开始首次引入表之前（因此也在启用它之前）设置 数据范围开始时间。

例如，如果表 table1 和 table2 具有必需的 时间列，为了将这两个表的 数据范围开始时间 设置为 2022-11-23 07:00:00 UTC，请运行以下命令：

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

Copy

然后：

• 例如，对于表 table1，如果引入尚未开始，则相应 时间列 值早于 2022-11-23 07:00:00 的所有记录都 不会 被引入。

• 例如，对于表 table2，如果引入已开始，则在重新加载此表之前，所有数据同步中都将忽略 数据范围开始时间 值。在重新加载期间，相应 时间列 值早于 2022-11-23 07:00:00 的所有记录都不会被引入。

也可以取消设置 数据范围开始时间。例如，要对表 table1 取消设置 数据范围开始时间，请运行以下命令：

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

Copy

同样，如果表 table1 的引入已开始，则需要重新加载此表，才能从 ServiceNow 重新引入所有记录。

启用或禁用表同步¶

若要启用 ServiceNow 中特定表的数据同步，请使用以下实参调用 ENABLE_TABLES 存储过程：

CALL ENABLE_TABLES(<tables_to_enable>);

Copy

其中：

tables_to_enable

指定 ServiceNow 表名称数组。

使用表名称，不要使用 ServiceNow UI 中显示的标签。您可以在 ` ServiceNow 的数据字典表`_ 中找到表名称。在 ServiceNow UI 中，转到 System Definition » Tables。Name 列会显示表名称。

例如，要为名称为 table1、table2 和 table3 的表启用同步，请运行以下命令：

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

Copy

若要禁用 ServiceNow 中特定表的数据同步，请使用以下实参调用 DISABLE_TABLES 存储过程：

CALL DISABLE_TABLES(<tables_to_disable>);

Copy

其中：

tables_to_disable

指定 ServiceNow 表名称数组。

使用表名称，不要使用 ServiceNow UI 中显示的标签。您可以在 ` ServiceNow 的数据字典表`_ 中找到表名称。在 ServiceNow UI 中，转到 System Definition » Tables。Name 列会显示表名称。

例如，要为名称为 table1 和 table2 的表禁用同步，请运行以下命令：

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

Copy

禁用该表将停止其同步。重新启用表同步后，将从暂停的位置开始恢复引入。

连接器会公开采用两个实参的 ENABLE_TABLES 过程的已弃用版本：

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

Copy

其中：

tables_to_configure

指定以逗号分隔的 ServiceNow 表名称列表。

enable

指定是否应为这些表启用或禁用同步。指定为 TRUE 以启用或指定为 FALSE 以禁用。

此过程已弃用，并将在未来的连接器版本中移除。我们建议将 ENABLE_TABLES 和 DISABLE_TABLES 与单个实参搭配使用。

ENABLE_TABLES 和 DISABLE_TABLES 过程会将指定的表名称添加到 ENABLED_TABLES 视图中。

如果要将 ServiceNow 中的所有可用表添加到 ENABLED_TABLES 视图中，请调用 PREFILL_CONFIG_TABLE 存储过程。

若要调用此过程，请运行以下命令：

CALL PREFILL_CONFIG_TABLE();

此过程会将所有 ServiceNow 表添加到 ENABLED_TABLES 视图中，并默认禁用表引入。

要允许这些新添加的表进行同步：

1. 运行以下命令，生成 ENABLED_TABLES 视图中的表逗号分隔列表：

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

   Copy

2. 在此命令返回的列表中，移除不应进行同步的所有表。

3. 调用 ENABLE_TABLES 存储过程，并传至此列表中。

如果最近向 ServiceNow 添加了新表，则可以使用相同方法（即生成表列表、编辑列表并将列表传至 ENABLE_TABLES 存储过程）来识别新表并允许这些表进行同步。

为配置了列筛选的表启用同步¶

如果不需要在 Snowflake 中查看 ServiceNow 表的所有列，可以跳过这些列。例如，如果单行超过行大小上限 10 MB，您可能希望跳过这些列。

若要允许引入包含指定列的表，请运行以下命令：

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

Copy

其中：

table_to_enable

指定 ServiceNow 表名称。

include_columns

指定要引入的列名称数组。如果存在 sys_id、sys_created_on 和 sys_updated_on，即使此数组中未提及这些名称，引入时也会包含这些名称。

exclude_columns

指定引入时要排除的列名称数组。您不能排除 sys_id、sys_created_on 或 sys_updated_on 列，因为连接器在引入过程中会使用它们。

例如，假设有一个名为 u_table 的 ServiceNow 表，该表包含 sys_id、sys_updated_on、col_1 和 col_2 列，且执行以下语句：

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

Copy

此时，将仅为给定表引入 sys_id 和 sys_updated_on 列；但如果调用以下内容：

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

Copy

则会引入 sys_id、sys_updated_on 和 col_2。

连接器将验证所提供的列，如果 ServiceNow 中没有任何可用列，则会拒绝启用请求。由于 ServiceNow API 仅支持包含模式，连接器会将提供的列数组转换为所包含列的列表，并将其与各个请求一起发送到 ServiceNow。附带所包含列的 URL 可能太长， ServiceNow 无法处理。在调用 ENABLE_TABLE_WITH_COLUMNS 时，连接器会验证此限制。

可以在 ENABLED_TABLES 视图的 INCLUDED_COLUMNS 列中找到每个表所包含列的配置。若要修改所引入列的列表，需要先禁用特定表。如果为表配置了列筛选，则只能使用 ENABLE_TABLE_WITH_COLUMNS 过程启用列。在这种情况下，您不能使用 ENABLE_TABLES。

配置变更不会影响已引入的数据。列筛选仅适用于新引入的记录。

展平视图仅包含启用表时指定的列。每次所包含列的列表发生变更时，视图都会更新。如果未配置列筛选，则视图中会包含所有可用列。

重新加载表中的数据¶

若要重新加载特定表中的数据，请调用 RELOAD_TABLE 存储过程：

CALL RELOAD_TABLE('<table_name>');

其中：

table_name

指定要重新加载的表的名称。

调用 RELOAD_TABLE 存储过程时，连接器将执行以下示例：

1. 连接器将暂时挂起原始表以执行引入。

   备注

   重新加载表时，无法重新启用表以执行引入。

2. 连接器会创建用来执行引入的单独临时表。

3. 连接器会将数据引入到这个新的临时表中。这个表在 CONNECTOR_STATS 视图中显示为使用 __tmp 后缀命名的表）。

   备注

   每次重新加载都会考虑 数据范围开始时间 的值，该值可以限制引入哪些记录。

4. 引入数据后，连接器会使用临时表中的数据替换原始表中的数据。

5. 连接器将删除临时表。

6. 连接器将重新启用原始表以执行引入。

在此过程中，您可以继续查询原始表中的现有数据。但是，在引入过程完成之前，对 ServiceNow 表中数据的变更不会反映到 Snowflake 表中。

为避免 ServiceNow 实例过载，请每次只重新加载一个表。

取消表的重新加载¶

若要取消重新加载表中数据的过程，请使用 CANCEL_RELOAD_TABLE 存储过程，如以下示例所示：

CALL CANCEL_RELOAD_TABLE('<table_name>');

其中：

table_name

指定要取消重新加载的表的名称。

取消重新加载时，连接器将删除在重新加载期间创建的所有临时对象。然后，可将该表作为正常同步计划的一部分引入。

配置表的单页提取大小¶

连接器通过将表划分为称作页面的较小区块来提取表中的数据。每向 ServiceNow 发出一个 API 请求，就会提取一个页面。由于 Snowflake 和 ServiceNow REST APIs 受到的限制，来自 ServiceNow API 的响应大小不能超过 10 MB，并且应在小于一分钟的时间内返回。

为了解决这个问题，连接器限制了单次 API 请求中的提取行数。此限制为页面大小。

连接器使用以下过程来确定页面大小：

1. 最初，默认页面大小设置为 10,000 行。

2. 如果由于超出响应大小，导致在引入过程中提取请求失败，则页面大小将逐渐减小 1000、100、10 和 1，直到请求成功或将最终页面大小设置为 1。

3. 成功时的页面大小值将保存在连接器状态中，供后续请求使用。

表的当前页面大小可在 ENABLED_TABLES 视图中查看。若要查看页面大小，请运行以下命令：

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

其中：

table_name

指定要引入的 ServiceNow 表的名称。

连接器用于确定页面大小的过程可能会导致效率降低。此过程只减小页面大小。不增加页面大小。如果表中存在单个大行，导致页面大小设置为较低的值，则这种情况可能会发生。

若要避免这种情况，可以通过调用 RESET_PAGE_SIZE 存储过程来手动设置页面大小，如以下示例所示：

CALL RESET_PAGE_SIZE('<table_name>');

其中：

table_name

指定要引入的 ServiceNow 表的名称。

引入运行¶

给定表的引入会根据配置好的计划触发。运行会从源表中循环下载所有相关行，这些行将组成上一段中提到的页面。

初始加载和更新

一页数据提取完成时，会立即插入到相应的事件日志表中。在这个暂存区，新提取的更改在同步表中不可用，也不能通过展平视图使用。提取完成后，只要有任何数据返回，就会发起下一个附带更新条件的请求。如果引入运行完成，并且源表中没有更多要提取的数据，则会触发异步合并任务，该任务会从自上次合并以来插入的事件日志中获取所有变更，并将这些变更应用到同步表。应用完成后，就可以在同步表和展平视图中使用数据了。

截断和加载

在截断和加载模式下，每次引入运行都会创建一个临时表。每个提取的行页面都会首先插入到此临时表中（这个表位于内部连接器架构中，连接器用户无法使用）。在这个暂存区，新提取的更改在同步表中不可用，也不能通过展平视图使用，它们仍显示在上一次运行中提取的数据。如果引入运行完成，并且源表中没有更多可用数据，临时表中的数据将会替换同步表中的现有数据。所有提取的行也会添加到事件日志中。最后，会将临时表删除。

监控进度

若要查看当前或过去引入运行的状态，可以查询 CONNECTOR_STATS 视图。它显示在 STATUS 列中。仅当提取数据成功，且所有更改都应用于同步表时，它才会设置为 DONE。如果引入正在运行，或是同步表合并/同步表行的替换尚未完成，则状态为 RUNNING。