mcpField
M
manage-api-version

manage-api-version

github.com/mulesoft開発14207 回インストール今日更新
リポジトリ

manage-api-version について

Muleプロジェクト開発者向けに、`pom.xml`のAPI依存関係のバージョンを表示、確認、変更するスキルです。Anypoint StudioのAPI Specs設定に対応し、複数APIをまとめて扱えます。現在のバージョン表示は`pom.xml`のみを参照します。

主な機能

  1. 01全APIまたは指定APIのバージョン表示
  2. 02Exchangeで利用可能なバージョンを照会
  3. 03複数のAPI依存関係をまとめて更新
  4. 04更新後のプロジェクト再スキャフォールド

活用シーン

  1. 01MuleプロジェクトのAPI依存バージョン確認
  2. 02指定APIに新しいバージョンがあるか確認
  3. 03複数API依存関係のバージョンを一括変更

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/mulesoft/mulesoft-dx --skill manage-api-version

インストール後、Claude Code で/manage-api-versionを入力して読み込まれたか確認します。

同梱ファイルscripts/fetch_versions.sh

詳細

manage-api-version

Mule プロジェクト内の 1 つ以上の API 依存関係のバージョンを読み取り、変更します。これは、Anypoint Studio の Project Properties → API Specs tab で設定する値と同じです。プロジェクト内の各 API 依存関係には、pom.xml に独自のバージョンプロパティが設定されます。プロパティ名は、依存関係の artifactId と .version を組み合わせたものです。

<properties>
  <order-api.version>1.0.0</order-api.version>
  <customer-api.version>2.1.0</customer-api.version>
</properties>

概要

このスキルは、pom.xml 内の <{artifactId}.version> プロパティを読み取り、更新します。Mule プロジェクトには 1 つ以上の API 依存関係を含めることができ、それぞれに独自のバージョンプロパティがあります。プロパティ名は常に {artifactId}.version で、artifactId は API 依存関係の Maven アーティファクト ID です。

実行できること： すべての API または名前を指定した API のバージョンを表示し、新しいバージョンが利用可能か（すべての API または指定した API について）確認するか、1 回の操作で 1 つ以上の API 依存関係のバージョンを更新し、すべての変更を適用してからプロジェクトを再スキャフォールドします。

前提条件

開始する前に、次のツールが利用可能であることを確認してください。

anypoint-cli-v4 --version   # must be v4; needs exchange asset list
mvn --version               # Maven 3.6+ for rescaffold (CHANGE path only)

anypoint-cli-v4 が見つからない場合：

npm install -g @mulesoft/anypoint-cli-v4
anypoint-cli-v4 conf username <username>
anypoint-cli-v4 conf password <password>

CHECK と CHANGE のパスでは Exchange に問い合わせます。CLI が認証されていない場合やネットワークが利用できない場合でも、表示のみの操作（DISPLAY ALL、DISPLAY SPECIFIC）は引き続き動作します。これらの操作では pom.xml のみを読み取ります。

同梱スクリプト

このスキルには、専用の scripts/ ディレクトリにシェルヘルパーが 1 つ含まれています。

スクリプト用途
scripts/fetch_versions.sh <groupId>:<artifactId>:<currentVersion> [...]1 回の実行で 1 つ以上の API 依存関係について、公開済みバージョンの全リストを取得します。エージェントが API ごとにループして anypoint-cli-v4 を逐次実行する代わりに、API ごとに Exchange へ並列で問い合わせます。使い方と出力形式の詳細は、ステップ 7b の バージョンの検出を参照してください。

「skill is now active」メッセージで指定された絶対パス（この SKILL.md があるディレクトリ）を使用し、Bash ツールで実行してください（例：<skill-dir>/scripts/fetch_versions.sh ...）。相対パスの ../scripts/... は組み立てないでください。作業ディレクトリはターンごとに変わるため、相対パスは機能しません。

実行パス

