ロボットでの Python および HCL スクリプト

ロボット アプリは、データ分析や組織の Diligent One ワークフローの一部の自動化で使用できるネイティブのクラウドベースのスクリプトを提供します。ロボットスクリプトは Python と Python のすべての補助ライブラリを Galvanize のカスタム Python ライブラリである HighBond Command Language (HCL) と組み合わせ、ドメインにフォーカスしたデータ分析と Diligent One 自動化を実現します。

ロボットは引き続き ACLScript と Analytics からアップロードされたスクリプトを使用して、データ分析とデータ自動化をサポートします。このため、ACL（Audit Command Language）への既存の投資、業界標準のプログラミング言語である Python の能力、HCL の利点を活用できます。

3 種類のロボット

ロボット アプリには 3 種類のロボットが含まれます。異なる種類のロボットはさまざまな点で類似していますが、異なるスクリプト シナリオをサポートします。

  • ACL ロボットは、アナリティクスからアップロードしたスクリプトやスケジュールされたタスクを使用した本格的なデータ分析をサポートします。スクリプトはクラウドまたはオンプレミスで実行できます。

  • HighBond ロボットは、直接ロボットで作成された Python/HCL スクリプトおよびスケジュールされたタスクを使用した本格的なデータ分析をサポートします。スクリプトはクラウドでのみ実行できます。

  • ワークフローロボット 直接ロボットで作成された Python/HCL スクリプトおよびスケジュールされたタスクまたはイベントに基づくタスクを使用して、軽量データ分析、または Diligent One ワークフローの一部の自動化をサポートします。スクリプトはクラウドでのみ実行できます。

    メモ

    ワークフローロボットにアクセスするには、Professional サブスクリプションのシステム管理者ユーザータイプが割り当てられている必要があります。

    Professional サブスクリプションを持つシステム管理者は、Diligent One イベントによってトリガーされるワークフローロボットのタスクを設定することができます。この機能は開発中であり、まだ提供されていません。

ロボット タイプの比較

ロボット タイプは 3 つありますが、ロボットによって意図されている目的が異なり、各ロボットは機能的に独立しています。同じスクリプトで ACLScript と Python/HCL を使用することはできません。

ロボットの特徴 ACL ロボット HighBond ロボット ワークフローロボット
意図されている目的 データ分析と自動化 Diligent One プラットフォームの自動化
サポートされている言語 ACLScript

  • Python

  • Pandas、NumPy、Requests、他の標準 Python ライブラリ

  • HCL カスタム Python ライブラリ（HighBond Command Language）
スクリプト オーサリングの場所 Analytics ロボット
スクリプト実行場所

  • クラウド

  • オンプレミス

  • クラウド
タスクを実行するオプション

  • スケジュール済み

  • アドホックで実行（手動）

  • Diligent One イベントによりトリガー

  • スケジュール済み

  • アドホックで実行（手動）
最長タスク実行時間

  • クラウドベースのロボット エージェント：60 分

  • オンプレミスのロボット エージェント：顧客ネットワークにより制御される

制限なし

メモ

12 時間制限を予定していますが、未実施です。

長時間実行されているタスクを停止する必要がある場合は、タスクの実行タブのタスクの実行をキャンセルをクリックすることができます。

 15 分
同時に実行できるタスクの最大数 5 5 50
必要なアクセス許可

  • ロボットのコラボレーター

  • コラボレーターのロボット ロールで制御されたアクセスの度合い（所有者、編集者、レビュー担当者）

 Professional サブスクリプションのシステム管理者ユーザー タイプ

ロボット スクリプト エディター

HighBond ロボットとワークフローロボットには、Python/HCL スクリプトをオーサリングしてインタラクティブに（手動で）実行するための統合スクリプト エディターが含まれています。スクリプト エディターは、データ サイエンス コミュニティで一般的な開発環境である Jupyter Notebook アプリでモデリングされています。スクリプト エディターは スクリプト作成に対するセルベースのアプローチ を使用します。

メモ

