重要
このページの日本語コンテンツは古くなっている可能性があります。最新の英語版コンテンツをご覧になるには、こちらをクリックしてください。
ServiceNow Source Connector for Confluent Cloud¶
注釈
Confluent Platform 用にコネクターをローカルにインストールする場合は、「ServiceNow Source Connector for Confluent Platform」を参照してください。
Kafka Connect ServiceNow Source Connector は、ServiceNow テーブル（ServiceNow のドキュメント を参照）での追加や変更をポーリングし、これらの変更を Apache Kafka® にリアルタイムで移動するために使用されます。コネクターは、ServiceNow Table API に対する範囲クエリを使用して ServiceNow テーブルからデータを消費し、Kafka のトピックを追加またはアップデートします。
機能¶
ServiceNow Source Connector では、次の機能がサポートされています。
- トピックの自動作成: このコネクターは Kafka トピックを自動的に作成できます。
- 少なくとも 1 回のデリバリー: コネクターによって、レコードが Kafka のトピックに少なくとも 1 回は配信されることが保証されます。
- 自動再試行: ネットワーク障害が発生した場合、コネクターは自動的にリクエストを再試行します。再試行の回数はプロパティ
retry.max.timesで管理します。各再試行間隔には指数関数的バックオフが毎回追加されます。 - 柔軟性: スループットの制限を強制する 2 つのパラメーター
batch.max.rowsとpoll.interval.sを構成できます。10000件のレコードと30秒のポーリング間隔がデフォルトです。所定の間隔内に大量のアップデートが発生した場合は、構成可能なバッチサイズに従ってレコードのページネーションがコネクターにより行われます。ServiceNow での精度は 1 秒単位であるため、ServiceNow コネクターではpoll.interval.s構成プロパティの最小設定として 1 秒がサポートされています。 - Supports one task: コネクターは、1 つのタスクのみの実行をサポートしています。つまり、1 つのテーブルが 1 つのタスクにより処理されます。
- サポートされるデータフォーマット: このコネクターは、Avro、JSON スキーマ（JSON-SR）、Protobuf、および JSON（スキーマレス）出力フォーマットをサポートします。スキーマレジストリ ベースのフォーマット（Avro、JSON スキーマ、Protobuf など）を使用するには、Schema Registry を有効にしておく必要があります。詳細については、「スキーマレジストリ Enabled Environments」を参照してください。
Connect 用の Confluent Cloud API の使用に関する詳細とサンプルについては、「Confluent Cloud API for Connect」セクションを参照してください。
制限¶
以下の情報を確認してください。
- コネクターの制限事項については、ServiceNow Source Connector の制限事項を参照してください。
- 1 つ以上の Single Message Transforms（SMT）を使用する場合は、「SMT の制限」を参照してください。
- Confluent Cloud Schema Registry を使用する場合は、「スキーマレジストリ Enabled Environments」を参照してください。
クイックスタート¶
このクイックスタートを使用して、Confluent Cloud ServiceNow Source Connector の利用を開始することができます。このクイックスタートでは、コネクターを選択し、イベントをストリーミングするようにコネクターを構成するための基本的な方法について説明します。
- 前提条件
- アマゾンウェブサービス （AWS）、Microsoft Azure （Azure）、または Google Cloud Platform （GCP）上の Confluent Cloud クラスターへのアクセスを許可されていること。
- Confluent CLI がインストールされ、クラスター用に構成されていること。「Confluent CLI のインストール」を参照してください。
- スキーマレジストリ ベースのフォーマット（Avro、JSON_SR（JSON スキーマ）、Protobuf など）を使用するには、Schema Registry を有効にしておく必要があります。詳細については、「スキーマレジストリ Enabled Environments」を参照してください。
- ServiceNow インスタンスの URL、テーブル名、およびコネクターの認証の詳細情報が必要です。詳細については、ServiceNow のドキュメント を参照してください。
Confluent Cloud Console の使用¶
ステップ 1: Confluent Cloud クラスターを起動します。¶
インストール手順については、「Quick Start for Confluent Cloud」を参照してください。
ステップ 2: コネクターを追加します。¶
左のナビゲーションメニューの Data integration をクリックし、Connectors をクリックします。クラスター内に既にコネクターがある場合は、+ Add connector をクリックします。
Step 4: Enter the connector details.¶
注釈
- すべての 前提条件 を満たしていることを確認してください。
- アスタリスク ( * ) は必須項目であることを示しています。
At the Add ServiceNow Source Connector screen, complete the following:
- Select the way you want to provide Kafka Cluster credentials. You can
choose one of the following options:
- Global Access: Allows your connector to access everything you have access to. With global access, connector access will be linked to your account. This option is not recommended for production.
- Granular access: Limits the access for your connector. You will be able to manage connector access through a service account. This option is recommended for production.
- Use an existing API key: Allows you to enter an API key and secret part you have stored. You can enter an API key and secret (or generate these in the Cloud Console).
- Click Continue.
- Add the ServiceNow authentication details:
- ServiceNow Instance URL: The ServiceNow instance URL.
- ServiceNow table name: The ServiceNow table name.
- ServiceNow Username: The ServiceNow basic authentication username.
- ServiceNow Password: The ServiceNow basic authentication password.
- Click Continue.
Add the following details:
- Select the output record value format (data going to the Kafka topic): AVRO, JSON, JSON_SR (JSON Schema), or PROTOBUF. Schema Registry must be enabled to use a スキーマレジストリ-based format (for example, Avro, JSON Schema, or Protobuf). For more information, see スキーマレジストリ Enabled Environments.
Show advanced configurations
HTTP request timeout (ms): HTTP request timeout in milliseconds.
Maximum number of times to retry request: Maximum number of times to retry request.
Poll interval (ms)t: Frequency in seconds to poll for new data in each table. The minimum poll interval is one second and the maximum poll interval is 60 seconds.
Max rows per batch: Maximum number of rows to include in a single batch when polling for new data. This setting can be used to limit the amount of data buffered internally in the connector.
Starting time in UTC (yyyy-MM-dd): Time to start fetching all updates/creation. Default uses the time connector launched. Note that the time is in UTC and has required format: yyyy-MM-dd.
Transforms and Predicates: For more details, see the Single Message Transforms (SMT) documentation.
For all property values and definitions, see 構成プロパティ .
Click Continue.
Based on the number of topic partitions you select, you will be provided with a recommended number of tasks.
- To change the number of tasks, use the Range Slider to select the desired number of tasks.
- Click Continue.
Verify the connection details by previewing the running configuration.
After you've validated that the properties are configured to your satisfaction, click Launch.
コネクターのステータスが Provisioning から Running に変わります。
Step 5: Check for records.¶
レコードが Kafka のトピックに生成されていることを確認します。
Connect 用の Confluent Cloud API の使用に関する詳細とサンプルについては、「Confluent Cloud API for Connect」セクションを参照してください。
Confluent CLI の使用¶
以下の手順に従うと、Confluent CLI を使用してコネクターをセットアップし、実行できます。
注釈
- すべての 前提条件 を満たしていることを確認してください。
- コマンド例では Confluent CLI バージョン 2 を使用しています。詳細については、「Confluent CLI v2 への移行 <https://docs.confluent.io/confluent-cli/current/migrate.html#cli-migrate>`__」を参照してください。
ステップ 2: コネクターの必須の構成プロパティを表示します。¶
以下のコマンドを実行して、コネクターの必須プロパティを表示します。
confluent connect plugin describe <connector-catalog-name>
例:
confluent connect plugin describe ServiceNowSource
出力例:
Following are the required configs:
connector.class: ServiceNowSource
name
kafka.auth.mode
kafka.api.key
kafka.api.secret
kafka.topic
output.data.format
servicenow.url
servicenow.table
servicenow.user
servicenow.password
tasks.max
ステップ 3: コネクターの構成ファイルを作成します。¶
コネクター構成プロパティを含む JSON ファイルを作成します。以下の例は、コネクターの必須プロパティを示しています。
{
"connector.class": "ServiceNowSource",
"name": "ServiceNowSource_0",
"kafka.auth.mode": "KAFKA_API_KEY",
"kafka.api.key": "****************",
"kafka.api.secret": "************************************************",
"kafka.topic": "<topic-name>",
"output.data.format": "AVRO",
"servicenow.url": "<instance-URL>",
"servicenow.table": "<table-name>",
"servicenow.user": "<username>",
"servicenow.password": "<password>",
"tasks.max": "1",
}
以下のプロパティ定義に注意してください。
"connector.class": コネクターのプラグイン名を指定します。"name": 新しいコネクターの名前を設定します。
"kafka.auth.mode": 使用するコネクターの認証モードを指定します。オプションはSERVICE_ACCOUNTまたはKAFKA_API_KEY（デフォルト）です。API キーとシークレットを使用するには、構成プロパティkafka.api.keyとkafka.api.secretを構成例（前述）のように指定します。サービスアカウント を使用するには、プロパティkafka.service.account.id=<service-account-resource-ID>に リソース ID を指定します。使用できるサービスアカウントのリソース ID のリストを表示するには、次のコマンドを使用します。confluent iam service-account list
例:
confluent iam service-account list Id | Resource ID | Name | Description +---------+-------------+-------------------+------------------- 123456 | sa-l1r23m | sa-1 | Service account 1 789101 | sa-l4d56p | sa-2 | Service account 2
"kafka.topic": データの送信先となるトピック名を入力します。"output.data.format": 出力データフォーマット（ Kafka トピックに送られるデータ）として AVRO、JSON_SR（JSON スキーマ）、PROTOBUF、または JSON（スキーマレス）を入力します。スキーマレジストリ ベースのフォーマット（Avro、JSON_SR（JSON スキーマ）、Protobuf など）を使用するには、Schema Registry を有効にしておく必要があります。詳細については、「スキーマレジストリ Enabled Environments」を参照してください。"servicenow.<>": インスタンスの URL、テーブル名、およびコネクターの認証の詳細情報を入力します。詳細については、ServiceNow のドキュメント を参照してください。インスタンスの URL は、https://dev1000.service-now.com/のように入力します。"tasks.max": このコネクターで使用する タスク の数を入力します。このコネクターは、1 つのタスクのみの実行をサポートしています。つまり、1 つのテーブルが 1 つのタスクにより処理されます。
Single Message Transforms: CLI を使用する SMT の追加の詳細については、Single Message Transforms（SMT） のドキュメントを参照してください。
すべてのプロパティの値と説明については、「構成プロパティ」を参照してください。
ステップ 4: プロパティファイルを読み込み、コネクターを作成します。¶
以下のコマンドを入力して、構成を読み込み、コネクターを起動します。
confluent connect create --config <file-name>.json
例:
confluent connect create --config servicenow-source-config.json
出力例:
Created connector ServiceNowSource_0 lcc-do6vzd
ステップ 5: コネクターのステータスを確認します。¶
以下のコマンドを入力して、コネクターのステータスを確認します。
confluent connect list
出力例:
ID | Name | Status | Type | Trace
+------------+-------------------------------+---------+--------+-------+
lcc-do6vzd | ServiceNowSource_0 | RUNNING | source | |
ステップ 6: レコードを確認します。¶
レコードが Kafka のトピックに生成されていることを確認します。
Connect 用の Confluent Cloud API の使用に関する詳細とサンプルについては、「Confluent Cloud API for Connect」セクションを参照してください。
構成プロパティ¶
このコネクターでは、以下のコネクター構成プロパティを使用します。
データへの接続方法（How should we connect to your data?）¶
nameコネクターの名前を設定します。
- 型: string
- 指定可能な値: 最大 64 文字の文字列
- 重要度: 高
Kafka クラスターの認証情報（Kafka Cluster credentials）¶
kafka.auth.modeKafka の認証モード。KAFKA_API_KEY または SERVICE_ACCOUNT を指定できます。デフォルトは KAFKA_API_KEY モードです。
- 型: string
- デフォルト: KAFKA_API_KEY
- 指定可能な値: KAFKA_API_KEY、SERVICE_ACCOUNT
- 重要度: 高
kafka.api.key- 型: password
- 重要度: 高
kafka.service.account.idKafka クラスターとの通信用の API キーを生成するために使用されるサービスアカウント。
- 型: string
- 重要度: 高
kafka.api.secret- 型: password
- 重要度: 高
データの送信先トピック（Which topic do you want to send data to?）¶
kafka.topicデータの書き込み先トピック名を指定します。
- 型: string
- 重要度: 高
出力メッセージ（Output messages）¶
output.data.formatKafka 出力レコード値のフォーマットを設定します。指定可能なエントリは、AVRO、JSON_SR、PROTOBUF、または JSON です。スキーマベースのメッセージフォーマット（AVRO、JSON_SR、PROTOBUF など）を使用する場合は、Confluent Cloud Schema Registry を構成しておく必要がある点に注意してください
- 型: string
- 重要度: 高
ServiceNow の詳細（ServiceNow details）¶
servicenow.urlServiceNow インスタンスの URL。
- 型: string
- 重要度: 高
servicenow.tableServiceNow テーブル名。
- 型: string
- 重要度: 高
servicenow.userServiceNow の基本認証のユーザー名。
- 型: string
- 重要度: 高
servicenow.passwordServiceNow の基本認証のパスワード。
- 型: password
- 重要度: 高
connection.timeout.msHTTP リクエストのタイムアウト（ミリ秒）。
- 型: int
- デフォルト: 50000（50 秒）
- 重要度: 低
retry.max.timesリクエストの再試行の最大回数。
- 型: int
- デフォルト: 3
- 重要度: 低
poll.interval.s各テーブルの新しいデータをポーリングする頻度（秒）。ポーリング間隔の最小値は 1 秒、最大値は 60 秒です。
- 型: int
- デフォルト: 30
- 重要度: 中
ServiceNow のクエリ（ServiceNow query）¶
batch.max.rows新しいデータのポーリング時に単一のバッチに含める最大行数。この設定を使用して、コネクターの内部にバッファリングするデータの量を制限できます。
- 型: int
- デフォルト: 10000
- 指定可能な値: [1,...,10000]
- 重要度: 低
servicenow.sinceすべてのアップデートおよび作成のフェッチを開始する時刻。デフォルトでは、コネクターの起動時刻を使用します。UTC と yyyy-MM-dd の形式で指定する必要があります。
- 型: string
- 重要度: 中
このコネクターのタスク数（Number of tasks for this connector）¶
tasks.max- 型: int
- 指定可能な値: [1,…,1]
- 重要度: 高
次のステップ¶
参考
フルマネージド型の Confluent Cloud コネクターが Confluent Cloud ksqlDB でどのように動作するかを示す例については、「Cloud ETL のデモ」を参照してください。この例では、Confluent CLI を使用して Confluent Cloud のリソースを管理する方法についても説明しています。