ユーザーの意図パス
現在のバージョンを表示／確認する — すべての API、または特定の API の指定なし→ DISPLAY ALL（ステップ 1 → 2 → 3）
現在のバージョンを表示／確認する — 1 つ以上の特定の API を指定→ DISPLAY SPECIFIC（ステップ 1 → 2 → 4）
新しい／更新されたバージョンが利用可能か確認する — 特定の API の指定なし→ CHECK ALL（ステップ 1 → 2 → 5）
新しい／更新されたバージョンが利用可能か確認する — 1 つ以上の特定の API を指定→ CHECK SPECIFIC（ステップ 1 → 2 → 6）
バージョンを設定、変更、調整、更新、引き上げ、切り替えする→ CHANGE（ステップ 1 → 2 → 7 → 8 → 9）

ステップ 1：プロジェクトディレクトリを特定する

次の優先順位で、利用可能な最善の手がかりを使ってプロジェクトのルートを特定します。

  1. 正確なパスが指定されている — そのまま使用します。
  2. おおよその場所またはフォルダー名が指定されている（例：「order-api プロジェクト」「ドキュメント内」「~/projects にあるもの」）— find を使って、その手がかりに一致する pom.xml を探します。一致するものが複数見つかった場合は、ユーザーに確認します。
  3. 複数のプロジェクトが開かれている／対象範囲内にあり、API 名は指定されているが、プロジェクトの手がかりがない（例：マルチルートワークスペース、またはコンテキストから参照できる pom.xml が複数ある）— 「現在／アクティブなプロジェクト」にフォールバックする前に、指定された API の <{artifactId}.version> プロパティ（または一致するハードコードされた <dependency> の artifactId）が、開いているプロジェクトの pom.xml ファイルのうち 1 つにのみ存在するか確認します。
    • 一意に一致する — そのプロジェクトをそのまま使用します。質問はしません。1 か所にしか存在しない名前は、実際には曖昧ではありません。
    • 複数のプロジェクトに一致する — ケース 5 と同様に、どのプロジェクトかを尋ねます。
    • 開いているプロジェクトのいずれにも一致しない — 「どのプロジェクトか」は尋ねません（問題がプロジェクトにあるかのように聞こえますが、おそらく API 名のほうが問題です）。代わりに、次のように伝えます。

      開いているプロジェクト（<list the open project names/paths>）のいずれにも、<name> という API が見つかりませんでした。別の API 名のことですか？それとも、現在開いていないプロジェクトにありますか？ この確認は、対象範囲内にプロジェクトが 2 つ以上ある場合にのみ行います。開いている／参照できるプロジェクトが 1 つだけの場合は、ケース 4 に進みます。識別する必要がないときに尋ねてはいけません。

  4. 現在の作業ディレクトリが示されている（例：「このプロジェクト」「現在のもの」）、または対象範囲内のプロジェクトが 1 つだけ — 現在のディレクトリに pom.xml があるか確認し、あれば使用します。
  5. 何も指定されていない — プロジェクトの手がかりも、識別に使える API 名もなく、対象範囲内に複数のプロジェクトがある — これには、2 つ以上のプロジェクトが開いていて、この会話で対象プロジェクトがまだ決まっていない場合の「API バージョンを更新して」や「更新を確認して」のような完全に一般的な依頼も含まれます。この場合、技術的にはアクティブな「現在のディレクトリ」があっても、推測してはいけません（たとえば、最後にフォーカスされていたファイルタブに対応するディレクトリなど）。名前もパスも指定されていない一般的な依頼こそ、この手順で曖昧さを確認する対象です。次のように尋ねます。

どのプロジェクトで作業しますか？フルパスやフォルダー名を指定するか、現在のディレクトリと伝えてください。

続行する前に、特定したパスに pom.xml が存在することを確認します。

