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

OAuth の設定¶

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

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

• Snowflake Connector for ServiceNow® 内：

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

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

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

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

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

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

   • ServiceNow インスタンスが既にOAuth コード付与フローを使用していて、そのインスタンスをSnowflake Snowflake Connector for ServiceNow® コネクタで使用する場合は、クライアント 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 で、 Redirect URL field に次のように入力します。

      https://apps-api.c1.<cloud_region_id>.<cloud>.app.snowflake.com/oauth/complete-secret
      

      Copy

      条件:

      cloud_region_id

      Snowflakeアカウントのクラウドリージョンの識別子を指定します。

      cloud

      クラウドプラットフォームの識別子を指定します（例: aws、 azure、または gcp）。

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

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

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

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

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

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

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

OAuth 更新トークンの生成¶

OAuth 更新トークンを生成するには、

1. OAuth の設定 で説明されているタスクを実行したことを確認してください。

2. ServiceNow ドキュメントの REST OAuth 例 で説明されているように、 ServiceNow インスタンスの /oauth_token.do エンドポイントに HTTP リクエストを送信します。

   たとえば、curlを使用して HTTP リクエストを送信する場合は、

   curl -d "grant_type=password" --data-urlencode "client_id=<client_id>" --data-urlencode "client_secret=<client_secret>" --data-urlencode "username=<username>" --data-urlencode "password=<password>" -X POST https://<instance_name>.service-now.com/oauth_token.do
   

   Copy

   条件

   instance_name

   ServiceNow インスタンスの名前を指定します。

   client_id および client_secret

   ServiceNow エンドポイントの設定時に取得した値を指定します。

   username および password

   ServiceNow インスタンスの認証情報を指定します。

   注釈

   上記の例では、curlで data-urlencode コマンドラインフラグを使用して、 ServiceNow に送信される HTTP リクエスト内のクライアントシークレット、ユーザー名、およびパスワードを URL エンコード します。

   別のツールを使用して HTTP リクエストを送信している場合は、これらの値をリクエストで URL エンコードしていることを確認してください。

   HTTP 応答の本文には、 JSON オブジェクトが含まれています。このオブジェクトの refresh_token フィールドから更新トークンを取得します。

   {"access_token":"abcd1234","refresh_token":"cdef567","scope":"useraccount","token_type":"Bearer","expires_in":1799}
   

   Copy

セキュリティ統合の作成¶

セキュリティ統合は、Snowflakeとサードパーティ OAuth 2.0サービス間のインターフェイスを提供するSnowflakeオブジェクトです。

次の例に示すように、 CREATE SECURITY INTEGRATION コマンドを使用してセキュリティ統合を作成します。

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;

条件:

name

セキュリティ統合の名前を指定します。

client_id

前のセクションで ServiceNow から取得した Client ID フィールドの値を指定します。

client_secret

前のセクションで ServiceNow から取得した Client Secret フィールドの値を指定します。

my_instance

ServiceNow インスタンスの名前を指定します。これは、 ServiceNow インスタンスホスト名の最初の部分です。たとえば、 ServiceNow インスタンスへの URL が次の場合、

https://myinstance.service-now.com

Copy

インスタンスの名前は myinstance になります。

シークレットオブジェクトの作成¶

Snowflake Connector for ServiceNow® が認証に使用するSnowflakeシークレットオブジェクトを作成します。

Snowflakeは、 ACCOUNTADMIN ロール（コネクタのインストール、構成、実行に使用するロール）とは別に、専用のロールを使用してシークレットオブジェクトを管理することをお勧めします。Snowflakeは、シークレットオブジェクトを専用のデータベースとスキーマに格納することもお勧めします。任意のロールを選択してシークレットを管理できること、また任意のデータベースとスキーマを選択してシークレットを格納できることに注意してください。

シークレットを管理するカスタムロールを作成するには、 CREATE ROLE コマンドを使用します。ロールに付与できる権限については、 アクセス制御権限 をご参照ください。

次のセクションでは、別のデータベースとスキーマに格納され、カスタムロールによって管理されるシークレットオブジェクトを作成する方法について説明します。

ウェアハウスの作成¶

Snowflakeは、コネクタ専用の ウェアハウスを作成する ことをお勧めします。専用のウェアハウスにより、コスト管理とリソースの追跡が改善されます。リソースの追跡を容易にするために、必要に応じて専用ウェアハウスに 1 つまたは複数のタグを追加 できます。

コネクタウェアハウスの場合、SnowflakeはLサイズのマルチクラスターウェアハウスを使用することをお勧めします。

servicenow_conn_warehouse という名前のLサイズのウェアハウスを作成するには、次のコマンドを実行します。

