fusion-devtools

Fusion DevTools

使用する場面

コマンドラインから Fusion プラットフォームのサービスを操作する必要がある場合に使用します。API の呼び出し、トークンの取得、サービスの検索、人物の検索などが該当します。

主な使用例：

• 「People API を呼び出して」
• 「context サービス用のトークンを取得して」
• 「本番環境ではどのサービスが利用できますか？」
• 「このエンドポイントをテストして」
• 「この人物の Azure ID を解決して」
• 「org サービスのベース URL は何ですか？」
• 「jq に渡せるアクセストークンを取得して」

暗黙的な使用例：

• エージェントが API コントラクトやレスポンス形式を確認する必要がある
• エージェントが HTTP リクエスト用のベアラートークンを必要としている
• エージェントがどのサービスキーがどの URL に対応するかを調べる必要がある
• エージェントがテストデータ用に人物の ID を調べる必要がある

使用しない場面

• バックエンドサービスのソースコードを変更する場合 — サービスのリポジトリを直接使用してください
• サービスをデプロイまたは公開する場合 — CI/CD パイプラインを使用してください
• インフラストラクチャをプロビジョニングする場合 — Terraform/Bicep を使用してください
• Service Bus / SignalR のデバッグ — Azure ポータルまたは専用ツールを使用してください
• AI 検索インデックスの管理 — 別途運用上の課題として扱ってください

前提条件

fdev を .NET グローバルツールとしてインストールします：

dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" fusion-devtools

最新バージョンに更新します：

dotnet tool update --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" fusion-devtools

初回使用前に認証します：

fdev login

主なワークフロー

1 — Fusion REST API を呼び出す

fdev rest を使用して、任意の Fusion サービスを呼び出します。サービス検出によってベース URL が解決され、トークンが自動的に取得されます。

fdev rest <serviceKey> '<path>'

? のグロブ展開を防ぐため、zsh/bash ではパスを引用符で囲む必要があります。

例：

# GET from people service (production)
fdev rest people '/persons/me?api-version=3.0'

# POST with JSON body
fdev rest context '/contexts?api-version=1.0' -m post -b '{"query":"test"}'

# POST with body from file
fdev rest people '/persons/search?api-version=3.0' -m post -b @request.json

# Different environment
fdev rest people '/persons/me?api-version=3.0' -e ci

# Save response to file
fdev rest people '/persons/me?api-version=3.0' -o response.json

# Full URL mode (skip discovery)
fdev rest --url https://httpbin.org/get --no-auth

# Custom scope override
fdev rest people '/persons/me?api-version=3.0' --scope api://my-app/.default

主なオプション：メソッドを指定する -m、本文を指定する -b（@file に対応）、環境を指定する -e、フル URL モードの --url、認証をスキップする --no-auth、スコープを上書きする --scope、出力ファイルを指定する -o、--header KEY=VALUE。

2 — アクセストークンを取得する

fdev get-access-token を使用すると、az account get-access-token と同様に、構造化された JSON 形式でトークンを出力できます。出力はパイプに渡しやすい形式です。

# Token for a specific service (resolves scope via discovery)
fdev get-access-token --service-key people

# Token with explicit scope
fdev get-access-token --scope api://97978493-9777-4d48-b38a-67b0b9cd88d2/.default

# Extract just the token
fdev get-access-token --service-key people | jq -r '.accessToken'

出力形式：

{
  "accessToken": "eyJ...",
  "expiresOn": "2026-05-15T12:00:00+00:00",
  "expiresOnUnix": 1778846400,
  "scope": "api://app-id/.default",
  "tokenType": "Bearer"
}

3 — サービスと環境を検索する

# List all environments
fdev disc envs

# List services in an environment (JSON output)
# Note: disc subcommand uses single-dash flags (-json, -out) — this is by design
fdev disc env list fprd -json

# List services showing key and URI
fdev disc env list fprd -out ku

4 — 人物を検索する

# Resolve by email
fdev persons resolve [email protected]

# Search by name
fdev persons search "John"

5 — PIM ロールを有効化する

管理操作に必要な場合は、Azure のアクセス権限を昇格します：

fdev pim azure activate

安全上の注意：PIM の有効化を実行する前に、必ずユーザーに確認してください。これにより、昇格されたアクセス権が付与されます。

6 — 生の JWT トークンを取得する（クリップボード）

クリップボードを使った手軽なトークン取得ワークフローには、既存のコマンドを使用します：

fdev token          # test environment token
fdev token --prod   # production token

手順

ステップ 1 — fdev が利用可能か確認する

fdev コマンドを使う前に、インストールされていることを確認します：

fdev --version

インストールされていない場合は、「前提条件」に記載されているインストールコマンドを表示します。認証が必要な場合は、fdev login を実行します。

ステップ 2 — 適切なコマンドを選択する

必要な操作	コマンド
Fusion API を呼び出してレスポンスを確認する	fdev rest <service> '<path>'
スクリプトやパイプ渡し用のトークンを取得する	fdev get-access-token --service-key <key>
利用可能なサービスを検索する	fdev disc env list <env>
サービスのベース URL とスコープを検索する	fdev disc env list <env> -json を実行し、キーで絞り込む
人物を検索する	fdev persons resolve <email>
クリップボード用の手軽なトークンを取得する	fdev token

ステップ 3 — デバッグには詳細モードを使用する

任意のコマンドに --verbose を追加すると、キャッシュのヒット／ミス、リクエスト／レスポンスの全ヘッダー、トークンの詳細など、診断情報が出力されます。

fdev rest people '/persons/me?api-version=3.0' --verbose

ステップ 4 — 必要に応じてキャッシュを無効にする

サービス検出の結果はローカルにキャッシュされます（環境：24 時間、サービス：1 時間）。最新の情報を取得するには、--no-cache を使用します：

fdev rest people '/persons/me?api-version=3.0' --no-cache

環境

キー	用途	備考
ci	継続的インテグレーション／開発	安定性が最も低く、最新の変更が反映されます
fqa	品質保証	本番前の検証
fprd	本番環境	デフォルトの環境

すべてのコマンドで、デフォルトの環境は fprd です。-e <env> で上書きできます。

リファレンスガイド

コマンドオプションとワークフローのレシピについて詳しくは、references/ を参照してください：

• command-reference.md — すべてのオプションを含む、簡潔なコマンド早見表
• agentic-patterns.md — エージェント型ワークフローの一般的なレシピ

安全性

• このスキルは変更を行う機能を備えています。競合する場合は、インラインのガイダンスよりもリポジトリ内のワークフロー指示を優先してください。
• ユーザーに表示する出力にアクセストークンをそのまま含めないでください。表示する場合は、一部を切り詰めるか、伏せてください。
• グロブ展開を防ぐため、? を含むパスはシェルコマンド内で必ず引用符で囲んでください。
• 本当に公開されているエンドポイントに限り、--no-auth を使用してください。
• 権限昇格を伴う fdev pim azure activate を実行する前に、必ずユーザーに確認してください。
• 明示的に依頼された場合を除き、トークンをファイルに保存したり、ログに記録したりしないでください。