会話ごとに質問できるのは 1 回までです。 ユーザーが対象プロジェクトを指定または確認したら、同じ会話内の後続の依頼でもそのプロジェクトを使用し続けます。毎回聞き直してはいけません。後からユーザーが別のプロジェクトや、別の場所に解決される API を指定した場合は、完全な確認質問を再度行わず、応答で切り替えることを伝えてからそのまま切り替えます（例：「この操作では <project> に切り替えます。」）。

停止（コンテキストからプロジェクトを特定できない場合に限ります）。

ステップ 2：操作を振り分ける

ユーザーの依頼から、意図を示すキーワードを読み取ります。

キーワード操作
get、show、find、display、what is、current — すべて／全件／特定の API 名がない→ すべて表示
get、show、find、display、what is、current — 1 つ以上の特定の API 名がある→ 特定の API を表示
any new、updates、newer、latest、upgrade — 特定の API 名がない→ すべて確認
any new、updates、newer、latest、upgrade — 1 つ以上の特定の API 名がある→ 特定の API を確認
set、change、adjust、update、bump、switch→ 変更

意図が曖昧な場合は、次のように尋ねます。

現在の API バージョンを表示しますか、それとも 1 つを変更しますか？

停止（依頼から操作を判断できない場合に限ります）。

ステップ 3：すべての API バージョンを表示する（すべて表示）

  1. pom.xml を読み取ります。<properties> 内にある、名前が .version で終わり、API 仕様の依存関係に対応するプロパティをすべて探します。API 仕様の依存関係を特定するには、対応する <dependency> ブロックを確認します。
    • classifier の確認（優先）： API 仕様の依存関係では、次のいずれかの classifier を使用します：raml、oas、graphql、protobuf、fat-protobuf、evented-api。コネクターでは mule-plugin を使用します。classifier があり、このリストと一致する場合は API 仕様です。
    • artifactId による代替判定： classifier が設定されていない場合は、artifactId に api という語が含まれているか確認します。これは API 仕様アーティファクトで一般的な命名規則です。 classifier が mule-plugin の依存関係、またはどちらの条件にも該当しない依存関係はスキップします。
  2. 該当するものをすべて表示します：
API dependency versions (from pom.xml <properties>):

  order-api.version    → 1.0.0
  customer-api.version → 2.1.0
  1. 見つからなかった場合は、その旨を明確に伝え、Anypoint Studio の Project Properties → API Specs タブで API がプロジェクトに追加されているか確認するようユーザーに案内します。

「すべて表示」パスでは、ここでスキルを終了します。

ステップ 4：指定された API のバージョンを表示する（特定の API を表示）

  1. ユーザーが指定した API 名をすべて抽出します。API 名が指定されていない場合は、「すべて表示」に切り替えます。
  2. pom.xml を読み取ります。指定された API ごとに、対応する <{artifactId}.version> プロパティを探します。
  3. 各結果を表示します：
order-api.version    → 1.0.0
customer-api.version → 2.1.0
  1. 指定された API のプロパティが見つからない場合は、そのことを示し、ユーザーが正しい名前を確認できるよう、利用可能な API バージョンプロパティを一覧表示します。

「特定の API を表示」パスでは、ここでスキルを終了します。

ステップ 5：すべての API について新しいバージョンを確認する（すべて確認）

  1. pom.xml を読み取り、すべての API 仕様の依存関係を特定します（「すべて表示」と同じ classifier／artifactId の判定ロジックを使用します）。

  2. 各 API について、以下のバージョン検出手順を使用して、利用可能なバージョンの一覧をすべて取得します。

  3. 結果を報告します：

    いずれかの API に新しいバージョンがある場合：

    Newer versions available:

  order-api:    current 1.0.0 → latest 2.0.0
  customer-api: current 1.5.0 → latest 1.6.0

No updates available:
  billing-api: 3.1.0 (already latest)

Would you like to update any of these?

    停止 — ユーザーが更新を希望する場合は、指定された API についてステップ 7 から始まる変更パスに移行します。

    新しいバージョンがある API がない場合：

    All APIs are on their latest versions:

  order-api:    1.0.0
  customer-api: 2.1.0
  billing-api:  3.1.0

