7.1 MySQL Shell でのレポート
7.1.6 組込み MySQL Shell レポート
7.1.1 MySQL Shell レポートの作成
サポートされているスクリプト言語 (JavaScript および Python) のいずれかで、MySQL Shell のユーザー定義レ ポートを作成および登録できます。 レポート機能は、同じ API フロントエンドスキームを使用して組込みレポー トおよびユーザー定義レポートを処理します。
MySQL Shell レポートの登録
レポートでは、受け入れるレポート固有のオプションのリストを指定できます。また、指定した数の追加引数を 受け入れることもできます。 レポートでは、これらの入力の両方をサポートすることも、いずれもサポートしな いこともできます。 レポートのヘルプをリクエストすると、MySQL Shell では、オプションと引数のリスト、お よびレポートの登録時に提供されるこれらの説明が提供されます。
署名
MySQL Shell レポートとして登録する Python または JavaScript 関数のシグネチャは、次のようにする必要があ ります:
Dict report(Session session, List argv, Dict options);
ここでは:
•
session は、レポートの実行に使用される MySQL Shell セッションオブジェクトです。
•
argv は、レポートに渡される追加の引数の文字列値を含むオプションのリストです。
•
options は、レポート固有のオプションとその値に対応するキー名と値を持つオプションのディクショナリで
す。
レポートタイプ
レポート関数は、登録時に使用するタイプに応じて、特定の形式でデータを返すことが期待されます:
リストタイプ 出力をリストのリストとして返します。最初のリストはカラムの名前で構成され、残りは行のコンテ ンツです。MySQL Shell では、デフォルトで出力がテーブル形式で表示されるか、\show または\watch コマンドで --vertical または --E オプションが指定されている場合は垂直形式で表示されます。 行の値 は、アイテムの文字列表現に変換されます。 行の要素数がカラム名の数より少ない場合、欠落してい る要素は NULL とみなされます。 行の要素数がカラム名の数より多い場合、余分な要素は無視されま す。 このレポートを登録するときは、「list」 タイプを使用します。
レポートタイプ 単一アイテムを含むリストとしてフリーフォーム出力を返します。MySQL Shell では、YAML を使用 してこの出力が表示されます。 このレポートを登録するときは、「report」 タイプを使用します。
印刷タイプ 出力を画面に直接出力し、出力がすでに表示されていることを示す空のリストを MySQL Shell に返し ます。 このレポートを登録するときは、「print」 タイプを使用します。
出力を提供するには、レポートの API 関数で、キー report を含むディクショナリと、返されるリスト内の各セク ション目に対して 1 つずつ JSON オブジェクトのリストを返す必要があります。 リストタイプにはリストごとに 1 つの要素を使用し、レポートタイプには単一の要素を使用し、印刷タイプには要素を使用しません。
7.1.2 MySQL Shell レポートの登録
ユーザー定義レポートを MySQL Shell に登録するには、Python の JavaScript または shell.register_report() で
shell.registerReport() メソッドをコールします。 メソッドの構文は次のとおりです:
shell.registerReport(name, type, report[, description])
ここでは:
•
name は、レポートの一意の名前を示す文字列です。
•
type は、「list」、「report」 または 「print」 のいずれかの出力形式を決定するレポートタイプを示す文字列で
す。
•
report は、レポートの起動時にコールされる関数です。
•
description は、レポートがサポートするオプション、レポートが受け入れる追加の引数、および MySQL Shell
ヘルプシステムで提供されるヘルプ情報を指定するために使用できるオプションを含むディクショナリです。
name、type および report パラメータはすべて必須です。 レポート名は次の要件を満たしている必要があります:
• MySQL Shell インストールで一意である必要があります。
• 有効なスクリプト識別子である必要があるため、最初の文字は文字またはアンダースコア文字で、その後に任 意の数の文字、数字またはアンダースコア文字が続く必要があります。
MySQL Shell レポートの永続化
• 大文字と小文字を混在させることはできますが、小文字に変換する場合は、MySQL Shell インストールで一意 である必要があります。
レポート名では、登録プロセス中や、\show および\watch コマンドを使用してレポートを実行する際に、大/小文 字は区別されません。 shell.reports オブジェクトで対応する API 関数をコールする場合、レポート名では大/小文 字が区別されます。 Python モードか JavaScript モードかにかかわらず、レポートの登録に使用された正確な名 前を使用して関数をコールする必要があります。
オプションのディクショナリには次のキーが含まれており、これらはすべてオプションです:
brief
レポートの簡単な説明。details
文字列の配列として提供されるレポートの詳細な説明。 これは、\show コマンドで\help コマンドまたは --help オプションを使用する場合に提供されます。
options
レポートが受け入れることができるレポート固有のオプション。 配列内の各ディクショナリには 1つのオプションが記述されており、次のキーが含まれている必要があります:
•
name (string、必須): 長い形式のオプションの名前。有効なスクリプト識別子である必要があり
ます。
•
brief (string、オプション): オプションの簡単な説明。
•
shortcut (string、オプション): オプションの代替名 (単一の英数字)。
•
details (文字列の配列、オプション): オプションの詳細な説明。 これは、\show コマンドで\help
コマンドまたは --help オプションを使用する場合に提供されます。•
type (string、オプション): オプションの値タイプ。 許可される値は
「string」、「bool」、「integer」 および 「float」 で、type が指定されていない場合、デフォル トは 「string」 です。 「bool」 が指定されている場合、このオプションはスイッチとして機能:
指定しない場合、false にデフォルト設定され、\show または\watch コマンドを使用してレポー トを実行する場合は true にデフォルト設定され (値は受け入れられません)、shell.reports オブ ジェクトを使用してレポートを実行する場合は有効な値が必要です。
•
required (bool、オプション): オプションが必要かどうか。 required が指定されていない場合、デ
フォルトで false に設定されます。 オプションタイプが 「bool」 の場合、required は true にで きません。•
values (文字列の配列、オプション): オプションに使用できる値のリスト。 このキーを持つこと
ができるのは、「string」 タイプのオプションのみです。 values が指定されていない場合、この オプションは任意の値を受け入れます。
argc
レポートで想定される追加の引数の数を指定する文字列。次のいずれかを指定できます:• 単一の数値として指定される引数の正確な数。
• アスタリスクとして指定されたゼロ個以上の引数。
• 引数番号の範囲。ダッシュで区切られた 2 つの数値として指定されます (例: 「1-5」)。
• 最小値で最大値が指定されていない引数番号の範囲。数値とアスタリスクで区切ります (「1-*」
など)。
7.1.3 MySQL Shell レポートの永続化
MySQL Shell レポートは、レポートに使用されるスクリプト言語と一致するように、JavaScript コードの場合は
.js のファイル拡張子、Python コードの場合は .py のファイル拡張子で保存する必要があります。 ファイル拡張
子は大/小文字が区別されません。レポートを永続化するには、MySQL Shell プラグインにレポートを追加することをお薦めします。 プラグインお よびプラグイングループは、MySQL Shell の起動時に自動的にロードされ、それらが定義および登録する関数は すぐに使用可能になります。 MySQL Shell プラグインでは、初期化スクリプトを含むファイルの名前は、言語に 応じて init.js または init.py である必要があります。 MySQL Shell プラグインの使用手順については、セクション 7.3「MySQL Shell プラグイン」 を参照してください。
かわりに、レポートを含むスクリプトを MySQL Shell ユーザー構成パスの init.d フォルダに直接格納するこ ともできます。 MySQL Shell が起動すると、.js または .py ファイル拡張子を持つ init.d フォルダにあるす
MySQL Shell レポートの例
べてのファイルが自動的に処理され、それらのファイル内の機能が使用可能になります。 (この場所では、
ファイル名は MySQL Shell には関係ありません。) デフォルトの MySQL Shell ユーザー構成パスは、Unix では ~/.mysqlsh/、Windows では %AppData%\MySQL\mysqlsh\です。 ユーザー構成パスは、環境変数
MYSQLSH_USER_CONFIG_HOME を定義することで、すべてのプラットフォームでオーバーライドできます。
7.1.4 MySQL Shell レポートの例
このユーザー定義レポートの例 sessions は、現在存在するセッションを示しています。
def sessions(session, args, options):
sys = session.get_schema('sys') session_view = sys.get_table('session') query = session_view.select(
'thd_id', 'conn_id', 'user', 'db', 'current_statement',
'statement_latency AS latency', 'current_memory AS memory') if (options.has_key('limit')):
limit = int(options['limit']) query.limit(limit) result = query.execute()
report = [result.get_column_names()]
for row in result.fetch_all():
report.append(list(row)) return {'report': report}
shell.register_report(
'sessions', 'list', sessions, {
'brief': 'Shows which sessions exist.',
'details': ['You need the SELECT privilege on sys.session view and the underlying tables and functions used by it.'], 'options': [
{
'name': 'limit',
'brief': 'The maximum number of rows to return.', 'shortcut': 'l',
'type': 'integer' }
], 'argc': '0' } )
7.1.5 MySQL Shell レポートの実行
MySQL Shell に登録されている組込みレポートおよびユーザー定義レポートは、\show または\watch コマンドを 使用して任意の対話型 MySQL Shell モード (JavaScript、Python または SQL) で実行するか、JavaScript または Python スクリプトの shell.reports オブジェクトを使用してコールできます。 パラメータを指定せずに\show コマ ンドまたは\watch コマンドを実行すると、使用可能な組込みレポートおよびユーザー定義レポートがすべてリス トされます。
Show および Watch コマンドの使用
\show および\watch コマンドを使用するには、アクティブな MySQL セッションが使用可能である必要がありま
す。\show コマンドは、組込み MySQL Shell レポートまたは MySQL Shell に登録されているユーザー定義レポートの
いずれかの名前付きレポートを実行します。 レポートでサポートされているオプションまたは追加の引数を指定 できます。 たとえば、次のコマンドは組込みレポート query を実行します。このレポートは、引数として単一の SQL ステートメントを取ります:\show query show session status
レポート名では大文字と小文字は区別されず、ダッシュとアンダースコアは同じものとして扱われます。
\show コマンドには、次の標準オプションもあります:
•
--vertical (または -E) では、テーブル形式ではなく垂直形式でリストを返すレポートの結果が表示されます。
•
--help では、指定したレポートに提供されているヘルプが表示されます。 (または、レポート機能のヘルプを表
示するレポートの名前を指定して\help コマンドを使用することもできます。)