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	リスト
マップ	辞書

拡張オブジェクトは、両方の言語で文字どおり同じオブジェクトです。