ノードの使い方 — Excel Readerノード

このチュートリアルでは、AgentriaのExcel Readerノードの使い方を説明します。Excel Readerノードは、XLSXファイルのシートをパースして、列名・データ行・行数を分けて返します。

このチュートリアルでは、Excelファイルをアップロードすると表の内容を構造のまま読み取る「Excel表データの読み取り」ワークフローを完成させます。

事前準備

Agentriaキャンバスへの進入方法については、🔗3ステップコアガイドをご参照ください。

XLSXファイルを1つ用意します。最初の行に列名が入っている表の形式である必要があります。Excel Readerノードは最初の行を列名として認識し、その下の行をデータとして読み取ります。

Excel Readerノードが読み取る形式は.xlsxです。旧形式の.xlsファイルは、Excelで.xlsxとして保存してからご使用ください。

以降の画面に表示される列名はサンプルファイルのものであり、ご用意されたファイルの最初の行の内容によって異なって表示されます。

このチュートリアルを完了すると、以下のことができるようになります。

1. Excel ReaderノードのExcelファイル項目にファイルタイプの変数を接続できます。

2. シートの列名をheadersとして受け取り、確認できます。

3. データ行をrowsとして受け取り、列名で値を参照できます。

4. データ行の数をcountとして受け取り、他のノードで活用できます。

5. ノードテスト（Node Test）とアビリティテスト（Ability Test）でパース結果を確認できます。

ワークフロー概要

このチュートリアルの中心はExcel Readerノードです。

Excel Readerノードは、接続されたXLSXファイルのシートをパースして3つの値を返します。最初の行の列名はheadersに、その下のデータ行はrowsに、データ行の数はcountに分かれます。表を文字列として並べるのではなく構造を保ったまま返すため、特定の列の値だけを選んで使ったり、行単位で繰り返し処理したりするのに適しています。

Excel Readerノードは「ファイル処理ツール」カテゴリに属します。処理するファイル形式に応じて、以下のノードも併せて活用できます。

CSV ReaderノードはExcel Readerノードと返却形式まで同じです。扱うファイルが.csvであれば、このチュートリアルをそのまま実践していただけます。

その他のリーダーノードも、対応するファイル形式と返却形式が異なるだけで、ファイルを接続して結果を受け取り次のノードへ渡す流れは同じです。

PDFテキストリーダーノードの詳しい使い方については、🔗PDFテキストリーダーノードガイドをご参照ください。

ステップ1：入力変数の宣言（スタートノード）

スタートノード（Start Node）をダブルクリックしてノードエディター（Node Editor）を開きます。アビリティキャンバスでは、スタートノードはAbility Inputと表示されます。

入力変数（Input Variables）領域で以下の変数を追加し、保存（Save）をクリックします。

タイプは、ファイルを1つ受け取るFileを選択します。Excel Readerノードはファイルを1つずつ処理するため、複数のファイルを格納するFilearrayは使用しません。

excel_fileは、次のステップでExcel Readerノードの入力として接続する変数です。

ステップ2：Excel Readerノードの追加

キャンバスでノード追加（Add Node）をクリックし、「ファイル処理ツール」カテゴリからExcel Readerノードをドラッグ＆ドロップ（Drag and Drop）でキャンバスに配置します。

配置したノードの名前はNew Excel Reader Node 1となります。

ステップ3：Excel Readerノードの設定

![Excelファイル項目にexcel_file変数を接続したノードエディターの画像]

New Excel Reader Node 1ノードをダブルクリックしてノードエディターを開きます。

Excel Readerノードは以下の項目を提供します。

このチュートリアルではExcelファイルのみを使用します。任意項目であるsheet_nameとevaluate_formulaは、初期状態のままにしておくと最初のシートを読み取ります。

ファイルを接続する2つの方法

Excelファイル項目は2つの方法で設定できます。

ノードに直接アップロードするには、Excelファイル項目の選択またはドラッグ＆ドロップ領域にファイルを置きます。ファイルがノードに保存されるため、スタートノードでファイルを受け取る必要はありません。