USE ROLE accountadmin;
CREATE WAREHOUSE servicenow_conn_warehouse WAREHOUSE_SIZE = LARGE;

Copy

ServiceNow データのデータベースおよびスキーマの作成¶

次に、 ServiceNow データのデータベースとスキーマを作成します。 Snowflake Connector for ServiceNow® は、 ServiceNow データをこのデータベースとスキーマにインジェストします。

データベースとスキーマを作成するときは、次の点に注意してください。

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

• Snowflakeでインジェストされた ServiceNow データへのアクセスを制御するには、 データへのアクセスを許可するロールにスキーマに対する権限を付与 します。

データベースとスキーマを作成するには、 CREATE DATABASE と CREATE SCHEMA コマンドを実行します。

たとえば、データベース dest_db と ServiceNow データのスキーマ dest_schema を作成するには、次のコマンドを実行します。

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

Copy

ServiceNow インスタンスと通信するための API 統合の作成¶

次に、 ServiceNow インスタンスと通信するための API 統合を作成します。次の構文で CREATE API INTEGRATION コマンドを実行します。

CREATE API INTEGRATION <integration_name>
  API_ALLOWED_PREFIXES = ('https://<servicenow_instance_name>.service-now.com')
  ALLOWED_AUTHENTICATION_SECRETS = (<secret_name>)
  ENABLED = TRUE

Copy

条件:

integration_name

API 統合の名前を指定します。名前は、有効な オブジェクト識別子 である必要があります。名前は、使用するアカウントの API 統合間において一意である必要があります。

API_ALLOWED_PREFIXES = ('https://servicenow_instance_name.service-now.com')

ServiceNow インスタンスに URL を指定します。これにより、この API 統合の使用は、指定された URL を持つインスタンスに制限されます。

ALLOWED_AUTHENTICATION_SECRETS = (secret_name)

API 統合のスコープで使用できるシークレットの名前のリストを指定します。

これを シークレットオブジェクトの作成 で作成したシークレットオブジェクトの名前に設定します。

ENABLED = TRUE

この API 統合を有効にするか無効にするかを指定します。API 統合が無効になっている場合、その統合に依存する外部関数はすべて機能しません。

TRUE

統合の定義で指定されたパラメーターに基づいて統合の実行を許可します。

FALSE

メンテナンスのために統合を中断します。Snowflakeとサードパーティサービス間の統合はいずれも機能しません。

たとえば、 myinstance という名前の ServiceNow インスタンスに対して servicenow_api_integration という名前の API 統合を作成するには、次のコマンドを実行します。

USE ROLE accountadmin;
CREATE API INTEGRATION servicenow_api_integration
  API_ALLOWED_PREFIXES = ('https://myinstance.service-now.com')
  ALLOWED_AUTHENTICATION_SECRETS = (secretsdb.apiauth.servicenow_creds_pw)
  ENABLED = TRUE

Copy

コネクタのログの構成¶

Snowflake Connector for ServiceNow® は、イベントテーブルを使用してコネクタのエラーログを保存します。イベントテーブルを設定するには、 イベントテーブルの設定 ガイドに従います。イベントテーブルが設定されていない場合、ログとイベント情報は破棄されます。

コネクタ用カスタムロールの作成¶

次に、コネクタ用カスタムロールを作成し、コネクタを実行するために必要な権限をそのロールに付与します。

このロールにより、コネクタは次を実行できるようになります。

• データを取り込むためのタスクを作成し、管理する。

• 専用のウェアハウスを使用する。

• ServiceNow インスタンスに接続するために、シークレットと API 統合にアクセスする。

このロールは、コネクタによってインジェストされた ServiceNow データを含むテーブルとビューの所有者でもあります。

このロールを作成して権限を付与するには、

1. USERADMIN システムロールを使用して CREATE ROLE コマンドを実行し、データを所有するカスタムロールを作成します。たとえば、データを所有するカスタムロール connector_resources_provider を作成するには、次のコマンドを実行します。

   USE ROLE useradmin;
   CREATE ROLE connector_resources_provider;
   

   Copy

2. ACCOUNTADMIN ロールを使用して GRANT <権限> to ROLE コマンドを実行し、次の権限をカスタムロールに付与します。

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

   • 次のいずれか（両方ではない）。

     • EXECUTE MANAGED TASK

       専用ウェアハウスなしでコネクタを構成した場合は、この権限を付与します。

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

       コネクタ専用のウェアハウスを使用している場合は、この権限を付与します。

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

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

   • ServiceNow 用に作成した API 統合 に対する USAGE

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

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

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

   たとえば、 connector_resources_provider という名前のロールに次の権限を付与するには、

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

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

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

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

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

   • servicenow_api_integration 統合に対する USAGE

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

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

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

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

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

   Copy

