Set up data ingestion for your ServiceNow® data¶

アーカイブ済みの記録¶

コネクタは、インジェストされたテーブルに対してSnowflake側で ServiceNow でアーカイブされた記録 を積極的に反映しません。ある日付より古い非アクティブな記録をアーカイブすると想定すると、以下のようになります。

• コネクタがインジェストする前（たとえば、テーブルの 初期ロード の前）にアーカイブされた記録は、Snowflake側のテーブルにはまったく存在しません。

• コネクタによって既にインジェストされた後にアーカイブされた記録は、アーカイブアクションが発生したことを示すことなく、Snowflake側に残ります。

• 既に 増分更新 モードで動作しているテーブルに対して復元されたアーカイブ記録は、その後にその記録も変更されない限り（その sys_updated_on 値が現在の時刻に更新されない限り）、Snowflake側でインジェストされることはありません。

• テーブルの 初期ロード 中に復元されたアーカイブ記録は、 ID 列の sys_id によっては、Snowflake側でインジェストされる場合があります。

アクティブなアーカイブルールがあるテーブルを最新の状態にしたい場合、 テーブル全体をリロード することができます。しかし、リロード終了後にアーカイブまたは復元された記録は、上記と同じ原則に従います。

ServiceNow アーカイブテーブル ar_[table_name] の同期を有効にすることができます。ただし、そのようなテーブルの 初期ロード に続く最初の 増分更新 は、アーカイブテーブルの 初期ロード が開始された日以降に作成/更新された記録のために検索されます。sys_updated_on または sys_created_on のどちらも記録のアーカイブ時には変更されないため、アーカイブテーブルの 初期ロード 以降、ある時点までにアーカイブされた記録は、Snowflake側で欠落しています。たとえば、1年以上前の記録をアーカイブする場合、アーカイブテーブルの 初期ロード の後、1年間アーカイブされた記録は、Snowflake側のアーカイブテーブルにインジェストされません。アーカイブテーブルの 初期ロード の後、 destroyルール によって復元たは削除されたアーカイブ記録は、Snowflake側でそのテーブルから削除されることはありません。

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 を選択します。

テテーブル同期の有効化または無効化¶

このセクションでは、 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®テーブルのすべての列が不要な場合、コネクタはそれらを無視できます。たとえば、1行が最大行サイズ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 を使用して除外することはできません。

