API Agent の使用

エンドツーエンドのAPI公開とテストには、 API Agent 。 以下は、 API Agent プラグインを使用する際に期待されることについての詳細と、エージェントがどのように動作し、エージェントで利用可能な機能を理解するために歩くことができるエンドツーエンドのフローシナリオのサンプルのセクションです。

管理者は、組織内の特定の開発者に適切なロールを割り当てて、 API Agent を有効にすることができます。 この選択的有効化によって、ツールが適切な状況下で効果的に使用されるようになる。 管理者がソースを設定した後、開発者は Visual Studio Code プラグインをインストールし、ワークスペースへの統合を開始できる。 詳細については、 API Agentのユーザーロールセクションを参照してください。

ベスト・プラクティス

API Agent エクステンションは、 Visual Studio Code でAPI管理を支援するために使用されるツールである。 適切な機能を確保するためには、エクステンション・ウィンドウの高さをいっぱいにし、少なくともウィンドウの幅の1/3を確保することが不可欠である。
ドキュメントのプロンプトを理解する
ドキュメントでコマンドを目にしたら、その正しい使い方を理解することが不可欠だ。

  1. コマンドに [apiName] のようなプレースホルダーが含まれている場合は、それを独自のテキストに置き換える必要がある。 例:

    • コマンド: Run test cases for [apiName]:[version]
    • 交換： Run test cases for bookshop-api-3:1.0
    注: コマンドを実行する際は、 [apiName] を実際のAPI名に置き換えてください。

  2. プレースホルダーに入力するには、 [@file] ：

    • 文書には次のようなプロンプトが表示されるかもしれない： remediate api [@file] using spectral-owasp ruleset. remediate api @bookstore.yaml using spectral-owasp ruleset に置き換える。

    [@file] を置き換えるには、 @ シンボルをトリガーして、 Visual Studio Code ワークスペースのファイルにアクセスする必要があります。 次に、エージェントにアップロードするファイルを選択します。

新しいセッションを開始するには
セッションをアクティブに保つには、問題を引き起こしている可能性のある一時的なデータや残留データを消去し、システムを更新して最新の状態にする必要があります。
セッションをアクティブに保ち、リフレッシュするには、以下の手順を実行する：
  1. CMD + SHIFT + Pを入力し、 Visual Studio Code コマンドパレットを開く。
  2. コマンドラインに Developer: Reload window と入力する。
  3. コマンドラインに API Agent: Logout と入力する。
    注： このコマンドはログイン・セッションを削除しますが、認証プロセスを再度行う必要があります。 しかし、ログイン情報（ pOrg, ログイン URL など）はキャッシュされたままです
  4. ログアウト後にキャッシュされたログイン情報をすべて削除するには、コマンドラインで API Agent: Clear session from workspace state and reload と入力します。
    注意： Visual Studio Code でプラグインを削除または無効化しても、キャッシュされたログイン情報は保持されます。 つまり、再度プラグインをダウンロードしたときに URL フィールドには最後に使用した URL が入力されます。
デバッグ・プロセス
デバッグのために、 Visual Studio Code のコマンドパレットには2つのエリアがある。
エクステンションの Visual Studio Code 側を表示するには、以下の手順を実行する：
  1. CMD + SHIFT + Pを入力し、 Visual Studio Code コマンドパレットを開く。
  2. コマンドラインで Show Output Channels と入力し、リストからコマンドを選択する。
  3. 出力チャンネルリストで、 API Agent Debug Logs を選択する。
  4. Visual Studio Code エクステンションは以下の情報を表示する：
    • ログインデータとセッションデータ。
    • タブ変更後の拡張機能の再初期化。
チャットウェブビュー側を表示するには、以下の手順を実行します：
  1. CMD + SHIFT + Pを入力し、 Visual Studio Code コマンドパレットを開く。
  2. コマンドラインで Developer: Open Webview Developer Tools と入力し、リストからコマンドを選択する。
  3. ウェブビューの開発者ツールで、以下の情報にアクセスできます：
    • コンソールタブ：ログとコンソール出力を見る
    • ネットワーク・タブ：RESTコールの検査
ファイルの添付とダウンロード
ファイルを添付してダウンロードするには、以下の手順に従ってください：
  1. ファイルを添付するには、 @ と入力してファイルメニューを起動し、ファイルを選択する必要があります。
    注： 最大ファイルサイズは1GBで、ファイル名にはスペースや特殊文字は使用できません。
  2. validate api @testapi.yaml のようなコマンドをコピー・アンド・ペーストした場合、 validate api のようなコマンドを削除し、 @ のようなコマンドを再入力すると、ファイルメニューが表示されます。
  3. @ と入力して表示されるファイルメニューからファイルを選択する。
  4. 次のアクションボタンにファイルへの参照が含まれている場合、例えば remediate api [@file] using spectral-owasp ruleset のように、 @ のシンボルでファイルメニューをトリガーして、 [@file] を新しく添付されたファイルに置き換える必要があります。
  5. コマンドラインのファイル名を削除するには、コマンドを削除して、 validate api を再入力する。
API Agent リロードとログアウトの問題
  • しばらくチャットを使用しなかった場合、 API Connect で使用されるトークンはその間に失効し、会話を続けると Error: Unauthorized が表示され、自動的にログアウトされます。 もう一度ログインする必要があります。
  • リソースを適切に消去するには、 Visual Studio Code 管理下のサインアウトオプションではなく、プラグイン内のログアウトオプションを使用する必要があります。
    重要： API Agent プラグインは API Assistant から名前が変更されました。 古いバージョンをお持ちの場合は、新しいバージョンをダウンロードする前に削除してください。
異なるスタックを使用する、または同じスタックで異なるユーザーでログインする
あるスタックまたはユーザーからログアウトした後、ワークスペースの状態からセッションをクリアすると、 API Agent 、別のスタックに切り替えるときに古い情報が使用され、永続性の問題が発生することがありました。
この問題を解決するには、以下のステップを実行します。
  1. 現在のスタックまたはユーザーからログアウトする。
  2. コマンドパレットで、以下のコマンドを実行する：
    API Agent: Clear session from workspace state
  3. ページを再ロードしてください。
  4. 新しいスタックまたはユーザーでログインする。