Snowflake Connector for ServiceNow® をインストールした後、このロールをコネクタに付与します。

インジェスト開始後にインジェストされたデータにアクセスするためのより詳細に設定されたロールを別途作成することをお勧めしますが、このロールを使用してインジェストされたデータをクエリすることができ、さらに権限を追加してこのロールを拡張することができます。逆に、コネクタが必要とするオブジェクトに対するロール権限の取り消しや、取り込まれたデータを持つテーブルやビューのロール所有者の変更は許可されておらず、コネクタが破壊されます。

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

コネクタをインストールするには、

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

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

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

   USE ROLE ACCOUNTADMIN;
   

   Copy

4. コネクタのカスタムのロール（以前に作成したロール）を、 コネクタのインスタンスとして機能するデータベース に付与します。

   たとえば、 connector_resources_provider という名前のロールをデータベース my_connector_servicenow に付与するには、次のコマンドを実行します。

   GRANT ROLE connector_resources_provider TO DATABASE my_connector_servicenow;
   

   Copy

5. インストールされたデータベースに FIREWALL_CONFIGURATION データベースプロパティを設定します。ServiceNow インスタンスの URL プレフィックスを含めます。

   たとえば、データベースの名前が my_connector_servicenow で、 ServiceNow インスタンス名が my-instance の場合は、次のコマンドを実行します。

   ALTER DATABASE my_connector_servicenow SET FIREWALL_CONFIGURATION = ('https://my-instance.service-now.com')
   

   Copy

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

   USE DATABASE my_connector_servicenow;
   

   Copy

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

   CALL CONFIGURE_CONNECTION({
      'serviceNowUrl': '<servicenow_base_url>',
      'secret': '<secret_name>',
      'apiIntegrationName': '<api_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

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

   api_integration_name

   ServiceNow の API 統合（以前に作成した API 統合） の名前を指定します。

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

   たとえば、次の ServiceNow インスタンスへの接続を構成する場合です。

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

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

   • servicenow_api_integration という名前の API 統合を使用する。

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

    CALL CONFIGURE_CONNECTION({
       'serviceNowUrl': 'https://myinstance.service-now.com',
       'secret': 'SECRETSDB.APIAUTH.SERVICENOW_CREDS_OAUTH_CODE',
       'apiIntegrationName': 'SERVICENOW_API_INTEGRATION'
   });
   

   Copy

   接続が正常に構成された場合、このストアドプロシージャは次のメッセージを出力します。

   Connection configured successfully
   

   Copy

   注釈

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

8. Snowflake Connector for ServiceNow® の開始 の説明に従ってコネクタを開始します。

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

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

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

Snowflake Connector for ServiceNow® の開始と停止¶

次のセクションでは、コネクタを開始、停止、および再開する方法について説明します。

CALL START_CONNECTOR(
  '<warehouse_name>',
  '<dest_db_schema>',
  '<name_of_journal_table>',
  '<connector_role>',
);

Successfully started the |SNC|. The connector can be configured now.

CALL RESUME_CONNECTOR();

Snowflake Connector for ServiceNow® の構成およびモニターでの権限の委任¶

コネクタをインストールした後、 ACCOUNTADMIN ロールのみが構成プロシージャを実行し、コネクタのモニターに使用されるビューにアクセスできます。

これらの権限を別のロールに委任するには、 GRANT IMPORTED PRIVILEGES ON DATABASE ... TO ROLE ... コマンドを実行します。このコマンドは、次の構文を使用します。

GRANT IMPORTED PRIVILEGES ON DATABASE <connector_name> TO ROLE <connector_config_role>;

条件:

connector_name

コネクタのインスタンスとして機能するデータベースの名前 を指定します。

connector_config_role

コネクタを構成およびモニターする権限を付与するロールの名前を指定します。

たとえば、 connector_config_role という名前のカスタムロールを作成し、 my_connector_servicenow という名前のコネクタインスタンスを構成およびモニターする権限をそのロールに付与するには、次のコマンドを実行します。

USE ROLE useradmin;
CREATE ROLE connector_config_role;

USE ROLE securityadmin;
GRANT IMPORTED PRIVILEGES ON DATABASE my_connector_servicenow TO ROLE connector_config_role;

コネクタが使用するウェアハウスの変更（オプション）¶

コネクタが使用するウェアハウスを変更するか、専用のウェアハウスを追加するには、次を呼び出します。

CALL CONFIGURE_WAREHOUSE('<warehouse_name>');

Copy

条件:

warehouse_name

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

専用ウェアハウスを使用せずにコネクタを実行するように構成するには、ウェアハウス名に空の文字列を渡します。

次のステップ¶

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