Set up data ingestion for your ServiceNow® data¶

存档的记录¶

对于引入的表，连接器不会在 Snowflake 一端主动反映 ServiceNow 中存档的记录 (https://docs.servicenow.com/bundle/washingtondc-platform-administration/page/administer/database-rotation/concept/c_ArchiveData.html)。假设您存档了早于特定日期的非活动记录，则适用以下内容：

• 在连接器引入之前（例如，在表 初始加载 之前）存档的任何记录都不会出现在 Snowflake 一端的表中。

• 任何在连接器引入后存档的记录仍保留在 Snowflake 一端，不会显示存档操作。

• 对于已在 增量更新 模式下运行的表，所恢复的任何存档记录都不会在 Snowflake 端引入，除非该记录后续也发生了修改（其 sys_updated_on 值更新为当前时间）。

• 在表的 初始加载 过程中恢复的存档记录可能会在 Snowflake 一端引入，具体取决于其在 sys_id 列中的 ID。

如果要更新有活动存档规则的表，可以 重新加载整个表，但重新加载完成后存档或回复的任何记录都将遵循上述原则。

可以启用 ServiceNow 存档表 ar_[table_name] 以执行同步。但此类表 初始加载 后的第一次 增量更新 将搜索存档表 初始加载 开始日期之后创建/更新的记录。因为当记录存档时，sys_updated_on 和 sys_created_on 都不会被修改，在 Snowflake 一端，在存档表 初始加载 到某个时间点后存档的记录会丢失。例如，如果存档记录的时间超过一年，则存档表 初始加载 后存档一年的任何记录都不会引入到 Snowflake 一端的存档表中。在 初始加载 存档表后，通过 销毁规则 (https://docs.servicenow.com/bundle/washingtondc-platform-administration/page/administer/database-rotation/task/t_CreateADestructionRule.html) 恢复或删除的存档记录在 Snowflake 一端永远不会从中删除。

使用 Snowsight 修改数据引入¶

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

1. Sign in to Snowsight as a user with the ACCOUNTADMIN role.

2. In the navigation menu, select Catalog » Apps.

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

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

5. 选择 Edit tables 按钮进入编辑模式。

6. 修改要引入的表：

   1. 搜索要引入的表。

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

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

7. 选择 Update data sync。

启用或禁用表同步¶

本节介绍如何启用或禁用 ServiceNow® 中的表同步。可以使用默认配置和自定义配置来启用同步。

CALL ENABLE_TABLES(<tables_to_enable>);

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

CALL DISABLE_TABLES(<tables_to_disable>);

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

使用列筛选启用单个表¶

如果不需要 Snowflake 中的 ServiceNow® 表的所有列，连接器可以忽略。例如，如果单行超过行大小上限 128 MB，请跳过这些列。

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

CALL ENABLE_TABLE('<table_to_enable>', <table_config>);

其中：

table_to_enable

指定 ServiceNow® 表名称。

table_config

对象包括带有列名称列表的 include_columns 或 exclude_columns 属性。如果有 sys_id、sys_created_on 和 sys_updated_on，则始终包含它们。您不必将其添加到 included_columns 数组中，也不能使用 excluded_columns 将其排除，因为连接器会在引入过程中使用它们。

例如，一个名为 u_table 的 ServiceNow® 表具有 sys_id、sys_updated_on、col_1 和 col_2 列，且执行以下语句：

CALL ENABLE_TABLE('u_table', { 'include_columns': ['sys_id', 'sys_updated_on'] });

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

CALL ENABLE_TABLE('u_table', { 'exclude_columns': ['col_1'] });

则会引入 sys_id、sys_updated_on 和 col_2。

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

可以在 CONFIGURED_TABLES 视图的 INCLUDED_COLUMNS 列中找到每个表的列配置。若要修改所引入列的列表，需要先禁用特定表。如果为表配置了列筛选，则只能使用 ENABLE_TABLE 过程启用表。您不能使用 ENABLE_TABLES，它接受表列表作为实参。

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

使用行筛选启用单个表¶

您可以通过指定筛选器条件，排除从 ServiceNow® 表指定行引入的数据。例如，排除 Snowflake 中包含您不想要的敏感数据的行，或者排除包含不必要数据的行以降低成本。

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

CALL ENABLE_TABLE('<table_to_enable>', <table_config>);

其中：

table_to_enable

指定 ServiceNow® 表名称。

table_config

对象包括带筛选器表达式的 row_filter 属性，该表达式是一个有效字符串。

目前支持的筛选器运算符为：

运算符	描述	示例
AND	连接条件的逻辑运算符，表示两个条件都必须满足。	active = "true" AND impact = "2"
OR	连接条件的逻辑运算符，表示至少必须满足一个条件。 重要 优先于 AND 运算符。请参阅以下 示例。	tablename = "incident" OR tablename = "problem"
=	Returns true if the values are equal.	priority = "1"
!=	Returns true if the values are not equal.	state != "7"
LIKE	Returns true if the value contains the specified character sequence. [1]	newvalue LIKE "privacy"
NOT LIKE	Returns true if the value doesn't contain a specified character sequence. [1]	description NOT LIKE "test"
STARTSWITH	Returns true if the value starts with the specified character sequence. [1]	description STARTSWITH "important"
ENDSWITH	Returns true if value ends with specified character sequence. [1]	description ENDSWITH "important"
IN	Returns true if the value is equal to any of the list of values. [2]	tablename IN ("incident", "task", "cmdb_ci")
NOT IN	Returns true if the value is not equal to any of the list values. [2]	status NOT IN ("in progress", "on hold", "cancelled")

_[1] - fields must be of string data type.

_[2] - choice fields must contain strings.

筛选器表达式规则和限制：

• 任何两个筛选器表达式必须使用 AND 或 OR 运算符进行连接。

• 运算符必须用空格隔开，并且必须大写。

• 值表达式必须放在双引号内。

• 表达式区分大小写。

• 表达式在 sys_id、sys_updated_on 或 sys_created_on 列上无法运算。

CALL ENABLE_TABLE('sys_audit', {
  'row_filter': 'tablename = "incident" AND fieldname = "cause" AND newvalue LIKE "privacy"'
});

CALL ENABLE_TABLE('incident', {
  'row_filter': 'active = "true" AND sys_created_by STARTSWITH "support" OR sys_created_by ENDSWITH "admin" AND category IN ("Network", "Cloud Management")'
});

CALL ENABLE_TABLE('incident', {
  'row_filter': 'incident_state IN ("1", "2", "3")', -- "New", "In Progress", "On Hold"
  'include_columns': ['incident_state', 'description']
});

指定同步计划¶

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

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

CALL CONFIGURE_DATA_INGESTION_SCHEDULE(<schedule>);

其中：

schedule

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

• { 'type': 'continuous' }，这是近实时引入计划。具有此同步计划的表使用专用的处理器来引入数据，并且不计入可以并行同步的最大表数。有关更多信息，请参阅 缩放连接器。您可以使用连续计划配置最多 20 个表。

  警告

  使用连续计划的表会导致 ServiceNow® 实例的负载增加。此外，它会导致连接器仓库持续使用，从而增加仓库的 Credit 使用量。Snowflake 建议谨慎使用连续计划，并且仅适用于需要在 Snowflake 中提供近实时数据的表。为了防止 ServiceNow® 实例过载，连接器实施了一种检测机制，能够自动禁用采用连续计划的失败的表。有关更多信息，请参阅 连接器禁用了使用连续计划的表。

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

  • '30m'

  • '1h'

  • '3h'

  • '6h'

  • '12h'

  • '1d'

• { 'type': 'custom', 'value': { 'hour': <hour>, 'day_of_week': '<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' 指示从星期五到星期日的范围。

在启用过程中，可以为特定表配置引入计划。要启用单个表并设置其引入计划，请使用以下实参调用 ENABLE_TABLE 存储过程：

CALL ENABLE_TABLE('<table_name>', <table_config>);

其中：

table_name

指定要启用的 ServiceNow® 表名称。

table_config

对象包括 schedule 属性，指定表同步的配置。请查看 CONFIGURE_DATA_INGESTION_SCHEDULE 存储过程的 schedule 以了解详细信息。

例如，要启用表 table_1 的引入并且每 3 小时同步一次数据，请调用以下存储过程：

CALL ENABLE_TABLE('table_1', { 'schedule': { 'type': 'interval', 'value': '3h' } });

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

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

其中：

table_names

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

schedule

指定同步的频率。请查看 CONFIGURE_DATA_INGESTION_SCHEDULE 存储过程的 schedule 以了解详细信息。

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

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

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

CALL CONFIGURE_CUSTOM_SCHEDULE_START_INGESTION_WINDOW(<window_length>);

其中，window_length 是 ISO 8601 持续时间格式的时间窗口长度。持续时间必须向上取整到下一个整小时，并且必须至少持续 1 小时。例如，值 'PT12H' 指定的是持续 12 小时的时间窗口，'P2D' 指定的则是持续 2 天的时间窗口。

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

• 已完成元数据表的引入

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

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

指定是否应同步删除¶

您可以指定连接器是否应将删除从 ServiceNow® 同步到Snowflake。默认情况下，如果配置了日志表，连接器会同步删除操作。然而，您可能想要禁用特定表的删除同步，而不更改全局配置。

要启用具有指定删除同步设置的表引入，请运行以下命令：

CALL ENABLE_TABLE('<table_to_enable>', <table_config>);

其中：

table_to_enable

指定 ServiceNow® 表名称。

table_config

包含 sync_deletions 布尔属性的对象。如果值设置为 true，则连接器会同步表的删除；如果值设置为 false，则连接器不会同步表的删除。

例如，要启用表 incident 的引入，但不同步删除，请运行以下命令：

CALL ENABLE_TABLE('incident', { 'sync_deletions': false });

指定是否应提取显示值¶

连接器可以获取 ServiceNow® 中任何支持类型字段的显示值。显示值是可读值，它们对应于存储在数据库中的实际值，例如，一个值为 1 的字段的显示值可能为 High。要了解更多关于显示值的信息，请参阅 ServiceNow® 文档 (https://www.servicenow.com/docs/bundle/xanadu-platform-administration/page/administer/field-administration/concept/c_DisplayValues.html)。

解析后的值以扁平化视图显示在一个单独的列中，后缀为 __DISPLAY_VALUE。连接器使用 Snowflake 类型创建文本和布尔列，但对于其他类型，例如不同可能格式的数字或日期值，显示值作为变体存储。

CALL ENABLE_TABLE('<table_to_enable>', <table_config>);

CALL ENABLE_TABLE('incident', { 'fetch_display_values': true });

CALL CONFIGURE_DISPLAY_VALUE_FETCHING(<fetch_display_values>);

CALL CONFIGURE_DISPLAY_VALUE_FETCHING(true);

指定数据范围开始时间¶

默认情况下，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® 中引入回所有记录。

完全重新加载¶

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

CALL RELOAD_TABLE('<table_name>');

其中：

table_name

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

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

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

   备注

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

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

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

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

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

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

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

筛选重新加载¶

要仅重新加载特定表中的部分数据，请调用带有配置对象参数的 RELOAD_TABLE 存储过程：

CALL RELOAD_TABLE('<table_name>', <config>);

其中：

table_name

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

config

指定重新加载的配置。配置对象可以包括以下属性：

• sys_ids：要重新加载的 ServiceNow® 记录标识符 (sys_id) 的数组。

• data_reload_range_start_time 和 data_reload_range_end_time：以 TIMESTAMP_TZ 格式指定数据范围的时间戳值。根据给定的表引入类型，仅在指定时间范围内具有 sys_updated_on 或 sys_created_on 的记录会被重新加载。

• conditions：一个字符串表达式，指定 ServiceNow® 表中字段的条件。只有满足条件的记录会被重新加载。

  表达式的语法与 行筛选 相同。如果在常规表上配置了行筛选，则也会应用于条件。

与完全重新加载相比，筛选重新加载不会替换原始表中的数据，而仅更改所选记录。

例如，要仅重新加载表 incident 中 sys_id 值为 1、2 和 3 的记录，请运行以下命令：

CALL RELOAD_TABLE('incident', { 'sys_ids': ['1', '2', '3'] });

要仅重新加载表 incident 中 sys_updated_on 值在 2022-11-23 07:00:00 和 2022-11-23 08:00:00 UTC 之间，并且仍然处于活动状态的记录，请运行以下命令：

CALL RELOAD_TABLE('incident', {
  'data_reload_range_start_time': TO_TIMESTAMP_TZ('2022-11-23 07:00:00 +00:00'),
  'data_reload_range_end_time': TO_TIMESTAMP_TZ('2022-11-23 08:00:00 +00:00'),
  'conditions': 'active = "true"'
});

取消表的重新加载¶

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

CALL CANCEL_RELOAD_TABLE('<table_name>');

其中：

table_name

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

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