たとえば、列 ServiceNow、 u_table、 sys_id、 sys_updated_on が含まれる col_1 という名前の :code:`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®で利用できない場合は、有効化のリクエストを拒否します。ServiceNowAPI はインクルードモードのみをサポートしています。そのため、コネクタは提供された列配列をインクルード列リストに変換して、リクエストごとに ServiceNow®に送信します。列が含まれる URL は、 ServiceNow®で処理するには長すぎる可能性があります。コネクタは、 ENABLE_TABLE が呼び出されたときに、この制限を検証します。

各テーブルの列の構成は、 INCLUDED_COLUMNS ビューの CONFIGURED_TABLES 列で確認できます。インジェストされる列のリストを変更するには、まず特定のテーブルを無効化する必要があります。テーブルに対してテーブルフィルタリングが構成されている場合は、 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	少なくとも1つが満たされる必要がある条件を結合する、論理演算子。 重要 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.

フィルター表現のルールと制限:

• 任意の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']
});

同期スケジュールの指定¶

Snowflake Connector for ServiceNow® は、指定されたスケジュールですべての ServiceNow®テーブルからSnowflakeにデータを同期します。デフォルトでは、すべてのテーブルが毎時（1時間ごとに）同期されます。

すべてのテーブルのデフォルトの同期スケジュールを変更するには、次の引数で CONFIGURE_DATA_INGESTION_SCHEDULE ストアドプロシージャを呼び出します。

CALL CONFIGURE_DATA_INGESTION_SCHEDULE(<schedule>);

条件:

schedule

同期の頻度を指定します。次の JSON 値のいずれかを指定できます。

• ``{ 'type': 'continuous' }``は、ほぼリアルタイムのインジェスチョンスケジュールです。この同期スケジュールのテーブルでは、専用のワーカーを使用してデータを取り込み、並行して同期できるテーブルの最大数にカウントされません。詳細については、 コネクタのスケーリング をご参照ください。連続スケジュールで最大20個のテーブルを構成するできます。

  警告

  継続的なスケジュールがあるテーブルは、ServiceNow®インスタンスの負荷が増加します。さらに、コネクタウェアハウスが常に利用されるようになり、ウェアハウスのクレジット消費が増加します。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 プロパティを含むオブジェクト。詳細は schedule ストアドプロシージャの CONFIGURE_DATA_INGESTION_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

同期の頻度を指定します。詳細は schedule ストアドプロシージャの CONFIGURE_DATA_INGESTION_SCHEDULE をご参照ください。

たとえば、毎週土曜日と日曜日の11:00 table_1 table_2 にテーブル PM と UTC をインジェストするには、以下のストアドプロシージャを呼び出します。

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時間単位に切り上げられ、少なくとも1時間継続する必要があります。たとえば、値 'PT12H' は12時間継続するウィンドウを指定し、 'P2D' は2日間継続するウィンドウを指定します。

カスタムスケジュールを持つテーブルのみを有効にすると、この構成は構成されたテーブルのフラット化されたビューの作成とリフレッシュにかかる時間にのみ影響します。フラット化されたビューは、以下の条件が満たされた後、最初のインジェスチョンサイクルで作成されます。

• メタデータテーブルのインジェスチョンが完了している

• 構成されたテーブルのインジェスチョンが開始されている。

メールアラートが有効になっている場合、カスタムスケジュールを使用するときにアラート頻度を Once per day に変更することをSnowflakeはお勧めします。

削除を同期させるかどうかの指定¶

コネクタが 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®ドキュメント をご覧ください。

解決された値は、フラット化された表示で、接尾辞 __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);

data range start timeの指定¶

デフォルトでは、 Snowflake Connector for ServiceNow® は対応する ServiceNow テーブルのすべての記録を同期します。sys_updated_on または sys_created_on 列（以降、time列 と呼ぶ）が存在するテーブルでは、data range start time*（つまり記録の対応する *time列 の値の下限）を設定することで、同期データの範囲を制限することができます。

このような構成では、対応する time列 の値が data range start timestamp より古い記録はインジェスト されません。このプロシージャで使用される対応する time列 は、増分更新と 同じ方法 で決定されます。

data range start timestamp 値を変更するには、 CONFIGURE_TABLES_RANGE_START ストアドプロシージャを次の引数で呼び出します。

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

Copy

条件:

table_names

data range start time を構成するテーブル名の配列を指定します。

range_start

data range start time を TIMESTAMP_TZ フォーマットで指定するタイムスタンプ、または NULL で現在値の設定を解除します。

• テーブルのインジェスチョンがまだ開始されていない場合、data range start time の値は、最初のインジェスチョンで考慮されます。

• テーブルのインジェスチョンが既に開始されている場合（リロード中など）、 data range start time 値は無視され、対応する time列 値が古すぎる記録をフィルターするために（別の） テーブルのリロード が必要になります。

したがって、テーブルの最初のインジェスチョンを開始する前（つまり、テーブルを有効にする前）に、data range start time を設定することをお勧めします。

例えば、テーブル table1 と table2 に必要な*time列*がある場合、これら2つのテーブルの data range start time を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 より前に対応する time 列 の値を持つすべての記録はインジェスト されません。

• 例えば、テーブル table2 に対して、そのインジェスチョンが既に開始されている場合、このテーブルをリロードするまで、すべてのデータ同期で data range time start 値は無視されます。リロード中、2022-11-23 07:00:00より前に対応する time列 値を持つ記録はすべてインジェストされません。

data range start time の設定を解除することも可能です。例えば、テーブル 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. コネクタは、この新しい仮テーブルにデータをインジェストします。このテーブルは、 :ref:` サフィックスが付いた名前のテーブルとして CONNECTOR_STATS<label-monitoring_the_servicenow_connector_v2> :code:`__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 の 1、2、3 の sys_id 値を持つレコードのみをリロードするために、以下のコマンドを実行します。

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

2022-11-23 07:00:00 から 2022-11-23 08:00:00 UTC の間の``sys_updated_on`` 値を持ち、かつテーブル incident 内でまだアクティブなレコードのみをリロードするには、次のコマンドを実行します。

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

リロードをキャンセルするテーブルの名前を指定します。

リロードをキャンセルすると、コネクタはリロード中に作成されたすべての仮オブジェクトをドロップします。その後、テーブルは通常の同期スケジュールの一部としてインジェスチョン可能になります。