https://a.storyblok.com/f/270183/1368x665/a7adde883b/25feb_dev_blog_cli-yargs.png

Vonage CLI バージョン3が一般公開されました。

最終更新日 March 4, 2025
#cli
#authentication
#devops

所要時間：1 分

あばよ、悪党ども！新しいVonage CLIが出航した！前のバージョンは？まあ、それは板を歩いて、今Davy Jonesのロッカーに眠っている。この物語は、私たちが切り替えを行うために勇敢に航海した危険な海域、私たちが発掘した変更の恵み、そしてこの壮大なオーバーホールがVonage CLIをより強力な船、より滑らかな航行、より迅速なコマンド、そして同じように初心者と塩辛い海の犬の両方に準備ができていることを示します！

さて、なぜ私は海賊のように話しているのでしょうか？なぜならVonage CLIのバージョン3が登場し、海賊をテーマにした yargsフレームワークを使って一から書き直された。この投稿では、私たちがなぜCLIを変更したのか、何が変わったのか、そしてこのオーバーホールによってCLIがどのように使いやすく、より柔軟で、新しいユーザーと熟練したプロの両方にとってより強力になったのかについて説明します。

なぜ新バージョンなのか？

以前のバージョンでは オクリフ.oclifは素晴らしいフレームワークですが、Vonage CLIはその限界にぶつかっていました。Yargsは、解析されたコマンドライン引数を受け取るハンドラ関数を作成するだけのシンプルなフレームワークを提供する。これにより、期待される引数を渡して出力を検証する必要があるため、テストが簡単になる。Yargsが扱うのはただひとつ、引数の解析だけだ。Oclifは引数を処理し、コマンドを実行し、出力を解析し、ユーザー体験をコントロールする。以前のバージョンでは、oclifプラグイン・システムは、コア・コマンドに影響を与えることなくベータ・コマンドを追加することができるので、魅力的だった。しかし、一部のユーザーがそのコマンドをインストールし損ねる可能性があり、CLIにバグがあるのではと思われ、混乱を招くことが判明した。また、プラグインの標準に従うことが難しいことも判明した。 --api-key, --apiキーまたは または--api_key.

私たちはCLIをやり直し、実用的なアプローチをとる必要があった。それぞれのコマンドについて、私たちは「誰がこれを使うのか、何のために使うのか」と問いかけた。誰が "という部分に答えるために、私たちはCLIを新しいユーザー（CLIプログラムを使うのが初めての人やVonageを使ったことがない人）やスーパーユーザーにとって簡単に使えるようにしたいと考えました。全てのコマンドは JSON か YAML を出力することができ、スーパーユーザにはスクリプトを簡単に、Vonage を初めて使うユーザにはプレーンテキストを出力することができます。私たちはまた、新しいCLIを可能な限りアクセスしやすいものにしたいと考えました。エリクソン（スウェーデンを拠点とする企業）の一員として、その理想に従おうとしました。

ということで、Vonage CLIのバージョン3に飛び込んでみよう。

インストール

インストールする前に NodeJSがインストールされている必要があります（バージョン18以上）。インストールするには npm:

npm install -g @vonage/cli

これにより vonageコマンドがシステム全体で使えるようになります。これだけだ。これでCLIを使い始める準備ができました。しかし...コマンドを実行するたびにVonageの認証情報を渡さなければなりません。CLIの設定方法については、以下を参照してください。

自動アップデート

V3には自動アップデート機能もあります。コマンドを実行すると、CLIがNPMに連絡して新しいバージョンがないかチェックします（これは1日に1回だけ実行されます）。新しいバージョンがリリースされていれば、コマンドの実行終了後にメッセージが出力されます。ホームディレクトリの .vonageフォルダにファイルが作成されます。

注：クリティカルアップデートがある場合、CLIはアップデートするまで機能しません。

構成

旧バージョンのコンフィギュレーションシステムは混乱していた。そこには vonage.jsonファイル、環境変数、渡された引数、そしてグローバル・コンフィギュレーション・ファイルがあった。それぞれの場所で異なる値を保持することができたので、コマンドを実行すると望ましくない影響を引き起こす可能性があった。そこで、シンプルにした。認証パラメーターはこの階層に従っている：コマンドに渡される引数 -> ローカルの .vonagercファイル -> グローバルな config.jsonファイル HOME/.vonage.値はまた、異なるレイヤー間でマージされます。ローカルに設定された秘密鍵と、グローバルに設定されたアプリケーションIDがあったとする。その場合、アプリケーションIDが秘密鍵とペアになっていないので、正しく認証できないかもしれません。