CSV Readerノード、JSON Readerノード、テキストリーダーノード、Word Readerノード、HWPX Readerノード、HTML Readerノードも同じ方法でファイルを接続します。

どちらの方法でもファイルは1つだけ接続できます。 入力変数を接続する場合は、変数のタイプをFileで宣言し、テストでもファイルを1つだけアップロードします。複数のExcelファイルを処理する必要がある場合は、ファイルの数だけExcel Readerノードを配置し、各ノードにファイルを1つずつ接続します。

このチュートリアルでは入力変数を接続する方法を使用します。 Excelファイル項目に、スタートノードのexcel_file変数をドラッグ＆ドロップで接続します。ユーザーがアップロードしたファイルをその都度処理するワークフローを作るためです。

任意項目の追加

![変数追加モーダルでsheet_nameとevaluate_formulaを選択する画像]

任意項目は最初から画面に表示されていません。使用するには、ノードエディターの変数追加（Add Variable）ボタンをクリックします。変数追加モーダルで必要な項目にチェックを入れて保存をクリックすると、ノードのオプション変数領域に該当する項目が表示されます。sheet_nameを追加するとシート名項目として表示されます。

• sheet_name ： 読み取るシートの名前を指定します。シートが複数あるファイルから特定のシートを読み取る必要がある場合に使用します。指定しない場合は最初のシートを読み取ります。

• evaluate_formula ： 数式が入っているセルをどのように返すかを決めます。Trueの場合は数式が計算された結果値を、Falseの場合は=SUM(A1:A10)のような数式の文字列自体を返します。項目を追加するとTrueでオンになった状態で始まります。

ノードが出力する値

ノードが正常に実行されると、以下の3つの値を出力します。

3つの値の関係は次のとおりです。

• headers ： シートの最初の行を列名として読み取り、配列で返します。

• rows ： 最初の行を除いた残りの行をデータとして返します。

• count ： rowsの数です。列名の行は数えません。

最初の行は列名として使用されるためrowsには含まれません。したがって、Excelの画面で見える全体の行数よりcountが1つ少なくなります。

ステップ4：エンドノードの設定

エンドノード（End Node）をダブルクリックしてノードエディターを開きます。アビリティキャンバスでは、エンドノードはAbility Outputと表示されます。

出力変数（Output Variables）領域で以下の変数を追加し、保存をクリックします。

追加したrow_list項目に、Excel Readerノードのrowsをドラッグ＆ドロップで接続します。

出力変数は、名前とタイプを自分で決めたうえで、前のノードのアウトプットのうちタイプが一致する値をドラッグ＆ドロップで接続する方式です。rowsは配列であるため、タイプにArrayを選択しました。

headersとcountも必要であれば、同じ方法で出力変数を追加して接続できます。headersは配列なのでArrayを、countは整数なのでIntegerを選択します。このチュートリアルではデータ行のみを出力します。

ステップ5：ノードテストで出力を確認

ノードエディター上部のテスト（TEST）ボタンをクリックすると、左側にテスト入力（Test Input）パネルが開きます。[Ability Input] excel_file項目に用意したXLSXファイルをドラッグ＆ドロップでアップロードし、テスト（Test）をクリックします。

アウトプット領域（Output Section）でheadersを展開すると、シートの最初の行の値が順番に並びます。以下はサンプルファイルを入れたときの結果です。

headers
├─ [0]  番号
├─ [1]  カテゴリ
├─ [2]  機能名
├─ [3]

headers
├─ [0]  番号
├─ [1]  カテゴリ
├─ [2]  機能名
├─ [3]

headers
├─ [0]  番号
├─ [1]  カテゴリ
├─ [2]  機能名
├─ [3]

rowsを展開すると、データ行が[0]から並びます。各行をさらに展開すると、[0]、[1]のようなインデックスではなく列名が表示されます。

rows
└─ [0]

rows
└─ [0]

rows
└─ [0]

ここに表示されている番号、カテゴリ、機能名はノードが定めた名前ではなく、サンプルファイルの最初の行に書かれていた値です。別のファイルを使用すると、そのファイルの最初の行の内容がそのまま列名になります。

