SQL コマンドを使用したコネクタのインストールおよび構成¶

Snowflake Connector for ServiceNow®V2 のインストール¶

次の手順では、コネクタをインストールする方法について説明します。

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

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

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

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

   これにより、インストールプロセスの最初の部分を開始するために使用するダイアログが表示されます。

   ダイアログで、次のように構成します。

   1. Application name フィールドに、コネクタインスタンスのデータベースとして使用するデータベースの名前を入力します。このデータベースは自動的に作成されます。

   2. Warehouse used for installation フィールドで、コネクタのインストールに使用するウェアハウスを選択します。

      注釈

      これは、コネクタが ServiceNow®からのデータを同期するために使用するウェアハウスとは異なります。後のステップで、この目的のために別のウェアハウスを作成します。

   3. Get を選択します。

5. ダイアログが通知とともに表示されます: Installing App After installation, an email will be sent to <user_email>。SQL を使って構成を続けるには、ダイアログを閉じて Worksheets に進みます。

OAuth の設定¶

ServiceNow®インスタンスへの認証に OAuth を使用するように、 Snowflake Connector for ServiceNow®V2 を構成できます。

• ServiceNow では、 コード付与フロー で OAuth の使用をサポートするようにインスタンスを設定する必要があります。

• Snowflake Connector for ServiceNow®V2 内：

  • コネクタは、 TYPE = API_AUTHENTICATION とのセキュリティ統合を使用して、Snowflakeを ServiceNow®インスタンスに接続します。

    セキュリティ統合は、ServiceNow®インスタンスを認証するための ServiceNow® OAuth クライアント ID、クライアントシークレット、およびエンドポイント URL を指定します。

  • コネクタは、Snowflakeシークレットオブジェクトを使用して、認証情報などの機密情報を管理します。

    認証に OAuth を使用する場合、コネクタは ServiceNow® OAuth リフレッシュトークン、リフレッシュトークンの有効期限、およびセキュリティ統合の名前をSnowflakeシークレットオブジェクトに格納します。

Snowflake Connector for ServiceNow®V2 が OAuth を使用するように設定するには、次のステップに従います。

1. コード付与フローのある OAuth を使用するように ServiceNow®インスタンスを構成します。

   • ServiceNow®インスタンスが既に OAuth コード付与フローを使用していて、そのインスタンスを Snowflake Connector for ServiceNow®V2 で使用する場合は、クライアント ID、クライアントシークレット、OAuth トークンに対応するエンドポイント URL をメモします。

     詳細については、 OAuth トークンを管理する をご参照ください。この情報を書き留めたら、次のステップでセキュリティ統合を作成します。

   • 別の ServiceNow®インスタンスを使用する場合は、インスタンスにアクセスするか、インスタンスを作成し、 OAuth を設定する と クライアントがインスタンスにアクセスできるようにエンドポイントを作成する で示したように、コード付与フローで OAuth を使用するようにインスタンスを構成します。

2. ServiceNow®にアプリケーションレジストリを作成し、それを使用してコネクタを構成します。

   1. ServiceNow®インスタンスにログインし、 Homepage を選択します。

   2. OAuth を検索し、 Application Registry を選択します。

   3. New を選択してから、 Create an OAuth API endpoint for external clients を選択します。

      次の画像に示すように、アプリケーションレジストリの構成ページが表示されます。

      

   4. ServiceNow で、 Name フィールドに OAuth アプリケーションレジストリの名前を入力します。

   5. 必要に応じて、 ServiceNow で、 Refresh Token Lifespan フィールドと Access Token Lifespan フィールドの値を更新します。

      • Snowflakeは、アクセストークンの有効期間を少なくとも600秒に設定することをお勧めします。

      • 更新トークンの有効期間には、7776000（90日）の値を指定します。

   6. ServiceNow で、 Submit を選択します。

      OAuth アプリケーションレジストリがアプリケーションレジストリのリストに表示されます。

   7. ServiceNow で、作成したばかりのアプリケーションレジストリを選択します。

      ServiceNow®が Client ID フィールドと Client Secret フィールドの値を生成したことに注意してください。これらの値は、次のセクションで セキュリティ統合を作成する ときに使用します。

