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

存档的记录¶

The connector does not actively reflect the records archived in ServiceNow (https://docs.servicenow.com/bundle/washingtondc-platform-administration/page/administer/database-rotation/concept/c_ArchiveData.html) on the Snowflake side for the ingested tables. Assuming that you archive inactive records older than a certain date, the following apply:

• Any record archived before the connector ingested it (for example, before the initial load of the table) will not be present in the table on the Snowflake side at all.

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

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

• An archived record restored during the initial load of the table may be ingested on the Snowflake side depending on its ID in the sys_id column.

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

可以启用 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 一端永远不会从中删除。

Modify data ingestion using Snowsight¶

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

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

2. 在导航菜单中，选择 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。

Enable or disable the table synchronization¶

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

CALL ENABLE_TABLES(<tables_to_enable>);

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

CALL DISABLE_TABLES(<tables_to_disable>);

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

Enable a single table by using column filtering¶

If you don't need all columns from a ServiceNow® table in Snowflake, the connector can ignore them. For example, skip columns if a single row exceeds the maximum row size of 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。

The connector validates the provided columns and rejects the enablement request if any of the columns are not available in ServiceNow®. ServiceNow® API supports only include mode. As a result the connector transforms provided column arrays into included columns list and sends them with each request to ServiceNow®. The URL with included columns could possibly be too long to be handled by ServiceNow®. The connector validates this limitation when the ENABLE_TABLE is invoked.

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

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

Enable a single table by using row filtering¶

您可以通过指定筛选器条件，排除从 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"
=	如果值相等，则返回 true。	priority = "1"
!=	如果值不相等，则返回 true。	state != "7"
LIKE	如果该值包含指定的字符，则返回 true。[1]	newvalue LIKE "privacy"
NOT LIKE	如果该值不包含指定的字符序列，则返回 true。[1]	description NOT LIKE "test"
STARTSWITH	如果值以指定的字符序列开头，则返回 true。 [1]	description STARTSWITH "important"
ENDSWITH	如果值以指定的字符序列结尾，则返回 true。[1]	description ENDSWITH "important"
IN	如果该等于值列表中的任何值，则返回 true。[2]	tablename IN ("incident", "task", "cmdb_ci")
NOT IN	如果该值不等于值列表中的任何值，则返回 true。[2]	status NOT IN ("in progress", "on hold", "cancelled")

_[1] - 字段必须是 string 数据类型。

_[2] - 选择字段必须包含字符串。

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

• 任何两个筛选器表达式必须使用 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']
});

Specify the synchronization schedule¶

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。

Specify whether deletions should be synchronized¶

您可以指定连接器是否应将删除从 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 });

Specify whether display values should be fetched¶

连接器可以获取 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);

Specify the data range start time¶

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

With such a configuration, records with the corresponding time column value older than the data range start timestamp are not ingested. The corresponding time column used by this procedure is determined in the same way as for the incremental updates .

要更改 数据范围开始时间 值，请使用以下实参调用存储过程 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

然后：

• for table table1, for example, if its ingestion has not started yet, all records with a corresponding time column value before 2022-11-23 07:00:00 are not ingested.

• for table table2, for example, if its ingestion has already started, the data range time start value is ignored in all data synchronizations until reloading this table. During the reload, all records with a corresponding time column value before 2022-11-23 07:00:00 are not ingested.

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

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

Copy

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

Full reload¶

若要重新加载特定表中的数据，请调用 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 table reload¶

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

CALL CANCEL_RELOAD_TABLE('<table_name>');

其中：

table_name

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

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