Would you like to change any version anyway?

    停止 — はいの場合は、ステップ 7 の変更パスに移行します。

ユーザーが変更を希望しない場合は、ここでスキルを終了します。

ステップ 6：指定された API について新しいバージョンを確認する（特定の API を確認）

  1. ユーザーが指定した API 名を抽出します。

  2. 指定された API ごとに、以下のバージョン検出手順を使用して利用可能なバージョンの一覧をすべて取得し、現在のバージョンと比較して新しいバージョンがあるか判定します。

  3. ユーザーが指定した順に、API を 1 つずつ確認します：

    新しいバージョンがある場合：

    order-api — current: 1.0.0
A newer version is available: 2.0.0

Would you like to update it?

    停止 — はいの場合は、この API の変更フローに進みます（ステップ 7c 以降）。いいえの場合は、次に指定された API に進みます。

    すでに最新バージョンの場合：

    order-api is already on the latest version: 1.0.0

Would you like to change it to a different version anyway?

    停止 — はいの場合は、この API の変更フローに進みます（ステップ 7c 以降）。いいえの場合は、次に指定された API に進みます。

  4. 指定されたすべての API を確認した後、変更対象としてキューに追加された API がある場合は、ステップ 8 に進みます。

ステップ 7：対象 API を特定し、利用可能なバージョンを取得する（変更）

7a — 変更する API を特定する

更新する API がユーザーから指定されている場合は、それらを使用します。指定されていない場合は：

  1. pom.xml を読み取り、API 依存関係のバージョンプロパティをすべて一覧表示します。
  2. 更新する API をユーザーに尋ねます。

停止（対象 API が事前に指定されていない場合のみ）。

7b — Exchange から利用可能なバージョンを取得する

問い合わせる前に、後で問題が発生した場合に復元できるよう、現在の pom.xml の内容をメモリにバックアップしてください。

対象となる各 API について、pom.xml の <dependency> ブロックから groupId と artifactId を読み取り、以下のバージョン検出手順を使って、すべてのバージョン一覧を 1 回の呼び出しで取得してください。同じスクリプトの呼び出しに、対象 API を個別の引数としてすべて渡してください。API ごとに呼び出しを分けてはいけません。

いずれかの行で "source": "error" が返された場合（その API について list と describe のフォールバックがどちらも失敗した場合）：

  • pom.xml がまだ変更されていない場合は、停止して、該当行の error フィールドを示し、次のようにユーザーに伝えてください。

    Exchange から <artifactId> のバージョンを取得できませんでした。anypoint-cli-v4 が認証済みで、ネットワークにアクセスできることを確認してから、もう一度お試しください。

  • pom.xml が前の手順ですでに部分的に変更されている場合は、停止する前にバックアップした状態に復元し、同じメッセージを伝えてください。
バージョン検出（共有手順 — ステップ 5、6、7b で使用）

バンドルされたスクリプトを 1 回呼び出して、対象となるすべての API のバージョンを検出してください。ループして anypoint-cli-v4 を API ごとに呼び出してはいけません。 anypoint-cli-v4 を直接呼び出すたびに、Node CLI のコールドスタートとネットワークの往復が発生します。API ごとにループすると N 回の往復が逐次実行されますが、スクリプトを 1 回呼び出せば並列に実行され、すべての結果がそろってから返されます。複数の API 依存関係があるプロジェクトで、このスキルを高速に感じさせる最も効果的な方法です。

スクリプトは、絶対パスを指定して Bash ツールで呼び出してください。パスは <skill-dir>/scripts/fetch_versions.sh です。ここで <skill-dir> は「skill is now active」メッセージで伝えられた絶対パス（SKILL.md があるディレクトリ）です。相対パス ../scripts/... を組み立ててはいけません。ターンをまたぐと作業ディレクトリが変わり、相対パスが機能しなくなるためです。

