AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

カスタム プラグインで Atlas CLI を拡張

Atlas CLI は、カスタム コマンドで機能を拡張できるプラグインをサポートしています。スタンドアロンバイナリにコンパイルされる、任意のプログラミング言語でプラグインを開発できます。

このチュートリアルでは、 Go と Cobra ライブラリを使用して最初の Atlas CLIプラグインを作成する手順を説明します。

既存のプラグインのインストールと管理の詳細については、atlas プラグインを参照してください。

各 Atlas CLIプラグインは2 つのコンポーネントで構成されています。

  • プラグインとそのコマンドを記述する manifest.ymlファイル

  • ユーザーがプラグインコマンドを実行するときに Atlas CLI が呼び出す実行可能バイナリ

プラグインコマンドを実行すると、Atlas CLI はマニフェストファイルを読み取り、正しいバイナリを識別し、適切な引数で実行します。プラグインバイナリはすべてのコマンド ロジックを独立して取り扱います。

始める前に、以下のものがインストールされていることを確認してください。

1

MongoDB は、 開始点として使用できるプラグインのリポジトリの例を示しています。

git clone https://github.com/mongodb/atlas-cli-plugin-example.gitcd atlas-cli-plugin-example
2

例プラグインは次の構造をしています。

atlas-cli-plugin-example/├── cmd/│ └── plugin/│ └── main.go├── internal/├── manifest.template.yml├── go.mod├── go.sum├── Makefile├── .goreleaser.yaml└── .github/ └── workflows/ └── release.yml
3

プラグイン構成を確認するには、manifest.template.yml を開いてください。

name: atlas-cli-plugin-exampledescription: this is an example pluginversion: $VERSIONgithub: owner: $GITHUB_REPOSITORY_OWNER name: $GITHUB_REPOSITORY_NAMEbinary: $BINARYcommands: example: description: Root command of the atlas cli plugin example aliases: - example-alias-1 - example-alias-2

manifest.template.yml はプラグインのマニフェストファイルを定義します。マニフェストは、プラグインが提供するコマンドと実行するバイナリを Atlas CLI に指示します。

4

プラグイン実装を確認するには、cmd/plugin/main.go を開いてください。

package main import ( "fmt" "os" "github.com/spf13/cobra") func main() { rootCmd := &cobra.Command{ Use: "example", Short: "An example Atlas CLI plugin", Run: func(cmd *cobra.Command, args []string) { fmt.Println("Hello from the Atlas CLI plugin!") }, } if err := rootCmd.Execute(); err != nil { os.Exit(1) }}

プラグインは、 コマンドの定義に Cobr を使用します。Atlas CLI がプラグイン を実行するとき、コマンド名と引数を バイナリに渡します。

5

リポジトリのルートから、プラグインバイナリをビルドし、マニフェストファイルを生成します。

go build -o bin/binary ./cmd/pluginBINARY=binary VERSION=1.0.0 \ GITHUB_REPOSITORY_OWNER=$(git remote get-url origin | sed 's/.*[:/]\(.*\)\/.*/\1/') \ GITHUB_REPOSITORY_NAME=$(basename -s .git $(git remote get-url origin)) \ envsubst < manifest.template.yml > manifest.yml

プラグインディレクトリを作成し、ファイルをコピーします。デフォルトのプラグインディレクトリはオペレーティング システムによって異なります。

PLUGIN_DIR=~/Library/Application\ Support/atlascli/plugins/atlas-cli-plugin-examplemkdir -p "$PLUGIN_DIR"cp manifest.yml bin/binary "$PLUGIN_DIR/"
6

プラグインが動作することを確認します。

atlas example

出力は次のようになります。

Hello from the Atlas CLI plugin!

独自のプラグインを作成するには、例を変更するか、最初から作成します。

  1. プラグインの名前、説明、コマンドで manifest.template.yml を更新します。

  2. Go (またはスタンドアロンバイナリにコンパイルされる任意の言語)にコマンド ロジックを実装します。

  3. バイナリ名が manifest.template.yml の binaryフィールドと一致していることを確認します。

重要

マニフェスト内のコマンド名は、既存の Atlas CLI コマンドまたは他のインストール済みプラグインのコマンドと競合してはなりません。

プラグインを配布して、他のユーザーが atlas plugin install コマンドを使用してインストールできるようにするには、次の手順に従います。

  1. GitHubリポジトリでプラグインをホストします。

  2. GoRelaser または同様のツールを使用して、複数のプラットフォーム向けにコンパイルされたバイナリを含む Github リリースを作成します。例リポジトリには、.goreleaser.yaml 構成と自動リリース用の GitHub アクション ワークフローが含まれています。

  3. セマンティック バージョン管理に従ってリリース タグを作成します(例: 、v1.0.0)。

GitHub リリースを作成すると、ユーザーはプラグインをインストールできます 。

atlas plugin install <github-owner>/<repository-name>

Goと Cobr を使用することを推奨していますが、スタンドアロンの実行可能バイナリにコンパイルされる任意の言語でプラグインを記述できます。別の言語で記述されたプラグインの例については、 GitHub のRustプラグインリポジトリの例を参照してください。

プラグインは次の要件を満たしている必要があります。

  • バイナリは、最初の引数としてコマンド名を受け入れる必要があります。

  • バイナリはスタンドアロン実行可能ファイル(外部ランタイム依存関係なし)である必要があります。

  • manifest.yml の binaryフィールドはバイナリ ファイル名と一致する必要があります。