MySQL Shell 8.0.17 から、拡張オブジェクトを定義し、ユーザー定義の MySQL Shell グローバルオブジェクトの一部 として使用できるようにすることができます。 拡張オブジェクトを作成して登録すると、JavaScript モードと Python モードの両方で使用できます。
拡張オブジェクトは、1 つ以上のメンバーで構成されます。 メンバーには、基本データ型の値、ネイティブの JavaScript または Python で記述された関数、または別の拡張オブジェクトを指定できます。 組込みグローバルオブ ジェクト shell で提供される関数を使用して、拡張オブジェクトを構築および登録します。 MySQL Shell に登録した 後、オブジェクトにメンバーを追加することで、オブジェクトの拡張を続行できます。
注記
関数を含む拡張オブジェクトを MySQL Shell グローバルオブジェクトとして直接登録でき ます。 ただし、拡張オブジェクトを適切に管理するには、すべての拡張オブジェクトのエン トリポイントとして機能する、または少数のトップレベル拡張オブジェクトを作成し、これ らのトップレベル拡張オブジェクトを MySQL Shell グローバルオブジェクトとして登録す ると便利です。 その後、現在および将来の拡張オブジェクトを、適切なトップレベル拡張オ ブジェクトのメンバーとして追加できます。 この構造では、MySQL Shell グローバルオブ ジェクトとして登録された最上位の拡張オブジェクトによって、開発者は様々なタイミング で作成され、様々な MySQL Shell プラグインに格納された様々な拡張オブジェクトを追加 できます。
7.2.1 ユーザー定義 MySQL Shell グローバルオブジェクトの作成
拡張オブジェクトのエントリポイントとして機能する新しい MySQL Shell グローバルオブジェクトを作成するには、
まず Python の JavaScript または shell.create_extension_object() の組込み shell.createExtensionObject() 関数を使用 して、新しいトップレベル拡張オブジェクトを作成します:
shell.createExtensionObject()
次に、Python の JavaScript または shell.register_global() で shell.registerGlobal() メソッドをコールして、この最上位 の拡張オブジェクトを MySQL Shell グローバルオブジェクトとして登録します。 メソッドの構文は次のとおりです:
shell.registerGlobal(name, object[, definition])
ここでは:
•
name は、グローバルオブジェクトの名前 (およびクラス) を示す文字列です。 名前は有効なスクリプト識別子で
ある必要があるため、最初の文字は文字またはアンダースコア文字で、その後に任意の数の文字、数字またはアン ダースコア文字が続く必要があります。 この名前は MySQL Shell インストール内で一意である必要があるため、組 込み MySQL Shell グローバルオブジェクト (db, dba, cluster, session, shell, util など) の名前にすることはできず、
ユーザー定義 MySQL Shell グローバルオブジェクトにすでに使用されている名前にすることもできません。 次の例 は、グローバルオブジェクトを登録する前に名前がすでに存在するかどうかを確認する方法を示しています。
拡張オブジェクトの作成
重要
グローバルオブジェクトの登録に使用する名前は、JavaScript モードと Python モードの 両方でオブジェクトにアクセスするときにそのまま使用されます。 したがって、グローバ ルオブジェクト (ext など) には単純な一言の名前を使用することをお薦めします。 キャメ ルケースまたはスネークケース (myCustomObject など) で複合名でグローバルオブジェク トを登録する場合は、グローバルオブジェクトを使用するときに、登録された名前を指定 する必要があります。 メンバーに使用される名前のみが、言語に適した方法で処理されま す。
•
object は、MySQL Shell グローバルオブジェクトとして登録する拡張オブジェクトです。 拡張オブジェクトは一度
のみ登録できます。
•
definition は、MySQL Shell ヘルプシステムで提供されるグローバルオブジェクトのヘルプ情報を含むオプションの
ディクショナリです。 ディクショナリには、次のキーが含まれます:
•
brief (string、オプション): ヘルプ情報として提供されるグローバルオブジェクトの簡単な説明。
•
details (文字列のリスト、オプション): ヘルプ情報として提供されるグローバルオブジェクトの詳細な説明。
7.2.2 拡張オブジェクトの作成
新しい拡張オブジェクトを作成して、1 つ以上の関数、データ型またはその他の拡張オブジェクトを提供するに は、Python の JavaScript または shell.create_extension_object() で組込み shell.createExtensionObject() 関数を使用し ます:
shell.createExtensionObject()
拡張オブジェクトにメンバーを追加するには、Python の JavaScript または shell.add_extension_object_member() で 組込み shell.addExtensionObjectMember() 関数を使用します:
shell.addExtensionObjectMember(object, name, member[, definition])
ここでは:
•
object は、新しいメンバーが追加される拡張オブジェクトです。
•
name は、新しいメンバーの名前です。 名前は有効なスクリプト識別子である必要があるため、最初の文字は文字
またはアンダースコア文字で、その後に任意の数の文字、数字またはアンダースコア文字が続く必要があります。
名前は、同じ拡張オブジェクトにすでに追加されているメンバー間で一意である必要があり、メンバーが関数の 場合、名前は定義された関数の名前と一致する必要はありません。 Python を使用してメンバーを定義および追加 する場合でも、名前はキャメルケースで指定することをお薦めします。 キャメルケースでメンバー名を指定する と、MySQL Shell でネーミング規則を自動的に適用できます。MySQL Shell では、メンバーはキャメルケースを使 用して JavaScript モードで使用可能になり、スネークケースを使用して Python モードで使用可能になります。
•
member は新しいメンバーの値で、次のいずれかを指定できます:
• サポートされている基本データ型。 サポートされているデータ型は、「none」 または
「null」、「bool」、「number」(整数または浮動小数点)、「string」、「array」 および「dictionary」です。
• JavaScript または Python 関数。 インタフェース (パラメータおよび戻り値) が 表7.1「拡張オブジェクトでサ ポートされているデータ型のペア」 でサポートされているデータ型に制限されている場合は、拡張オブジェクト にメンバーとして追加される関数本体でネイティブコードを使用できます。 インタフェースで他のデータ型を使 用すると、動作が未定義になる可能性があります。
• 別の拡張オブジェクト。
•
definition はオプションのディクショナリで、メンバーのヘルプ情報を含めることができます。また、メンバーが関
数の場合は、関数が受け取るパラメータのリストです。 ヘルプ情報は、次の属性を使用して定義されます:
•
brief は、メンバーの簡単な説明です。
•
details は、文字列のリストとして提供されるメンバーの詳細な説明です。 これは、MySQL Shell \help コマンド
を使用する場合に提供されます。
このページは機械翻訳したものです。
拡張オブジェクトの作成
関数のパラメータは、次の属性を使用して定義されます:
•
parameters は、関数が受け取る各パラメータを記述するディクショナリのリストです。 各ディクショナリには 1
つのパラメータが記述され、次のキーを含めることができます:
•
name (string、必須): パラメータの名前。
•
type (string、必須): パラメータのデータ
型。「string」、「integer」、「bool」、「float」、「array」、「dictionary」または 「object」 のいずれかで す。 タイプが 「object」 の場合は、class または classes キーも使用できます。 タイプが 「string」 の場合 は、values キーも使用できます。 タイプが「dictionary」の場合は、options キーも使用できます。
•
class (文字列、オプション、データ型が 「object」 の場合に使用可能): パラメータとして許可されるオブジェ
クトタイプを定義します。
•
classes (文字列のリスト、オプション、データ型が 「object」 の場合に使用可能): パラメータとして許可され
るオブジェクトタイプを定義するクラスのリスト。 class および classes でサポートされているオブジェクト 型は、Session, ClassicSession, Table や Collection などの MySQL Shell API によって公開されるオブジェクト 型です。 このリストにない関数にオブジェクト型が渡されると、エラーが発生します。
•
values (文字列のリスト、オプション、データ型が 「string」 の場合に使用可能): パラメータに有効な値のリス
ト。 このリストにない関数に値が渡されると、エラーが発生します。
•
options (オプションのリスト、オプション、データ型が「dictionary」の場合に使用可能): パラメータに許可さ
れているオプションのリスト。 オプションではパラメータと同じ定義構造が使用されますが、オプションに
required が指定されていない場合は、デフォルトで false に設定される点が異なります。MySQL Shell では、
エンドユーザーが指定したオプションが検証され、このリストにない関数にオプションが渡されるとエラーが 発生します。 8.0.19 を介した MySQL Shell 8.0.17 では、データ型が「dictionary」の場合、このパラメータは 必須ですが、MySQL Shell 8.0.20 からはオプションです。 オプションのリストを指定せずにディクショナリを 作成した場合、エンドユーザーがディクショナリに対して指定したオプションは、検証なしで MySQL Shell に よって関数に直接渡されます。
•
required (bool、オプション): パラメータが必須かどうか。 パラメータに required が指定されていない場合は、
デフォルトで true に設定されます。
•
brief (string、オプション): ヘルプ情報として提供されるパラメータの簡単な説明。
•
details (文字列のリスト、オプション): ヘルプ情報として提供されるパラメータの詳細な説明。
拡張オブジェクトは、MySQL Shell グローバルオブジェクトとして登録されるか、MySQL Shell グローバルオブジェ クトとして登録される別の拡張オブジェクトにメンバーとして追加されるまで、構成中とみなされます。 まだ登録さ れていない拡張オブジェクトを MySQL Shell で使用しようとすると、エラーが返されます。
クロス言語に関する考慮事項
拡張オブジェクトには、Python で定義されたメンバーと JavaScript で定義されたメンバーを混在させることができま す。MySQL Shell は、一方の言語から他方の言語へのデータの転送をパラメータおよび戻り値として管理します。表 7.1「拡張オブジェクトでサポートされているデータ型のペア」 には、言語間でデータを転送する際に MySQL Shell でサポートされるデータ型と、相互の表現として使用されるペアが表示されます:
表 7.1 拡張オブジェクトでサポートされているデータ型のペア
JavaScript Python
Boolean Boolean
文字列 文字列
Integer Long
数値 Float
Null なし
Array リスト