V3ではコンフィギュレーションが簡素化された。コンフィギュレーション値がマージされることはなくなりました。代わりに、CLIは以下の順序でコンフィグレーションをロードします：

  1. コマンドラインフラグ --api-key, --api-secret, --プライベートキーおよび --アプリID.

  2. 現在の作業ディレクトリにあるローカル設定ファイル .vonagerc.

  3. グローバル設定ファイル .vonageフォルダにあるグローバル設定ファイル ホーム/.vonage/config.json.

認証情報を保存するには vonage認証セット:

vonage auth set --api-key=<your api key> --api-secret=<your api secret>

これでAPIキーとシークレットが設定され、設定が有効であることが確認されます：

✅ Checking API Key Secret

API Key: <Your api key>
API Secret: **************

プロのアドバイス使用方法 --ローカルを使うと、現在いるディレクトリにのみ設定を保存することができます。

これで、あなたの認証情報は <あなたのホームディレクトリ>/.vonage/config.jsonに保存されます。.後で、設定したことを忘れたら vonage auth showは認証設定を出力します(そしてチェックします)。

ヒント追加 --を追加する。を追加する。

vonage auth show

Global credentials found at: /Users/manchuck/.vonage/config.json

API Key: 76009afe
API Secret: dWB**************

✅ Checking API Key Secret

一部のコマンドは、Vonageアプリケーションに対してのみ機能します。 アプリケーションに対してのみ機能します。.アプリケーションの設定は --app-idと --プライベートキー

注意: -api-key も必要です。-apiキーと --api-secretを指定する必要がある。

API Key: 76009afe
API Secret: dWB**************
App ID: 4f4d4831-1491-41d4-be82-689c78e09997
Private Key: Is Set

✅ Checking API Key Secret
✅ Checking App ID and Private Key

これで、CLIを使用する際に毎回認証情報を入力する必要がなくなった。

使用方法

すべてのコマンドをレビューするつもりはないが（コマンドは多数あり、常に追加されている）、次のコマンドを使うことができる。 --ヘルプフラグを使えば、利用可能なすべてのコマンドとその使い方を見ることができる。ここでは2つの貴重なグループを紹介しよう。

JWTコマンド

JWTコマンドは2つある： vonage jwt create、そして vonage jwt validate.(我々の cURLコード・スニペット).Validateは、APIコールを行う際に認証の問題が発生した場合に役立つ。さて、前のセクションでCLIを設定したので、次のように実行する。 vonage jwt createを実行すると、それらの認証情報が使われます：

vonage jwt create
... A created JWT token is outputted ...

また、ACLで、サブジェクトを設定し、カスタム有効期限を設定することもできる：

vonage jwt create \
--app-id='00000000-0000-0000-0000-000000000000' \
--private-key=./private.key \
--sub='Alice' \
--acl='{"paths":{"/*/rtc/**":{},"/*/users/**":{},"/*/conversations/**":{},"/*/sessions/**":{},"/*/devices/**":{},"/*/image/**":{},"/*/media/**":{},"/*/applications/**":{},"/*/push/**":{},"/*/knocking/**":{},"/*/legs/**":{}}}' \
--exp=872827200

... A created JWT token is outputted ...

ヒントMacOSでは pbcopyコマンドはクリップボードにコマンドを出力する。これは パイプを追加することで行われる。 vonage jwt create | pbcopy.

validateコマンドは、トークンがアプリケーションに正しく署名されているかどうかをチェックすることができるが、他のクレームもチェックすることができる：

vonage jwt create <JWT Token> \
--app-id='00000000-0000-0000-0000-000000000000' \
--private-key=./private.key \
--sub='Alice' \
--acl='{"paths":{"/*/rtc/**":{},"/*/users/**":{},"/*/conversations/**":{},"/*/sessions/**":{},"/*/devices/**":{},"/*/image/**":{},"/*/media/**":{},"/*/applications/**":{},"/*/push/**":{},"/*/knocking/**":{},"/*/legs/**":{}}}' \
--exp=872827200