必須オブジェクトの作成¶

CREATE SECURITY INTEGRATION <name>
 TYPE = API_AUTHENTICATION
 AUTH_TYPE = OAUTH2
 OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST
 OAUTH_CLIENT_ID = '<client_id>'
 OAUTH_CLIENT_SECRET = '<client_secret>'
 OAUTH_TOKEN_ENDPOINT = 'https://<my_instance>.service-now.com/oauth_token.do'
 ENABLED = TRUE;

USE ROLE accountadmin;
CREATE WAREHOUSE servicenow_conn_warehouse WAREHOUSE_SIZE = LARGE;

SHOW PARAMETERS LIKE 'STATEMENT_TIMEOUT_IN_SECONDS' FOR ACCOUNT;
SHOW PARAMETERS LIKE 'STATEMENT_TIMEOUT_IN_SECONDS' FOR WAREHOUSE <connector_warehouse>;

ALTER ACCOUNT SET STATEMENT_TIMEOUT_IN_SECONDS = 10800;
ALTER WAREHOUSE <connector_warehouse> SET STATEMENT_TIMEOUT_IN_SECONDS = 10800;

USE ROLE accountadmin;
CREATE DATABASE dest_db;
CREATE SCHEMA dest_schema;

CREATE NETWORK RULE <name>
  MODE = 'EGRESS'
  TYPE = 'HOST_PORT'
  VALUE_LIST = ('<servicenow_instance_name>.service-now.com');

USE ROLE secretadmin;
GRANT USAGE ON SECRET secretsdb.apiauth.<secret_name> TO ROLE ACCOUNTADMIN;

CREATE EXTERNAL ACCESS INTEGRATION <integration_name>
  ALLOWED_NETWORK_RULES = (<network_rule_name>)
  ALLOWED_AUTHENTICATION_SECRETS = (<secret_name>)
  ENABLED = TRUE;

コネクタのログの構成¶

Snowflake Connector for ServiceNow®V2 は、イベントテーブルを使用してコネクタのエラーログを保存します。イベントテーブルを設定するには、 イベントテーブルの設定 ガイドに従います。

インストールされたコネクタの設定¶

コネクタを設定するには、次を行います。

1. Snowsightを使用してコネクタインスタンスのデータベースを作成します。データベースの作成方法の詳細については、 Snowsightによるコネクタのインストールと構成 をご参照ください。

2. SQL ワークシートに移動します。

3. ACCOUNTADMIN ロールを持つユーザーとしてログインします。例:

   USE ROLE ACCOUNTADMIN;
   

   Copy

4. コネクタに必要なすべての権限を コネクタのインスタンスとして機能するデータベース に付与します。

   • アカウントに対する EXECUTE TASK

   • アカウントに対する EXECUTE MANAGED TASK

   • コネクタ用に作成したウェアハウス に対する USAGE。

   • ServiceNow®データ用に作成したデータベース に対する USAGE

   • ServiceNow®データ用に作成したスキーマ に対する USAGE、CREATE TABLE、および CREATE VIEW。

   • ServiceNow®用に作成した外部アクセス統合 に対する USAGE

   • シークレット用に作成したデータベース に対する USAGE

   • シークレット用に作成したスキーマ に対する USAGE

   • 作成したシークレット に対する READ

   たとえば、 my_connector_servicenow という名前のコネクタに次の権限を付与するには、次を行います。

   • アカウントに対する EXECUTE TASK

   • アカウントに対する EXECUTE MANAGED TASK

   • ウェアハウス servicenow_conn_warehouse に対する USAGE

   • dest_db データベースに対する USAGE

   • dest_db.dest_schema スキーマに対する USAGE、 CREATE TABLE、 および CREATE VIEW

   • servicenow_external_access_integration 統合に対する USAGE

   • secretsdb データベースに対する USAGE

   • secretsdb.apiauth スキーマに対する USAGE

   • secretsdb.apiauth.servicenow_creds_oauth_code secret シークレットに対する READ

   次のコマンドを実行します。

   USE ROLE accountadmin;
   
   GRANT EXECUTE TASK ON ACCOUNT TO APPLICATION my_connector_servicenow;
   GRANT EXECUTE MANAGED TASK ON ACCOUNT TO APPLICATION my_connector_servicenow;
   
   GRANT USAGE ON WAREHOUSE servicenow_conn_warehouse TO APPLICATION my_connector_servicenow;
   
   GRANT USAGE ON DATABASE dest_db TO APPLICATION my_connector_servicenow;
   GRANT USAGE ON SCHEMA dest_db.dest_schema TO APPLICATION my_connector_servicenow;
   GRANT CREATE TABLE ON SCHEMA dest_db.dest_schema TO APPLICATION my_connector_servicenow;
   GRANT CREATE VIEW ON SCHEMA dest_db.dest_schema TO APPLICATION my_connector_servicenow;
   
   GRANT USAGE ON INTEGRATION servicenow_external_access_integration TO APPLICATION my_connector_servicenow;
   
   GRANT USAGE ON DATABASE secretsdb TO APPLICATION my_connector_servicenow;
   GRANT USAGE ON SCHEMA secretsdb.apiauth TO APPLICATION my_connector_servicenow;
   GRANT READ ON SECRET secretsdb.apiauth.servicenow_creds_oauth_code TO APPLICATION my_connector_servicenow;
   

   Copy