対象となる API ごとに <groupId>:<artifactId>:<currentVersion> 引数を 1 つ渡してください。ステップ 5 と 6 ではそのステップで特定したすべての API、ステップ 7b では変更対象のすべての API を渡します。

<skill-dir>/scripts/fetch_versions.sh \
  "<groupId1>:<artifactId1>:<currentVersion1>" \
  "<groupId2>:<artifactId2>:<currentVersion2>"

スクリプトは標準出力に JSON 配列を 1 つ出力します。各入力 API に対応するオブジェクトが、入力順に並びます。

[
  {
    "groupId": "org.example", "artifactId": "order-api", "currentVersion": "1.0.0",
    "versions": ["2.0.0", "1.1.0", "1.0.0"],
    "source": "list"
  }
]

各行の source フィールドを確認してください。

  • "list" — 通常の方法です。内部で exchange asset list <artifactId> --output json を実行し、groupId と assetId が完全一致する行に絞り込み、semver の降順（最も新しいものが先頭）に並べ替えています。単一のバージョンを基準にしていないため、以下で説明する誤検出の失敗モードはありません。結果をそのまま信頼してください。
  • "describe-fallback" — このアセットに一致する行が list で返されなかったため、スクリプトが exchange asset describe <groupId>/<artifactId>/<currentVersion> にフォールバックし、otherVersions フィールドを解析しました。describe のバージョン一覧は、問い合わせに使用したバージョンを基準としており、その基準バージョンが公開済みの最新バージョンではないと、新しいバージョンが実際に存在していても空で返されることが確認されています。この行のバージョン一覧は不完全な可能性があるため、warning フィールドをそのままユーザーに伝えてください。CHECK／CHANGE では常に pom.xml で現在固定されているバージョンを基準に問い合わせますが、これは最新バージョンであることはほとんどありません。
  • "error" — このアセットについて list と describe のフォールバックがどちらも失敗しました。この行の error フィールドをそのままユーザーに伝えてください。ステップ 7b（CHANGE）では、Exchange からの取得失敗として扱います（下記参照）。ステップ 5／6（CHECK）では、該当する API の失敗を報告したうえで、他の API の処理を続けてください。1 つの API の検索失敗を理由に、チェック全体を中止してはいけません。

（この方法は、このリポジトリ内の兄弟スキル build-mule-integration/scripts/search_templates.sh と manage-global-configurations/scripts/get_latest_connector.sh ですでに使われているパターンと同じです。これらのスクリプトも同じレイテンシ上の理由から、exchange asset list の呼び出しを逐次ループではなく並列で実行します。）

7c — 利用可能なバージョンを提示して選択を処理する

対象の API ごとに、利用可能なバージョンを単一の AskUserQuestion ツール呼び出しとして提示します。バージョン一覧を通常のチャットテキストで先に説明し、その後にツールも呼び出すことはしないでください。同じ質問が二重に表示されます。ツール呼び出し自体を唯一の提示方法とします。現在のバージョンより新しいバージョンがある場合は、質問文でその旨を伝えます。現在のバージョンをラベル付きで含め、利用可能なバージョンをすべて選択肢として列挙します。現在のバージョンはすでに一覧に含まれるため、「現在のバージョンを維持する」といった選択肢は不要です。

question: "order-api — current: 1.0.0. A newer version is available: 2.0.0. Which version would you like to use?"
options:
  - "2.0.0"
  - "1.1.0"
  - "1.0.0 (current, no change)"
  - "0.9.0"

現在のバージョンがすでに最新の場合は、質問文から「新しいバージョンがあります」という文を削除しますが、同じ方法で引き続きツールを呼び出します。

question: "order-api — current: 2.0.0. Which version would you like to use?"
options:
  - "2.0.0 (current, no change)"
  - "1.1.0"
  - "1.0.0"

複数の API を変更する場合は、1 つずつ処理します。最初の API について AskUserQuestion を 1 回呼び出し、停止して選択を受け取ってから、次の API に進み、新たに AskUserQuestion を呼び出します。