ロボットスクリプト エディターは、Diligent One でデータ分析と自動化を実現するために設計されています。一般的な Python スクリプト エディターまたは IDE（統合開発環境）向けではありません。このため、Jupyter や PyCharm などの IDE で提供された機能はサポートされません。一部の制限事項については、ロボット スクリプト エディターに含まれない Jupyter Notebook の機能を参照してください。

番号 説明
1

スクリプト エディターで開いているスクリプトのバージョン番号とコミットメッセージ
2

スクリプトを含むロボットの名前
3

セル コントロール：

  • セルを実行

  • 上に新しいセルを追加 (図示せず)

  • 下に新しいセルを追加（非表示）

  • 現在のセルとその上のすべてのセルを実行する (図示せず)

  • 現在のセルとその下のすべてのセルを実行する（図示せず）

  • セルを削除（非表示）
4

各セルが実行された順序を示すシーケンス インジケーター

詳細については、セルベースのスクリプト作成の主な特長を参照してください。
5

スクリプト コードを作成するためのセル

詳細については、スクリプト作成に対するセルベースのアプローチを参照してください。
6 セルの出力表示
7

上部のツールバー：

選択したセルの下に新しいセルを追加
選択したセルを上に移動する
選択したセルを下に移動する
選択したセルを実行
上から下の順序ですべてのセルを実行
スクリプト実行を停止
選択したセルを削除
スクリプトを以前にコミットされたバージョンに戻す
8

［変数］ボタン：HCL 変数を定義する［変数］ウィンドウ

詳細については、Python/HCL スクリプトの変数の使用を参照してください。
9

［AI に問い合わせる］ボタン: スクリプト作成を支援する［AI に問い合わせる］チャット パネルが開きます

詳細については、ロボットでの AI スクリプト アシスタントの使用を参照してください。
10 ［セッションファイル］ボタン（現在のファイル数を表示）: ［セッションファイル］パネルを開閉します
11

［保存してコミット］ボタン: スクリプトを保存し、新しいバージョンとしてコミットします

スクリプト作成に対するセルベースのアプローチ

スクリプト エディターの最も明らかな特徴は、複数のセルを使用して、単一のスクリプトを構成するコードの個別のブロックを含める機能です。Jupyter Notebook に慣れていない場合、スクリプト作成のセルベースのアプローチは最初は複雑に思われるかもしれません。実際には、使いやすく、すぐにわかるさまざまな利点があります。

メモ

セルはスクリプトの実行方法に影響しません。スクリプト エディターのセルの存在に関係なく、スケジュールされた自動スクリプト実行は、上から下に 1 行ずつ進みます。

セルベースのスクリプト作成の主な特長

  • 複数のセルは任意 不要な場合は、複数のセルを使用する必要がありません。単一のセルを使用して、スクリプト全体を作成して実行できます。

  • 論理分割 セルでは、自分が選択した論理ブロックにスクリプトを分割し、任意の順序またはシーケンス全体として、手動でブロックを個別に実行できます。

    たとえば、スクリプトの基本的な 4 セル編成は次のようになります。

    • 1 番目のセル Python ライブラリをインポートする

    • 2 番目のセル データをインポートする

    • 3 番目のセル データの分析を実行する

    • 4 番目のセル 分析の結果を出力する

  • セルの利点 スクリプト開発でセルを使用すると、次の利点があります。

    • 分離した個別のセルで作業して、他のセルに含まれるスクリプト ロジックを一時的に無視しながら、セルのテストと改善ができます。

    • 一度初期インポート セルを実行した後は、後続のセルを開発し、繰り返しテストをするときに、セルを実行し続ける必要がありません。

    • セルを使用して、スクリプトに視覚的な順序を設定し、異なる論理ブロック間の関係を見やすく、わかりやすくすることができます。

  • シーケンス インジケーター 各セルの横には数値インジケーターがあり、スクリプト セッション中にセルが実行された順序を示します。例：[7]。

    セルを実行するとインジケーターの数が増え、その間に実行した他のセルが考慮されます。たとえば、その間に 2 つの他のセルを実行したか、1 つの他のセルを 2 回実行した場合、インジケーターが [7] から [10] に変わります。

  • セッション メモリと保存された値 スクリプト セッション中にメモリに格納されたデータフレームと変数の値は、セルを実行した順序に基づいて更新されます。

    一般的に、スケジュールされた自動スクリプト実行中には、上から下に連続して実行されるようにセルを構築します。特定のデータフレームまたは変数の値は、スクリプト ロジックに基づいて漸進的に更新される場合があります。ばらばらの順序で手動でセルを実行した場合、データフレームまたは変数の値の現在の状態が想定とは異なり、エラーや不正確な結果が生じる可能性があります。データフレームまたは変数の値を意図された状態に復元するには、データフレームまたは変数を参照するすべてのセルを意図されている順序で再実行します。

  • セル出力の表示 デフォルトでは、セルを実行すると、セルの最後の式の出力のみが表示されます。セルの複数の式の出力を表示する場合は、別のセルに式を入力できます。ただし、スクリプト エディターで構成オプションを設定する方が便利です。

    • 次のようにセルを構成して、すべての式の出力を表示します。

      from IPython.core.interactiveshell import InteractiveShell