5. 宛先スキーマのテーブルとビューの所有権の譲渡（オプション）

   コネクタが再インストールされ、以前の宛先スキーマが再利用される場合、宛先スキーマのすべてのテーブルとビューの所有権をコネクタに譲渡する必要があります。スキーマ内のオブジェクトに対する許可の付与を管理し、インジェストされたテーブルのスキーマが変更されたときにフラット化されたビューを再作成するためには、コネクタに所有者権限が必要です。

   所有権を譲渡するには、 SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION 関数を呼び出します。

   USE ROLE accountadmin;
   CALL SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION(<connector_app>, true, <destination_database>, <destination_schema>);
   

   Copy

   SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION は、Snowflakeが提供するシステム関数で、指定したデータベースやスキーマのテーブルやビューの所有権をアプリケーションに譲渡することができます。譲渡されるのは、通常のテーブルと通常のビューの所有権のみです。たとえば、動的テーブル、外部テーブル、マテリアライズドビューなどの所有権は譲渡されません。

   この関数の署名は以下のとおりです。

   SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION(<to_app>, <should_copy_grants>, <from_database>, <from_schema>)
   

   Copy

   条件:

   to_app

   オブジェクトの所有権を譲渡するアプリケーションの名前を指定します。

   should_copy_grants

   TRUE の場合は既存の権限許可をコピーし、そうでない場合は取り消します。権限許可のコピーには、呼び出し側に MANAGE GRANTS の権限が必要です。

   from_database

   所有者が変更されるべきオブジェクトを含むデータベースの名前。

   from_schema

   （オプション）所有者を変更すべきオブジェクトを含むスキーマの名前。スキーマが指定されていない場合、提供されたデータベース内のすべてのスキーマのテーブルとビューの所有権が譲渡されます。管理されたスキーマのオブジェクトは、所有権の譲渡時に省かれます。

   この関数を実行するには、呼び出し元が以下のいずれかの条件を満たしている必要があります。

   • MANAGE GRANTS （例: ACCOUNTADMIN または SECURITYADMIN ロール）の権限がある、または

   • アプリケーションインスタンスを所有するロールと、所有権を譲渡するすべてのオブジェクトを所有するロールが含まれている。所有権がないオブジェクトは、関数によって省かれます。

   たとえば、所有権を譲渡するコネクタは次を満たしている必要があります:

   • my_connector_servicenow という名前のアプリケーションとしてインストールされた

   • Snowflake内にある ServiceNow®データの dest_db.dest_schema という名前のスキーマを使用している

   次のコマンドを実行します。

   USE ROLE accountadmin;
   CALL SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION('my_connector_servicenow', true, 'dest_db', 'dest_schema');
   

   Copy

   必要であれば、 DATA_READER アプリケーションロールを以前データを所有していたロールに付与し、データを使用する既存のパイプラインの中断を防ぎます。

   GRANT APPLICATION ROLE <connector_app>.DATA_READER TO ROLE <previous_data_owner_role>;
   

   Copy

   CONFIGURE_CONNECTOR プロシージャが実行されるまでは、 DATA_READER アプリケーションロールには宛先スキーマのテーブルとビューに対して権限の付与がないことに注意してください。