停止 — 次の API を提示する前に、現在の API に対するツールの応答を待ちます。ツール呼び出しの前後に、質問や選択肢の一覧をチャットメッセージとして繰り返してはいけません。

7d — 同じバージョンが選択された場合の処理

ユーザーが対象 API にすでに適用されているバージョンを選択した場合は、次のように応答します。

order-api はすでにバージョン 1.0.0 です。変更はありません。

その API を変更対象から除外します。リクエストに含まれるすべての API が変更不要の場合は、ここでスキルを終了します。それ以外の場合は、バージョン変更がある残りの API の処理を続けます。

ステップ 8：新しいバージョンを適用する（変更）

8a — pom.xml を更新する

変更対象の各 API について、該当するケースを判断します。

ケース 1 — プロパティのプレースホルダーがすでに存在する（<{artifactId}.version> が <properties> にある場合）： <properties> ブロック内の値を更新します。依存関係自体（<version>${order-api.version}</version>）を変更する必要はありません。

ARTIFACT_ID="order-api"
NEW_VERSION="1.1.0"

awk -v key="${ARTIFACT_ID}.version" -v val="$NEW_VERSION" '
  $0 ~ "<" key ">" { sub(/>.*</, ">" val "<") }
  { print }
' pom.xml > pom.xml.tmp && mv pom.xml.tmp pom.xml

ケース 2 — バージョンが依存関係に直接ハードコードされている（<{artifactId}.version> プロパティがなく、依存関係にリテラルの <version>1.0.0</version> がある場合）： これは、プロジェクトがまだプレースホルダーのパターンを使用していないことを意味します。次の両方を行います。

  1. <properties> ブロックに <{artifactId}.version>NEW</{artifactId}.version> を追加します。
  2. その依存関係のブロック内にあるハードコードされた <version>1.0.0</version> を <version>${order-api.version}</version> に置き換えます。

変更対象の各 API について繰り返し、ファイルを書き込む前にすべての編集を適用します。

8b — 確認する

行った変更の概要を出力します。

Updated in pom.xml:
  order-api.version:    1.0.0 → 1.1.0
  customer-api.version: 1.5.0 → 2.0.0

ステップ 9：プロジェクトを再スキャフォールディングする（変更）

すべてのバージョンプロパティを更新したら、APIkit を実行して、新しい API 仕様バージョンからフローを再生成します。これは、Anypoint Studio で「Project Properties → API Specs」タブの変更を保存したときに実行される操作と同じです。同じ操作で複数の API を変更した場合は、すべての API のフローがこの 1 回の処理で再生成されます。

プロジェクトのルートから、以下を表示どおりに実行します。コマンドは && でつないだ 2 つだけで、後ろには何も追加しないでください。

cd <projectDir> && mvn clean package -DskipTests
  • このコマンドに 2>&1、>、>>、その他のリダイレクトを絶対に追加せず、何にもパイプでつながないでください。 ツールの呼び出しでは stdout と stderr がすでにすべて取得されるため、リダイレクトを追加しても意味はありません。さらに、実際に副作用があります。ホスト IDE のコマンドレイヤーはストリームリダイレクト演算子を安全でないものとして扱い、ほかの点では信頼できるコマンドであっても手動承認を求めます。このステップでは、まさにそれを避ける必要があります。
  • フラグを追加したり、ほかのコマンドとまとめたりしないでください。上記の cd <projectDir> && mvn clean package -DskipTests という形式をそのまま使用してください。
  • 実行前にユーザーの確認を求めて止まらないでください。 実際の製品では、バージョン変更後の再スキャフォールディングは自動で行われます。pom.xml が変更された時点、またはユーザーが「Project Properties → API Specs」タブを操作した時点で、Anypoint Studio が人によるクリック操作を挟まずに実行します。このスキルでも同様に、ステップ 8 の編集を書き込んだら、確認を求めずにコマンドを実行してください。
  • 続行する前に、出力がすべて表示されるまで待ってください。
  • BUILD SUCCESS は、APIkit が更新された仕様バージョンを取り込み、対応するフローを再生成したことを意味します。これでプロジェクトと変更されたすべての API バージョンとの整合性が取れています。
  • BUILD FAILURE が発生した場合：pom.xml を変更前の状態に自動で復元し、調査できるよう Maven のエラー出力を一字一句そのまま報告してください。

    ビルドに失敗しました — pom.xml は以前の状態に復元されています。Maven エラー：[ここに出力]

