Understand APIチュートリアル1：Python API入門

最近弊社へのお問い合わせの内容で、Python APIの利用方法に関するお問い合わせが増えております。
そこで本ブログでも、Understand APIのチュートリアル記事を公開していきたいと思います。

なお、本記事は米国向けに公開されている開発元のブログ記事をベースとし、日本国内のUnderstand 7.0 APIの活用をご検討されているお客様向けに加筆・修正を加えたものとなります。

※一部の記事の内容ではUnderstand 6.5が使用されていますが、基本的な機能はUnderstand 7.0でも同様にご利用いただけます。

チュートリアル目次

第１回：Understand APIチュートリアル1：Python API入門

第２回：Understand APIチュートリアル2：最初のAPIスクリプトの作成

第３回：Understand APIチュートリアル3：Entity、References、Kind Filterとは

第４回：Understand APIチュートリアル4：字句解析（Lexer、Lexemeとは）

第５回：Understand APIチュートリアル5：グラフ

第６回：Understand APIチュートリアル6：インタラクティブレポート

Understand Python APIとは何ですか?

Understand Python APIを使用すると、独自のスクリプトを作成してカスタムレポートを作成したり、独自のメトリクスを生成したり、Understandに期待通りの成果を提供させたりすることができます。

API で提供されている関数の完全なリストは、Understandの「ヘルプ」>「Python API ヘルプ」よりいつでもご参照いただけます。

UnderstandのPython（uPython）の使用

ビルド1054以降、UnderstandにはUnderstand Python API実行用のPython（upython.exe）がバンドルされているため、APIを簡単に使い始めることができます。後述の「カスタムPythonインストール」のセクションで示している手順にしたがって、自身のローカル環境にインストールされたPythonから利用することもできますが、Understandにバンドルされている”uPython”を使用することもできます。uPythonは、Understand APIを使用するための環境設定があらかじめされている、Pythonのシンプルなラッパーです。

uPythonを使用するには、スクリプトに understand をインポートし、uPython実行可能ファイルを使用してスクリプトを実行するだけです。
以下はインタラクティブモードにおける実行例です。

c:\Program Files\SciTools\bin\pc-win64>upython 
>>> import understand 
>>> understand.version()
'6.5.1200'
>>>

uPythonは、パス環境変数に追加することで任意のディレクトリから使用できるようになります。Windowsでは、「ユーザー変数」>「環境変数」の順に選択し、「ユーザー変数」の「Path」をクリックして「編集…」をクリックし、「新規」をクリックして次のパスを貼り付けます：
C:\Program Files\SciTools\bin\pc-win64
変更を有効にするには再起動が必要になる場合があります。

カスタム Python インストール

このチュートリアルでは uPythonを使用しますが、代わりにカスタム Python ライブラリを使用することもできます。次の手順に従って、独自の Python インストールに Understandモジュールを追加する必要があります。
（関連FAQ）https://www.techmatrix.co.jp/product/understand/faq.html#api07

1. Understand 7.0以降にはPython 3.13以降が必要です。Understand 6.5にはPython 3.12以降が必要です。PythonはUnderstandと同じビット数である必要があります。そのため、Understandの64ビット版をお持ちの場合は、Python 3の64ビット版も必要になります。
2. PYTHONPATH環境変数を変更して、モジュールの場所 ( c:\Program Files\SciTools\bin\pc-win64\Python )を含めます。
3. PATH環境変数をc:\Program Files\SciTools\bin\pc-win64に編集します。
4. Linuxのみ: LD_LIBRARY_PATHをscitools/bin/linux64に設定します。
5. Understand に含まれているテスト スクリプトを実行して、API セットアップをテストします。
   python “c:\Program Files\SciTools\plugins\Scripts\Python\apiInstallTest.py”
   Understand7.0より以前のバージョンの Understand の場合は、次のコマンドを使用します。
   python “c:\Program Files\SciTools\scripts\python\api_install_test.py”
6. スクリプトにimport understandを追加します。
7. Python 3.8 以降では、次の例のように、os.add_dll_directory()関数を使用して、スクリプト自体の中で Understand インストールへのパスを指定する必要があります。

c:\python39>python
>>> import os 
>>> os.add_dll_directory("C:\\Program Files\\Scitools\\bin\\pc-win64\\") 
>>> import understand 0
>>> understand.version() 1055 
>>>

Understandプロジェクトの設定

Understand APIを使用するには、解析済のUnderstandプロジェクトが必要です。
Understandインストール後は、セットアップウィザードに従うか、「ファイル」>「新規」>「プロジェクト」を選択することで、コードから簡単にUnderstandプロジェクトを作成できます。
Understandプロジェクトの設定方法につきましては、「Understand プロジェクト作成・運用ガイド」をご確認ください。

Python で Understand API を実行する準備ができたので、チュートリアルを続行して、エンティティと参照にアクセスする方法、フィルターを適用する方法、字句解析（レクサー）を使用する方法、グラフを作成する方法、カスタムレポートを作成する方法を学習します。

今回の記事はここまでとなります。
次回の記事では実際にAPIスクリプトを作成していきます。