3.3.16　Kafkaアダプタを定義する

(a)　Kafkaアダプタの要求電文フォーマット

Kafkaアダプタの要求電文フォーマットについて説明します。

Kafkaアダプタの要求電文フォーマットには，ヘッダ電文とボディ電文があります。

●ヘッダ要求電文

ヘッダ要求電文は，Kafkaアダプタの要求電文フォーマットに従って作成します。

ファイルの格納場所は「<サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Kafka\schema\adpkafka_header_send_request.xsd」です。

テキストデータは，W3CのXMLの仕様に従って指定します。XML文書で使用できない「<」，「>」，「&」などの文字を使用する場合，エスケープするか，CDATAセクションを利用する必要があります。

名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/kafka/header_send_request」です。

表3‒115　Kafkaアダプタの要求電文フォーマット（ヘッダ）

タグ名					種別	出現回数	説明
<kafka-header-send-request>					−	1回	−
	<record>				−	1回	−
		<topic>			string	1回	メッセージの送信先トピックを指定します。 指定できる文字数は249文字以下です。半角英数文字，ピリオド（.），アンダーバー（_），ハイフン（-）を使用できます。 範囲外の数値を指定した場合，および要素値が空要素の場合は送信時にエラーになります。
		<headers>			−	0または1回	−
			<header>		−	0回以上	−
				<key>	string	1回	メッセージヘッダのキーを指定します。任意の文字列を指定できます。 要素値が空要素の場合は，値に空文字を設定して，メッセージを送信します。
				<value>※1	string	0または1回	メッセージヘッダの値を指定します。 任意の文字列を指定できます。 要素値をUTF-8でバイト配列に変換した値をメッセージヘッダの値に設定してメッセージを送信します。 要素値が空要素の場合は，値に0バイトのバイト配列（長さ0の配列）を設定して，メッセージを送信します。 要素を省略した場合は，値にnullを設定して，メッセージを送信します。
		<key>※2			string	0または1回	メッセージのキーを指定します。 任意の文字列を指定できます。 要素値が空要素の場合は，値に空文字を設定して，メッセージを送信します。 要素を省略した場合は，値にnullを設定して，メッセージを送信します。
		<partition>			int	0または1回	メッセージの送信先のパーティションIDを指定します。0〜2,147,483,647までの数値を指定できます。範囲外の数値を指定した場合，および要素値が空要素の場合は，要求電文解析時にエラーになります。 要素を省略した場合は，値にnullを設定して，メッセージを送信します。
		<timestamp>			long	0または1回	メッセージのタイムスタンプを指定します。0〜9,223,372,036,854,775,807までの数値を指定できます。 基点からミリ秒で時間を設定します。 要素を省略した場合は，トピックのデフォルトの設定では，メッセージの送信時刻（基点からのミリ秒単位の時間）がタイムスタンプに付与されます。トピックの設定の詳細については，Apache Kafkaの公式ドキュメントを参照してください。 範囲外の数値を指定した場合，および要素値が空要素の場合は，要求電文解析時にエラーになります。

（凡例）

−：該当する項目はありません。

注※1

value要素に設定した文字列を，バイト配列に変換し，メッセージのヘッダの値に設定してKafkaに送信します。バイト配列を文字セット「UTF-8」を使用して変換します。

注※2

送信したいkeyのデータ型に応じてproducer.key.serializerにシリアライズクラスを設定する必要があります。

例えば，送信データが文字列の場合に，producer.key.serializerにByteArraySerializerを指定するなど，producer.key.serializerに送信データと対応していない値を指定したときの動作は保証しません。key要素の送信データとシリアライズクラスとの対応については，表3-116を参照してください。

　

key要素の送信データとシリアライズクラスとの対応を次に示します。

表3‒116　key要素の送信データとシリアライズクラスとの対応

送信データ	producer.key.serializerの値
バイナリ形式（hexBinary，base64Binary）	ByteArraySerializer
文字列	StringSerializer

producer.key.serializerにByteArraySerializerを指定した場合，ヘッダ要求電文のメッセージのkey要素に指定した値をadpkafka.request.record.binary.decodingに指定したデコード形式でデコードし，Kafkaに送信するため，producer.key.serializerに指定する値は，adpkafka.request.record.binary.decodingに指定したデコード形式に合わせる必要があります。形式が異なる場合の動作は保証されません。

producer.key.serializerおよびadpkafka.request.record.binary.decodingの詳細については，マニュアル「サービスプラットフォーム リファレンス」の「3.13.1　Kafkaアダプタ定義ファイル」を参照してください。

●ボディ要求電文

ボディ要求電文はユーザが任意に作成します。