✅ Token was signed with the correct private key
✅ Token has not expired
✅ Application Id [00000000-0000-0000-0000-000000000000] matches [00000000-0000-0000-0000-000000000000]
✅ Subject [Alice] matches [Alice]
✅ ACL matches
  ✅ [ANY]  /*/rtc/**
  ✅ [ANY]  /*/users/**
  ✅ [ANY]  /*/conversations/**
  ✅ [ANY]  /*/sessions/**
  ✅ [ANY]  /*/devices/**
  ✅ [ANY]  /*/image/**
  ✅ [ANY]  /*/media/**
  ✅ [ANY]  /*/applications/**
  ✅ [ANY]  /*/push/**
  ✅ [ANY]  /*/knocking/**
  ✅ [ANY]  /*/legs/**
✅ All checks complete! Token is valid

アプリケーション・コマンド

強調したい vonageアプリというのも、vonageアプリは最もよく使われ、今回のバージョンで大きく変わったからだ。大きな変更はアプリケーションの作成だ。以前のバージョンでは、アプリケーションを作成し、同時にすべての能力設定を行うことができました。V3では、これを2つの別々のコマンドに分けました。製品ラインを拡大するにつれて、これらすべての能力を設定するために必要なフラグの数が増えてきました。さらに、1つのケイパビリティにちょっとした変更を加えたい場合、コンフィギュレーション全体を渡すか、関係のないケイパビリティを変更してしまう危険性があります。それでは、メッセージとVerify機能が構成されたアプリケーションのセットアップ方法を説明しましょう。

まず、新しいアプリケーションを作成します：

vonage apps create "My Vonage Application"

✅ Creating Application
✅ Saving private key
Application created

Name: My Vonage Application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  None Enabled

注：V1に慣れている人は、CLIがアプリケーションの名前を生成しなくなりました。

次に vonage apps capabilities update <アプリケーションID> メッセージ:

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 messages \
--messages-inbound-url='https://example.com/messages/inboud' \
--messages-status-url='https://example.com/messages/status \
--messages-version='v1' \
--no-messages-authenticate-media

✅ Fetching Application
✅ Adding messages capability to application: My Vonage Application

Name: My Vonage Application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  MESSAGES:
	Authenticate Inbound Media: Off
	Webhook Version: v1
	Status URL: [POST] https://example.com/messages/status
	Inbound URL: [POST] https://example.com/messages/inboud

を変更するだけでVerifyを追加できる。 メッセージを ベリファイ:

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 verify \
--verify-status-url='https://example.com/verify'

✅ Fetching Application
✅ Adding verify capability to application: My Vonage Application

Name: My Vonage Application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  MESSAGES:
	Authenticate Inbound Media: Off
	Webhook Version: v1
	Status URL: [POST] https://example.com/messages/status
	Inbound URL: [POST] https://example.com/messages/inboud

  VERIFY:
	Webhook Version: v2
	Status URL: https://example.com/verify

ヒント: 値(例えば、メッセージステータスのURL)の設定を解除したい場合は を渡すことができます。を値として渡すことができます： -messages-status-url='__remove__'。

最終コメント

2025年にCLIを使うのは時代遅れだと感じるかもしれないが、ダッシュボードの認証情報を組織内の全員と共有したくないかもしれない。我々の サブアカウントAPIを使えば、API キーとシークレットを持つ個別のアカウントを作成できます。CLIプログラムも自動化プロセスを支援します。あなたのコードがvonageサービスで機能することを確信するために、ステージング環境用のテストVonageアプリケーションを作成してください。(次の vonageベリファイに注目してください)。

CLIへの新しいコマンドや機能の追加はまだ終わっていません。使用方法 --ヘルプを使用して、利用可能なすべてのコマンドとその使用方法を見ることができます。また、"Vonage CLI入門 "のページもご覧ください。 ページまたは GitHub リポジトリ

ご質問がある場合、またはあなたが作っているものを共有したい場合は、こちらをクリックしてください。

最新の開発者向けニュース、ヒント、イベント情報をお届けします。

シェア:

https://a.storyblok.com/f/270183/400x400/5003a9e2e2/chuck-reeves.png
Chuck ReevesシニアJavaScriptデベロッパー

昔、GoogleやStackOverflowが登場する前の暗黒時代に、チャックはプログラミングを学んだ。ドキュメントやソースコードだけが頼りだった時代だ。Jr.フルスタックデベロッパーとして謙虚にスタートしたチャックは、現在のデベロッパーに成長し、仲間のデベロッパーに素晴らしい製品を生み出す力を与えるツールを作り上げた。新しいツールを作っているとき以外は、山に登ったり、自転車に乗ったりしている。