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 をクリックします。

ステップ 3: コネクターを選択します。¶

Click the ServiceNow Source connector card.

Step 4: Enter the connector details.¶

注釈

すべての前提条件を満たしていることを確認してください。
アスタリスク ( * ) は必須項目であることを示しています。

At the Add ServiceNow Source Connector screen, complete the following:

Select the topic you want to send data to from the Topics list. To create a new topic, click +Add new topic.

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>`__」を参照してください。

ステップ 1: 使用可能なコネクターをリスト表示します。¶

以下のコマンドを入力して、使用可能なコネクターをリスト表示します。

confluent connect plugin list

ステップ 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.mode

Kafka の認証モード。KAFKA_API_KEY または SERVICE_ACCOUNT を指定できます。デフォルトは KAFKA_API_KEY モードです。

型: string
デフォルト: KAFKA_API_KEY
指定可能な値: KAFKA_API_KEY、SERVICE_ACCOUNT
重要度: 高

kafka.api.key

型: password
重要度: 高

kafka.service.account.id

Kafka クラスターとの通信用の API キーを生成するために使用されるサービスアカウント。

型: string
重要度: 高

kafka.api.secret

型: password
重要度: 高

データの送信先トピック（Which topic do you want to send data to?）¶

kafka.topic

データの書き込み先トピック名を指定します。

型: string
重要度: 高

出力メッセージ（Output messages）¶

output.data.format

Kafka 出力レコード値のフォーマットを設定します。指定可能なエントリは、AVRO、JSON_SR、PROTOBUF、または JSON です。スキーマベースのメッセージフォーマット（AVRO、JSON_SR、PROTOBUF など）を使用する場合は、Confluent Cloud Schema Registry を構成しておく必要がある点に注意してください

型: string
重要度: 高

ServiceNow の詳細（ServiceNow details）¶

servicenow.url

ServiceNow インスタンスの URL。

型: string
重要度: 高

servicenow.table

ServiceNow テーブル名。

型: string
重要度: 高

servicenow.user

ServiceNow の基本認証のユーザー名。

型: string
重要度: 高

servicenow.password

ServiceNow の基本認証のパスワード。

型: password
重要度: 高

connection.timeout.ms

HTTP リクエストのタイムアウト（ミリ秒）。

型: 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 のリソースを管理する方法についても説明しています。