6. USE DATABASE コマンドを実行して、コネクタにデータベースを使用します。例:

   USE DATABASE my_connector_servicenow;
   

   Copy

7. CALL コマンドを使用して CONFIGURE_CONNECTOR という名前のストアドプロシージャを呼び出し、コネクタを構成します。

   CALL CONFIGURE_CONNECTOR({
     'warehouse': '<warehouse_name>',
     'destination_database': '<dest_db>',
     'destination_schema': '<dest_schema>'
   })
   

   Copy

   条件:

   warehouse_name

   コネクタのウェアハウスの名前を指定します。

   ウェアハウスの名前は、有効な オブジェクト識別子 である必要があります。

   dest_db

   Snowflake の ServiceNow®データ用のデータベース（先に作成したデータベース） の名前を指定します。

   データベースの名前は、有効な オブジェクト識別子 である必要があります。

   dest_schema

   Snowflake内にある ServiceNow®データのスキーマ（以前に作成したスキーマ） の完全修飾名を指定します。

   スキーマの名前は、有効な オブジェクト識別子 である必要があります。

   たとえば、構成するコネクタは次を満たしている必要があります。

   • ウェアハウス servicenow_conn_warehouse を使用している。

   • Snowflake内にある ServiceNow®データの dest_db.dest_schema という名前のスキーマを使用している

   次のコマンドを実行します。

   CALL CONFIGURE_CONNECTOR({
     'warehouse': 'servicenow_conn_warehouse',
     'destination_database': 'dest_db',
     'destination_schema': 'dest_schema'
   });
   

   Copy

   コネクタが正常に開始された場合、このストアドプロシージャは次のレスポンスを返します。

   {
     "responseCode": "OK",
     "message": "Connector successfully configured.",
   }
   

   Copy

   注釈

   コネクタが開始されると、コネクタに渡されたウェアハウス、宛先データベース、および宛先スキーマの名前を変更することはできません。コネクタはオブジェクトを名前で参照します。そのため、オブジェクトの名前をドロップまたは変更すると、コネクタは破損し動作しなくなります。

   ウェアハウスの名前を変更する代わりに、 UPDATE_WAREHOUSE ストアドプロシージャを使用して、コネクタが使用するウェアハウスを変更します。

8. CALL コマンドを使用して SET_CONNECTION_CONFIGURATION という名前のストアドプロシージャを呼び出し、ServiceNow®インスタンスへの接続を構成します。

   CALL SET_CONNECTION_CONFIGURATION({
     'service_now_url': '<servicenow_base_url>',
     'secret': '<secret_name>',
     'external_access_integration': '<external_access_integration_name>'
   })
   

   Copy

   条件:

   servicenow_base_url

   コネクタが使用する ServiceNow®インスタンスの URL を指定します。URL は次の形式にする必要があります。

   https://<servicenow_instance_name>.service-now.com
   

   Copy

   secret_name

   ServiceNow®への認証用の認証情報を含むシークレットオブジェクト（以前に作成したシークレット） の完全修飾名を指定します。

   シークレットオブジェクトの完全修飾名を次の形式で指定する必要があります。

   <database_name>.<schema_name>.<secret_name>
   

   Copy

   データベース、スキーマ、シークレットの名前は、有効な オブジェクト識別子 である必要があります。

   external_access_integration_name

   ServiceNow®の外部アクセス統合（先に作成した外部アクセス統合） の名前を指定します。

   統合の名前は、有効な オブジェクト識別子 である必要があります。

   たとえば、次の ServiceNow®インスタンスへの接続を構成するには、次を満たしている必要があります。

   • URL https://myinstance.service-now.com がある。

   • secretsdb.apiauth.servicenow_creds_oauth_code に格納されているシークレットを使用する。

   • servicenow_external_access_integration という外部アクセス統合を使用している。

   次のコマンドを実行します。

   CALL SET_CONNECTION_CONFIGURATION({
     'service_now_url': 'https://myinstance.service-now.com',
     'secret': 'SECRETSDB.APIAUTH.SERVICENOW_CREDS_OAUTH_CODE',
     'external_access_integration': 'SERVICENOW_API_INTEGRATION'
   });
   

   Copy

   コネクタが正常に構成された場合、このストアドプロシージャは次のレスポンスを返します。

   {
     "responseCode": "OK",
     "message": "Test request to ServiceNow® succeeded.",
   }
   

   Copy

   注釈

   一度コネクタを構成すると、渡されたシークレットと外部アクセス統合の名前を変更することはできません。コネクタはオブジェクトを名前で参照します。そのため、オブジェクトの名前をドロップまたは変更すると、コネクタは破損し動作しなくなります。