InteractiveShell.ast_node_interactivity = "all"

    • セルをリセットして、最後の式の出力のみを表示します。

      from IPython.core.interactiveshell import InteractiveShell
InteractiveShell.ast_node_interactivity = "last_expr"

    ヒント

    必要に応じて、構成設定を使用して、2 つのモードを切り替えることができます。セル出力の他の構成オプションについては、Jupyter または IPython のオンライン ドキュメントを参照してください。

ロボットスクリプト エディターでのキーボードショートカット

スクリプト エディターのキーボードショートカットを使用すると、スクリプトを開発する際に便利で迅速な操作が可能になります。スクリプト エディターで、使用可能なショートカットのリストを表示するには、以下のいずれかの方法を使用します。

  • Ctrl+/ を押す

  • タイトルバーで［キーボードショートカット］アイコン をクリックする

使用可能なショートカットのリストを以下に示します。

キーボードショートカット アクション
Ctrl + Shift + Enter 選択したセルを実行
Ctrl + Shift + M すべてのセルを連続して実行
Ctrl + Shift + Y 選択したセルとその上のすべてのセルを実行
Ctrl + Shift + U 選択したセルとその下のすべてのセルを実行
Ctrl + Shift + I スクリプト実行を停止

Ctrl + Shift + K

Ctrl + Shift + 上矢印

 上のセルを選択

Ctrl + Shift + J

Ctrl + Shift + 下矢印

 下のセルを選択

Ctrl + Shift + H

Ctrl + Shift + Home

 最初のセルを選択

Ctrl + Shift + L

Ctrl + Shift + End

 最後のセルを選択
Ctrl + Shift + A 上のセルを追加
Ctrl + Shift + B 下のセルを追加
Ctrl + Shift + D 選択したセルを削除
Ctrl + Shift + Z セルを上に移動
Ctrl + Shift + X セルを下に移動

ロボット スクリプト エディターに含まれない Jupyter Notebook の機能

前述のとおり、ロボット スクリプト エディターは Jupyter Notebook アプリでモデリングされています。製品の進化に伴い将来的には機能が追加される場合もありますが、現時点では次の Jupyter 機能はスクリプト エディターに含まれていません。

  • セルレベルの操作:

    • 元に戻す/やり直す操作

    • セルのコピー/貼り付け

    • セルの分割/マージ

  • セルのマークダウン（テキスト コンテンツの場合）

ログファイルへのスクリプト出力の保存

ロボットのタスクを使用して Python/HCL スクリプトを実行する場合、各タスクの実行に伴うログファイルにスクリプト出力を保存するオプションがあります。ログはタスクと同じ名前の JSON ファイルです (task_name.json)。