1 回の応答につき mvn の呼び出しは 1 回です。 ほかのツール呼び出しとまとめないでください。

ルール

  • プロパティ名は常に {artifactId}.version です — ハードコードされた <apiVersion> のようなタグではなく、API 依存関係の Maven artifactId から導出します。
  • <version> には絶対に触れないでください（pom.xml の先頭にある Maven アーティファクトのバージョン）。これはまったく別のフィールドです。
  • 変更を適用する前に、必ず利用可能なバージョンを表示してください。 ユーザーにバージョン文字列を入力するよう求めてはいけません。必ず最初に Exchange から取得して一覧を提示します。
  • 新しいバージョンがある場合に限り、その旨を通知します。 現在のバージョンが最新でない場合にのみ、「より新しいバージョンが利用可能です」というメッセージを表示します。それ以外の場合は表示しません。
  • 同じバージョンの選択はエラーではなく、何もしません。 ユーザーがすでに適用済みのバージョンを選択した場合はその旨を伝え、その API を変更対象から除外します。選択した項目がすべて何もしない項目なら、ファイルの書き込みも mvn の実行もせずに終了します。
  • 変更をすべてまとめて適用し、その後で一度だけ再スキャフォールドします。 mvn を実行する前に、pom.xml の編集をすべて適用します。API を個別に更新するたびに再スキャフォールドしてはいけません。最後に一度 mvn を実行すれば、すべての変更を反映できます。
  • 書き込み前に必ず pom.xml をバックアップします。 各 CHANGE 操作の開始時に、元の内容をメモリに保持します。Exchange の取得エラー、mvn の失敗、その他の理由で正常に完了できない場合は、自動的に元に戻します。
  • CHANGE の後には必ず再スキャフォールドします。再スキャフォールドは自動で行い、ユーザーに確認してはいけません。 mvn clean package -DskipTests を実行し、BUILD SUCCESS を確認するまでは、バージョンを更新したと宣言してはいけません。再スキャフォールドしないバージョン変更は、プロジェクトの整合性を損ないます。Step 8 の編集直後に確認を求めず実行してください。これは、pom.xml の変更時や API Specs タブの編集時に Anypoint Studio 自体が自動的に再スキャフォールドする動作に合わせるものです。
  • mvn コマンドの出力をリダイレクトしてはいけません。 2>&1、>、>>、パイプは使用しないでください。ツール呼び出しで stdout と stderr の全出力がすでに取得されます。また、リダイレクト演算子はホスト IDE の安全でないコマンドのチェックに引っかかり、不要な手動承認を強いる可能性があります。
  • 1 回の応答につき mvn の呼び出しは 1 回だけです。 ファイル編集や他のコマンドとまとめて実行しないでください。
  • pom.xml の編集に Anypoint CLI は不要です。 bash と Read／Edit ツールのみを使用してください。
  • Exchange の JSON 応答を解析するには、scripts/fetch_versions.sh が jq を必要とします。 スクリプトを実行するマシンで jq が利用できない場合、スクリプトは失敗します。別の手動フォールバック手段はありません。スクリプトの解析処理をインラインで再実装せず、jq をインストールしてください。
  • バージョンの検索では、対象 API ごとに anypoint-cli-v4 を直接呼び出すループを行わず、すべての対象 API を対象とする scripts/fetch_versions.sh の呼び出しを常に 1 回だけ行います。 Step 7b の バージョン検索 手順を参照してください。このスクリプトは、すべての対象 API に対して並行して exchange asset list（バージョンを指定しない）を実行します。そのアセットが list で見つからなかった場合に限り、API ごとに exchange asset describe の otherVersions フィールドをフォールバックとして使用します。describe のバージョン一覧は、問い合わせたバージョンに紐付いており、そのバージョンが最新でない場合に空または不完全な結果を返すことが確認されています。CHECK と CHANGE が問い合わせるのは、まさにその状況です。
  • 複数 API のバージョンは 1 つずつ選択します。 まず 1 つ目の API のバージョン一覧を表示して停止し、選択を受け取ってから次の API に進みます。すべての一覧を同時に表示してはいけません。
  • 複数ターンで対話します。 各 STOP マーカーでは、質問のみを通常のテキストとして表示し、その応答を終了して待ちます。必要な値がすべてそろうまで、ツールを実行してはいけません。
  • 提供済みの値は確認を省略します。 最初の STOP より前に、ユーザーがすでに提示した値（プロジェクトのパス、操作、対象 API、新しいバージョン）を抽出します。各 STOP では、質問への回答がすでにある場合は確認を省略します。