9. FINALIZE_CONNECTOR_CONFIGURATION というストアドプロシージャを呼び出す CALL コマンドを使用して、コネクタの構成を確定します。

   CALL FINALIZE_CONNECTOR_CONFIGURATION({
     'journal_table': '<name_of_journal_table>',
     'table_name': '<name_of_audited_table>',
     'sys_id': '<sys_id_of_audited_entry>'
   })
   

   Copy

   条件:

   name_of_journal_table

   削除された記録に関する情報を含むテーブルの名前を指定します。詳細については、 ServiceNow®インスタンスの準備 をご参照ください

   削除された記録に関する情報は、削除された記録を反映するように設定したテーブルでのみ利用できることに注意してください。

   削除された記録が反映されないようにするには、この引数に null を指定します。

   name_of_audited_table

   （オプション）ジャーナルテーブルに存在し、コネクタがアクセスできる必要がある監査済みテーブル名を指定します。ジャーナルテーブルへのアクセスの検証中に、コネクタはこのテーブルに関連する監査エントリを検索します。ServiceNow®へのクエリは成功したけれども、結果が得られず、プロシージャが失敗する場合にこのオプションを提供します。コネクタの ServiceNow®ユーザーが、指定されたテーブルのすべてのエントリにアクセスできることを確認します。

   このオプションは sys_id パラメーターとは併用できません。

   sys_id_of_audited_entry

   （オプション）ジャーナルテーブルに存在し、コネクタがアクセスできる必要がある一部の監査済みテーブルのエントリの sys_id を指定します。ジャーナルテーブルへのアクセスの検証中に、コネクタはこの sys_id に関連する監査エントリを検索します。ServiceNow®へのクエリは成功したけれども、結果が得られず、プロシージャが失敗する場合にこのオプションを提供します。コネクタの ServiceNow®ユーザーが指定されたエントリにアクセスできることを確認します。

   このオプションは table_name パラメーターとは併用できません。

   コネクタが正常に開始された場合、このストアドプロシージャは次のレスポンスを返します。

   {
       "responseCode": "OK",
   }
   

   Copy

   コネクタ構成の確定中に、コネクタは以前にエクスポートされたコネクタの状態が宛先スキーマに存在するかどうかを確認しようとします。 __CONNECTOR_STATE_EXPORT テーブルが存在し、コネクタにアクセス可能な場合、コネクタは状態のインポートを試みます。インポートが正常に終了すると、エクスポートテーブルは削除されます。インポート中にエラーが発生した場合、エラーを修正した後に FINALIZE_CONNECTOR_CONFIGURATION プロシージャを再度実行できます。状態をインポートしたくない場合、またはインポートエラーを修正したくない場合は、コネクタからテーブルの所有権を譲渡し、テーブルを削除します。

新しく作成されたデータベースはコネクタのインスタンスであり、次が含まれています。

• コネクタの構成に使用するストアドプロシージャ。詳細については、 SQL ステートメントを使用したデータインジェスチョンの設定 をご参照ください。

• コネクタのログに記録されたメッセージと統計を含むビュー。詳細については、 コネクタのモニターについて をご参照ください。

コネクタアプリケーションの役割¶

ネイティブアプリケーションとして、 Snowflake Connector for ServiceNow®V2 は アプリケーションの役割 を定義します。 コネクタのロールベースアクセス制御 でご確認いただけます。

次のステップ¶

コネクタをインストールして構成したら、 ServiceNow®データのデータインジェスチョンの設定 で説明されているステップを実行します。