ServiceNow®データのデータインジェスチョンの設定¶

Snowsightを使用したデータインジェスチョンの変更¶

インジェストされる ServiceNow テーブルまたはテーブルの同期スケジュールを変更するには、次を実行します。

1. ACCOUNTADMIN ロールを持つユーザーとして Snowsight にサインインします。

2. ナビゲーションメニューで Data Products » Marketplace を選択します。

3. ServiceNow®用Snowflakeコネクタを検索し、コネクタのタイルを選択します。

4. Snowflake Connector for ServiceNow® のページで、 Edit を選択します。

5. インジェストするテーブルを変更します。

   1. インジェストするテーブルを検索します。

   2. 選択または選択解除するテーブルの横にある Status 列のチェックボックスを選択します。

   3. Synch Schedule で、Snowflakeと ServiceNow 間でテーブルを同期する頻度を選択します。

6. Update を選択します。

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

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

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

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

条件:

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時間とし、最低1時間継続する必要があります。たとえば、値 'PT12H' は12時間継続するウィンドウを指定し、 'P2D' は2日間継続するウィンドウを指定します。

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

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

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

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

さらに、コネクタは以下の引数を持つ廃止された 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') ストアドプロシージャを呼び出して設定したデフォルトのスケジュールよりも優先されます。

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 からすべての記録をインジェストするには、このテーブルのリロードが必要です。

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

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

テーブルを無効にすると、同期が停止します。テーブルの同期が再度有効になると、一時停止された場所からインジェスチョンが再開されます。

コネクタは、2つの引数を取る、廃止されたバージョンの 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 の列は、コネクタがインジェスチョン処理で使用するため除外できません。

例えば、列 sys_id、 sys_updated_on、 col_1、 col_2 が含まれる u_table という名前の ServiceNow テーブルに対して次を実行します。

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. コネクタは、この新しい仮テーブルにデータをインジェストします。このテーブルは、 __tmp サフィックスが付いた名前のテーブルとして CONNECTOR_STATS ビューに表示されます。

   注釈

   リロードのたびに data range start time の値が考慮され、どの記録がインジェストされるかを制限することができます。

4. データがインジェストされた後、コネクタは元のテーブルのデータを仮テーブルのデータに置き換えます。

5. コネクタは仮テーブルを削除します。

6. コネクタは、インジェスチョンのために元のテーブルを再度有効にします。

このプロセス中、元のテーブル内にある既存のデータに対して引き続きクエリを実行できます。ただし、 ServiceNow テーブルのデータへの変更は、インジェスチョンプロセスが完了するまで Snowflakeテーブルに反映されません。

ServiceNow インスタンスの過負荷を回避するには、一度に1つのテーブルのみをリロードします。

テーブルのリロードのキャンセル¶

テーブルにデータをリロードするプロセスをキャンセルするには、次の例に示すように CANCEL_RELOAD_TABLE ストアドプロシージャを使用します。

CALL CANCEL_RELOAD_TABLE('<table_name>');

条件:

table_name

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

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

テーブルの単一ページフェッチのサイズ構成¶

コネクタは、テーブルをページと呼ばれる小さなチャンクに分割することで、テーブルからデータをフェッチします。ServiceNow への API リクエストごとに1ページがフェッチされます。Snowflakeと ServiceNow REST APIs の制限により、 ServiceNow API からの応答のサイズは10 MB を超えることはできず、応答は1分未満に返される必要があります。

これを考慮して、コネクタは単一の API リクエスト内でフェッチされる行数を制限します。この制限はページサイズです。

コネクタは、次のプロセスを使用してページサイズを決定します。

1. 最初にデフォルトのページサイズは10,000行に設定されています。

2. 応答サイズを超えたためにインジェスチョン中にフェッチリクエストが失敗した場合、リクエストが成功するか、最終的なページサイズが1に設定されるまで、ページサイズは1000、100、10、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 となります。