これがExcel Readerノードの核心です。値を取り出すときにrows[0]の3番目の項目のように順番を数えるのではなく、列名で直接指定できます。後からExcelで列の順序を変更しても、ワークフローを修正する必要はありません。

![ノードテスト結果の下部でcountの値を確認する画像]

アウトプット領域の一番下でcountを確認します。rowsの最後のインデックスが[11]であればcountは12になります。インデックスは0から始まるためです。

ノードテストは、該当するノードのみを単独で実行します。前後のノードを接続していない状態でもパース結果を先に確認できるため、ワークフローを完成させる前にファイルが正しく読み込まれるかを点検する際に役立ちます。

ステップ6：アビリティテストでワークフロー全体を実行

キャンバス右下のRUN TESTボタンをクリックして、アビリティテストを実行します。

excel_file項目にXLSXファイルをアップロードしてテストを実行すると、エンドノードのrow_listにパースされたデータ行が返されることを確認できます。

参考：パース結果の特徴

セルの値のタイプが保持されます。 数字が入っている列は数値として、文字が入っている列は文字列として返されます。サンプルファイルの番号列のように数字だけが入っている列は、文字列の"1"ではなく数値の1として渡されるため、続くノードで計算にそのまま使用できます。

最初の行は常に列名として処理されます。 Excel Readerノードは、シートの最初の行を無条件に列名とみなしてファイルを読み取ります。そのため、最初の行にレポートのタイトルや案内文が入っていたり、データがすぐに始まったりするファイルは、その内容が列名の位置を占めることになり、意図した結果を得られません。

読み取るファイルの形式をあらかじめ整えておいてください。タイトル行や空白行が表の上にある場合は削除し、最初の行に列名が来るように整理してからワークフローに渡します。

シートの最初の行の値がそのままキーになります。 列名はノードが作り出すものではなく、ファイルに書かれている値をそのまま取得します。名前は変換されることなく維持され、ドキュメントURLのような名前もそのまま使用されます。

読み取るシートはsheet_nameで指定します。 指定しない場合はファイルの最初のシートを読み取ります。別のシートを読み取る必要がある場合は、変数追加でsheet_name項目を出してシート名を入力します。1つのファイルの中の複数のシートをすべて読み取る必要がある場合は、シートの数だけExcel Readerノードを配置し、各ノードのsheet_nameにそれぞれ異なるシート名を指定します。

このとき、シート名はExcelファイルのシートタブに書かれている名前と正確に一致する必要があります。 一致しない場合はノードの実行が失敗し、以下のエラーが返されます。

このエラーは、値を入力していない場合だけでなく、入力した名前のシートが見つからなかった場合にも表示されます。見つからなかった名前は、メッセージの後の括弧内に表示されます。シート名項目に値をはっきり入力したにもかかわらずこのメッセージが表示される場合は、その名前をExcelのシートタブと照らし合わせてください。空白や大文字・小文字が異なっているケースが多くあります。

数式セルは返し方を選べます。 evaluate_formulaは追加するとTrueでオンになっているため、そのままにしておくと数式が計算された結果値が返されます。数式自体を点検したり文書化したりする場合のように、=SUM(A1:A10)のような元の文字列が必要なときだけFalseに変更します。

結合されたセルは最初のマスにのみ値が入ります。 Excelで複数のマスを結合すると、画面には1つの広いマスとして表示されますが、ファイルの中では左上の最初のマスだけが値を持ち、残りのマスは空になっています。Excel Readerノードはこれをそのまま読み取るため、最初のマスには値が、残りのマスにはnullが返されます。

縦の結合と横の結合はどちらも同じ方法で処理されます。たとえばカテゴリ列の2つの行を結合した場合、最初の行にのみ値が入り、2番目の行のカテゴリはnullになります。説明と活用例の2つの列を横に結合した場合は、説明にのみ値が入り、活用例はnullになります。

