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

存档的记录¶

对于引入的表，连接器不会在 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. 以具有 ACCOUNTADMIN 角色的用户身份登录 Snowsight。

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

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

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

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

6. 修改要引入的表：

   1. 搜索要引入的表。

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

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

7. 选择 Update data sync。

指定同步计划¶

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

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

CALL CONFIGURE_DATA_INGESTION_SCHEDULE(<schedule>);

其中：

schedule

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

• { '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' } });

Copy

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

CALL CONFIGURE_CUSTOM_SCHEDULE_START_INGESTION_WINDOW(<window_length>);

Copy

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

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

• 已完成元数据表的引入

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

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

指定数据范围开始时间¶

默认情况下，Snowflake Connector for ServiceNow®V2 会同步相应 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 和 DISABLE_TABLES 过程会将指定的表名称添加到 CONFIGURED_TABLES 视图中。

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

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

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

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

Copy

其中：

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'] });

Copy

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

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

Copy

则会引入 sys_id、sys_updated_on 和 col_2。

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

可以在 CONFIGURED_TABLES 视图的 INCLUDED_COLUMNS 列中找到每个表所包含列的配置。若要修改所引入列的列表，需要先禁用特定表。如果为表配置了列筛选，则只能使用 ENABLE_TABLE 过程启用表。在这种情况下，不能使用 :code:`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. 成功时的页面大小值将保存在连接器状态中，供后续请求使用。

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

SELECT PAGE_SIZE FROM TABLES_STATE 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。