トラブルシューティング

  • .version プロパティが見つからない場合： プロジェクトに API がまだ追加されていない可能性があります。Anypoint Studio の「プロジェクトのプロパティ」→「API Specs」タブで、まず API 依存関係を追加してください。これにより、pom.xml にプロパティが作成されます。
  • バージョン変更後に mvn が失敗する場合： pom.xml は自動的に元に戻されます。根本原因を Maven のエラーで確認してください。選択したバージョンに互換性のない依存関係があるか、Exchange アセットの公開が完了していない可能性があります。
  • 同じ API に複数のプロパティがある場合： <properties> の下に同じ artifactId が複数回記載されている場合は、プロジェクトの整合性を保つため、すべての箇所を更新してください。
  • 認証エラーにより scripts/fetch_versions.sh の行に "source": "error" が返される場合： anypoint-cli-v4 conf を実行して認証情報を確認するか、anypoint-cli-v4 conf username <user> ／ anypoint-cli-v4 conf password <pass> で再認証してください。環境に ANYPOINT_BEARER が設定されていて、同時に ANYPOINT_CLIENT_ID ／ ANYPOINT_CLIENT_SECRET も設定されている場合は、クライアント認証情報の変数を解除してください。複数の認証方式が同時に有効な場合、CLI は呼び出しを拒否します。
  • "source": "describe-fallback" と、短すぎるように見える versions リストが返される場合： これは想定される動作です。exchange asset list がその groupId ／ assetId に一致する行を見つけられなかったため、スクリプトはバージョンを基準にした describe の検索に切り替えています。この方法では、現在のバージョンより新しいバージョンが表示されないことがあります（「バージョンの検出」を参照）。artifactId が Exchange の assetId と完全に一致していること（大文字と小文字を区別）と、アカウントが正しい組織で認証されていることを確認してください。CLI セッションで選択中の組織とは異なる組織から公開されたプライベートアセットは、list では表示されません。次の手順として、anypoint-cli-v4 exchange asset list <artifactId> --output json を手動で実行し（フィルターなし）、アセットが pom.xml に記載されたものとは異なる groupId で表示されるか確認してください。
  • 明らかな認証／ネットワーク上の原因がないのに "source": "error" が返される場合： そのアセットでは、exchange asset list と describe によるフォールバックの両方が失敗しています。根本原因となる CLI エラーを詳しく確認するには、その API だけを対象に scripts/fetch_versions.sh を再実行してください。または、2 つの anypoint-cli-v4 コマンドを手動で実行し、stderr を直接確認してください。

関連スキル

  • manage-global-configurations — API AutoDiscovery（api.id）や、これらの API バージョンと組み合わせるその他のグローバル要素を設定します
  • build-mule-integration — バージョン変更後に Mule プロジェクトをビルドしてパッケージ化します

コメント

Markdown 対応