オプションを有効にするには、スクリプトのバージョンを保存してコミットするときに、 ［スクリプトの出力をタスクの実行ログファイルに保存］を選択します。このオプションはスクリプトのバージョンごとに個別に設定できるため、スクリプト出力を保存したい場合は、タスクが実行する特定のスクリプトのバージョンのオプションを選択してください。

スクリプト出力とは、スクリプトによって生成される stdout ストリームに含まれるすべてのものを指します。通常、stdout は、スクリプトを対話的に実行したときに、スクリプトが画面に出力したり表示したりするものです。基本的に、［スクリプトの出力をタスクの実行ログファイルに保存］を選択することで、画面に表示されるすべてのものを永久にキャプチャすることになります。このキャプチャされた出力は、スクリプトの開発時やトラブルシューティング時に確認するのに役立ちます。

追加情報:

  • オプションはタスクにのみ適用されます。ロボットスクリプト エディターで［スクリプトの出力をタスクの実行ログファイルに保存］を選択しても、オプションはロボットのタスクによって実行されるスクリプトにのみ適用されます。スクリプト エディターで対話的にスクリプトを実行する場合には、オプションは有効ではありません。

  • タスクの実行ログファイルのエラーメッセージ Python のエラーメッセージ (stderr ストリーム) は、［スクリプトの出力をタスクの実行ログファイルに保存］の設定に関係なく、常にタスクの実行ログファイルに含まれます。

  • タスクの実行ログファイルへのアクセス タスクの実行ログファイルは、［タスクの実行］タブの各タスクの実行に対して使用することができます。タスクの実行を選択すると、［タスクの実行詳細］サイド パネルでは［出力］セクションにログファイルが表示されます。このファイルをコンピューターにダウンロードしてレビューすることができます。

ACLScript から Python と HCL に移行する

Python は汎用プログラミング言語です。本来監査アナリティクス分野向けに設計されている比較的な簡単なスクリプト言語である ACLScript と比べて、Python はかなり複雑です。

ACLScript で使用可能な多数のコマンドや関数を段階的に HCL に導入する計画です。Galvanize のカスタム Python ライブラリである HCL を使い始めるには、少なくとも基本的な Python の技術が必要です。ACLScript から Python/HCL に移行することを検討している場合には、Python の導入コースを受講することをお勧めします。

Python コーディング規約

Python とHCL では、次のような ACLScript にはない特定のコーディング規約が適用されているため、それに慣れる必要があります。

  • 大文字と小文字を区別する Python および HCL 構文は大文字と小文字を区別します。ACLScript 構文では大文字と小文字が区別されません。

    Python：

    • print("Hello World!") は正常に動作します

    • PRINT("Hello World!") はエラーが発生します

  • 略語を使用しない Python および HCL の関数、メソッド、およびパラメーターの名前は正式名称で記述する必要があります。ACLScript とは異なり、略語はサポートされません。

  • インデントが解釈される Python はインデントを使用して、条件文やループなどの制御構造を実装します。インデントが正しくないと、エラーが発生します。ACLScript ではインデントは無視されます。

Python 外部ライブラリ

Python は多数の外部ライブラリまたはパッケージをサポートしています。このようなライブラリやパッケージをインストールすると、コア Python インストールおよび Python 標準ライブラリの機能を拡張できます。Python 外部ライブラリは関連コード モジュールの集合であり、コア Python および標準ライブラリが単独では実行できない特定の機能を実行するために設計されています。コア Python で実行するよりも、すばやく簡単に処理を実行できます。

メモ

Python を拡張するためにインストールできるコードの外部バンドルを指すときには、「ライブラリ」および「パッケージ」という用語は、一般的に、交換可能な意味で使用されています。Python ライブラリと Python パッケージには技術的な違いがありますが、ロボットで Python を使用するときには気にする必要はありません。

Diligent One Python に含まれる外部ライブラリ

Python の Diligent One インストールには、デフォルトで、特定の外部ライブラリが含まれているため、明示的にインストールする必要がありません。Diligent の独自の HCL Python ライブラリを除き、後続の Python/HCL スクリプトロジックで使用するには、プリインストールされたライブラリをインポートする必要があります。