行ごとに値が入っている必要のあるワークフローの場合は、結合を解除して各マスに値を入力したファイルをご使用ください。結合された表をそのまま読み取ると、途中にnullが混ざり、後続のノードで想定と異なる結果になることがあります。

データがないシートは空の結果を返します。 内容が空のシートを読み取ると、ノードはエラーを出さず、正常完了として処理し、headersとrowsに空の配列を、countに0を返します。 ワークフローが成功したかのように次のノードへ進むため、データがあるときだけ以降のステップを実行したい場合は、countが0かどうかを確認する分岐を設けてください。

行単位の繰り返し処理に適しています。 rowsは配列であるため、ループ（Loop）ノードに接続すると行ごとに同じ作業を実行できます。countは、処理する行がいくつあるかを事前に確認したり、行が1つもないときに以降のステップを飛ばす判断に活用したりできます。

表データにはリーダーノードを使用します。 同じ表であってもPDFの中に入っている場合は、PDFテキストリーダーノードがセルの内容を文字列としてつなげて返すため、行と列の区別がなくなります。表を構造のまま扱う必要がある場合は、元のデータをXLSXやCSVで用意し、Excel ReaderノードやCSV Readerノードで読み取るのが正確です。

次のステップ

🎉 おめでとうございます！ Agentriaを使って「Excel表データの読み取り」ワークフローを完成させました。

rowsをループノードに接続して行ごとに処理したり、特定の列の値だけを取り出してAIモデルノードに渡し、分類や要約を行うワークフローへ拡張したりできます。countを活用して、処理するデータがあるときだけ以降のステップを実行する構成も作ってみてください。

Agentriaは、アイデアを現実に変える可能性の空間です。

あなたのアイデア次第で、ワークフローは無限に広がります。

• より多くのアビリティ例が気になる方は 🔗アビリティガイド をご確認ください。

• エージェント例を見たい方は 🔗エージェントガイド をご確認ください。

よくある質問

Excel Readerノードとは何ですか？

Excel Readerノードは、AgentriaでXLSXファイルのシートをパースし、表の内容を構造のまま返すノードです。「ファイル処理ツール」カテゴリに属し、Excelファイル項目にファイルを接続すると、最初の行の列名をheaders配列として、その下のデータ行をrows配列として、データ行の数をcountという整数として出力します。任意項目として、読み取るシートを指定するsheet_nameと、数式セルの返し方を決めるevaluate_formulaを提供します。

Excel Readerノードはどのようなときに使いますか？

Excelで管理していた表データをワークフローの中で扱う必要があるときに使用します。商品リスト・顧客名簿・在庫状況のように、行ごとに同じ処理を繰り返す必要があるデータに適しています。表を文字列ではなく行と列の構造として受け取るため、特定の列の値だけを選んで使ったり、行単位で繰り返し処理したりできます。

headers、rows、countはそれぞれ何ですか？

headersはシートの最初の行から読み取った列名の一覧で、rowsは最初の行を除いたデータ行の一覧、countはそのデータ行の数です。最初の行は列名として使用されrowsには含まれないため、Excelの画面で見える全体の行数よりcountが1つ少なくなります。

rowsで特定の列の値はどのように参照しますか？

rowsの各要素は順番に並んだ配列ではなく、列名をキーに持つオブジェクトです。そのため、何番目の列かを数えるのではなく、列名で値を指定します。このとき使用する列名はノードが定めたものではなく、シートの最初の行に書かれている値であり、空白もそのまま維持されます。この方式であれば、後からExcelで列の順序を変更してもワークフローを修正する必要がありません。

Excel ReaderノードとPDFテキストリーダーノードはどう違いますか？

2つのノードは返却形式が異なります。PDFテキストリーダーノードは文書のテキストを1つの文字列としてつなげて返すため、PDFの中に表があってもセルの内容が順番に並ぶだけで、行と列の区別は残りません。Excel Readerノードはシートをパースして列名とデータ行を分けて返すため、表の構造がそのまま維持されます。表データを行単位で扱う必要がある場合は、元のデータをXLSXで用意してExcel Readerノードを使用します。