ボディ要求電文で指定された内容は，Kafkaのproducer.value.serializerの指定に基づいてバイト配列化され，ヘッダ要求電文で指定した項目と共にProducer APIを使用してKafkaに送信されます。

ボディ要求電文は，producer.value.serializerで指定したシリアライズクラスに対応した形式で作成してください。

例えば，要求電文形式がBinaryの場合に，producer.key.serializerにStringSerializerを指定するなど，要求電文形式と対応していない値を指定したときは，送信要求実行時にエラーを出力し，処理が終了します。

要求電文形式とシリアライズクラスとの対応について次に示します。

表3‒117　要求電文形式とシリアライズクラスとの対応

要求電文形式※1	送信データ	producer.value.serializerの値	リクエスト電文の例
XML	XML形式※2	StringSerializer	<userdata> 　　<dataA>dataA</dataA> 　　<dataB>dataB</dataB> </userdata>
	JSON形式
Binary	CSV形式のデータ	ByteArraySerializer	data, data, data
	文字列		data
	バイナリデータ		0x64 0x61 0x74 0x61
Any	文字列	ByteArraySerializer	data
	バイナリデータ		0x64 0x61 0x74 0x61

注※1

要求電文形式がXMLの場合はXMLスキーマ，Binaryの場合はバイナリフォーマット定義で作成します。

注※2

文字セットは「UTF-8」固定です。

producer.value.serializerの指定方法の詳細については，マニュアル「サービスプラットフォーム リファレンス」の「3.13.1　Kafkaアダプタ定義ファイル」を参照してください。

(b)　Kafkaアダプタの応答電文フォーマット

Kafkaアダプタの応答電文フォーマットについて説明します。

ファイルの格納場所は「<サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Kafka\schema\adpkafka_send_response.xsd」です。応答電文フォーマットの形式にはXML形式を使用してください。

名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/kafka/send_response」です。

(a)　Kafkaアダプタ定義ファイル

Kafkaアダプタ定義ファイルは，サービスプラットフォームが提供するテンプレートファイルを利用して編集します。

Kafkaアダプタ定義ファイルの編集手順を示します。

1. サービスアダプタ定義画面（詳細）の［独自定義ファイル］で「adpkafka.properties」を選択し，［編集］ボタンをクリックします。

   Kafkaアダプタ定義ファイルを編集するためのエディタが起動します。

2. エディタ上でKafkaアダプタ定義ファイルを編集します。

   Kafkaアダプタ定義ファイルで編集できる定義内容については，マニュアル「サービスプラットフォーム リファレンス」の「3.13.1　Kafkaアダプタ定義ファイル」を参照してください。

3. Eclipseのメニューから［ファイル］−［保存］を選択し，定義内容を保存します。

(b)　Kafkaアダプタ実行環境プロパティファイル

Kafkaアダプタ実行環境プロパティファイルの設定方法を次に示します。

1. テンプレートファイル（<サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Kafka\config\templates\serviceid.properties）をコピーして，次のディレクトリに格納します。

   全HCSCサーバ共通の定義の場合

   <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Kafka\config

   特定のHCSCサーバ用の定義の場合

   サブディレクトリ<HCSCサーバ名>を作成して格納してください。Windowsの場合，HCSCサーバ名の大文字・小文字は区別されます。

   <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Kafka\config\<HCSCサーバ名>

2. コピーしたテンプレートファイルのファイル名を「<サービスID^※>.properties」に変更します。

3. 定義内容を編集して保存します。

   Kafkaアダプタ実行環境プロパティファイルで編集できる定義内容については，マニュアル「サービスプラットフォーム リファレンス」の「6.17.1　Kafkaアダプタ実行環境プロパティファイル」を参照してください。

注※

サービスIDは，Kafkaアダプタを新規に追加するときにサービスアダプタ定義画面で指定する任意の文字列です。

(c)　Kafkaアダプタ実行環境共通プロパティファイル

Kafkaアダプタ実行環境共通プロパティファイルの設定方法を次に示します。

1. テンプレートファイル（<サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Kafka\config\templates\adpkafkacom.properties）をコピーして，次のディレクトリに格納します。

   全HCSCサーバ共通の定義の場合

   commonディレクトリはユーザが作成してください。

   <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Kafka\config\common

   特定のHCSCサーバ用の定義の場合

   サブディレクトリ<HCSCサーバ名>と「common」はユーザが作成してください。Windowsの場合，HCSCサーバ名の大文字・小文字は区別されます。

   <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Kafka\config\<HCSCサーバ名>\common

   ファイル名は変更しないでください。

2. 定義内容を編集して保存します。

   Kafkaアダプタ実行環境プロパティファイルで編集できる定義内容については，マニュアル「サービスプラットフォーム リファレンス」の「6.17.2　Kafkaアダプタ実行環境共通プロパティファイル」を参照してください。