Diligent One Python 環境にプリインストールされている外部ライブラリ：

ライブラリ 説明 Python インポート文
HCL HCL ライブラリ、または HighBond Command Language は、ドメインを絞ったデータ分析と Diligent One 自動化を実現する Diligent のカスタム Python ライブラリです。 不要
Pandas Pandas ライブラリは、データフレーム（スプレッドシート形式、表形式、データの二次元配列）を含め、Python におけるデータ操作およびデータ分析のための強力なツール群を提供します。

import pandas as pd

または

import pandas as pd

（任意で、ライブラリ名の簡潔なエイリアスを作成します）
NumPy NumPy ライブラリは、基本代数および統計演算、高度な数学演算、多次元配列での計算の構築と実行など、Python における高速で強力な科学演算機能を提供します。

import numpy

または

import numpy as np

（任意で、ライブラリ名の簡潔なエイリアスを作成します）
Requests Requests ライブラリは、Python で HTTP 要求を作成し、Web ベースの API と連携するための軽量の構文を提供します。

import requests

または

import requests as req

（任意で、ライブラリ名の簡潔なエイリアスを作成します）
Cryptography Cryptography ライブラリは、Python の暗号アルゴリズムを取り込むことをサポートしています。

import cryptography

または

import cryptography as crypt

（任意で、ライブラリ名の簡潔なエイリアスを作成します）

追加の外部ライブラリのインストール

HighBond ロボットは、Diligent One Python 環境にプリインストールされているライブラリにはない、追加の外部ライブラリのインストールをサポートします。追加のライブラリをインストールするには、Python パッケージのダウンロードとインストールのためのツールである pip を使用します。デフォルトでは、pip は、Python ソフトウェアのオープンソース リポジトリである Python Package Index (PyPI) からパッケージをダウンロードします。pip を使用して、別の場所からパッケージをインストールすることもできます。

たとえば、Excel ファイルおよびデータで作業するための Python ライブラリである pyexcel をインストールするには、ロボット スクリプト エディターでこのコマンドを使用します。

pip install pyexcel

外部ライブラリをインストールする場合でも、ロボット スクリプト エディターが外部ライブラリのすべての機能をサポートするという保証はありません。たとえば、特定の外部ライブラリで提供されているグラフやプロットの表示がサポートされない場合があります。

メモ

現在、ワークフロー ロボットは、追加の外部ライブラリのインストールを一切サポートしません。

HCLと Python を使用して API を操作する

ロボットで Python/HCL スクリプトを使って API（サードパーティ API と Diligent One 独自の API の両方）を操作できます。

メモ

ロボットから行う API 要求で明示的にホスト情報を指定する場合、HTTPS プロトコルを使用する必要があります。例：

  • https://openexchangerates.org/api

  • https://apis-us.highbond.com

サードパーティ API を操作する

サードパーティ API を操作するには、まずロボット スクリプト エディターで Python Requests ライブラリをインポートします。

import requests

Python の要求構文を使用して API 要求を作成し、応答を受信できます。ロボットで Python を使ってサードパーティの API 要求を行う簡単な例については、「 ロボットスクリプトと Diligent HighBond API の基本」の「第 3 部：能力を拡大する」をご覧ください。

サードパーティ API での Python の使用についての詳細説明は、本書の対象範囲外です。ただし、多数のオンライン リソースが提供されており、詳細なガイダンスが説明されています。

HighBond API を操作する

HighBond API は Diligent One プラットフォームの開発者インターフェイスです。API を使用すると、Diligent One の操作とワークフローを自動化し、レポートを作成し、Diligent One を組織の他のシステムと統合できます。

HCL に含まれているメソッドにより、HighBond API の操作が簡単になります。詳細については、HCL HighBond API メソッドを参照してください。

Python Requests ライブラリと HighBond API を使用することもできます。ただし、簡単かつシンプルにするため、HCL メソッドを使用することをお勧めします。

HighBond での Python および HCL の使用を説明する基本チュートリアルについては、ロボットスクリプトと Diligent HighBond API の基本を参照してください。