External API によるサービスマップのエクスポート¶

このドキュメントでは、Guance External API を使用してサービスノードと呼び出し関係を取得し、ワークスペースごとにクエリすることで、指定サイト内のサービスマップデータを集計する方法について説明します。

API は JSON を返します。CSV、Excel、アプリケーション依存関係リストを生成するには、呼び出し側で返却結果を整形する必要があります。

適用範囲¶

指定した時間範囲に収集された APM サービスマップをクエリし、サービス間の呼び出し関係を把握するために使用します。
単一のワークスペースではサービスマップ API を使用し、サイト内の全ワークスペースでは「ワークスペースをページングして一覧表示 → ワークスペースごとにトポロジをクエリ → 結果を集計」の流れを使用します。
エクスポート結果は、収集の完全性、データ保持期間、デプロイメントプランの影響を受けるため、すべての履歴依存関係や未収集の呼び出し関係を表すものではありません。
このドキュメントでは、毎回 1 つの workspaceUUID を指定する方法を採用します。コンソールのクロススペースセレクターはこのフローとは異なります。複数の UUID や * を workspaceUUID に連結しないでください。

異なるワークスペース間の呼び出し関係を分析する場合は、現場に該当する収集およびクロススペーストポロジ機能がすでに備わっていることを確認する必要があります。APM サービスマップのクロススペース設定の説明を参照してください。ワークスペースごとの集計では、元データに存在しないクロススペースの呼び出しエッジを補完することはありません。

準備作業¶

現在のサイトの External API Endpoint を確認します。通常は https://external-api.guance.com です。実際のデプロイ先アドレスを基準とし、コンソール front や OpenAPI Endpoint に置き換えないでください。
External API の AK/SK を準備し、API 署名認証に従ってリクエストヘッダーを生成します。ワークスペース OpenAPI の DF-API-KEY を署名の代わりに使用しないでください。
External 読み取り専用アカウントをサポートするバージョンでは、読み取り専用アカウントを使用して、この記事で説明する 2 つのクエリ API を呼び出すことができます。アカウントはサイト管理者が設定します。
start と end を固定します。どちらもミリ秒タイムスタンプであり、start < end である必要があります。すべてのワークスペースで同じ時間範囲を使用します。署名ヘッダーの X-Df-Timestamp は、各リクエスト送信時の秒タイムスタンプです。
最初に 1 つのワークスペースを選択し、コンソールと同じ時間範囲とフィルター条件で返却内容を検証してから、一括エクスポートを開始します。デプロイメントプランで追加されたグループ化などのパラメーターのサポート状況は、現場のバージョンに従います。

ステップ 1: ワークスペースのページング取得¶

ワークスペース一覧 API を呼び出します：

GET /api/v1/workspace/list?pageIndex=1&pageSize=100

pageIndex は 1 から始まります。pageSize の最大値は 100 です。サイト内のすべてのワークスペースをエクスポートする場合は search を指定しません。

レスポンス内の次の内容を読み取ります：

フィールド	用途
`content.data[].uuid`	後続のトポロジリクエストの `workspaceUUID`
`content.data[].name`	エクスポートデータにクエリ対象のワークスペース名を補足
`content.pageInfo.totalCount`	条件に一致するワークスペースの総数。ページング継続の要否判定に使用

毎回 pageIndex を 1 ずつ増やし、ページング結果をすべて処理するまで続けます。UUID で重複を排除し、今回実際にクエリするワークスペースのリストを保存します。総数に達していないのに空のページが返された場合は、異常を記録して再確認し、全ワークスペースのエクスポートが成功したと判断してはいけません。エクスポート中にワークスペースが追加または削除された場合、ページング結果も変化する可能性があります。

ステップ 2: 各ワークスペースのサービスマップの取得¶

service map API を呼び出します：

GET /api/v1/tracing/service_map_v2?workspaceUUID=wksp_example&start=1789430400000&end=1789516800000

サンプルの時間範囲は北京時間 2026-09-15 08:00 から 2026-09-16 08:00 です。実際の必要に応じて、データ保持期間内の範囲に置き換えてください。

次のリクエストは署名ヘッダーを示しています。プレースホルダーのまま実行することはできません。

curl '<Endpoint>/api/v1/tracing/service_map_v2?workspaceUUID=wksp_example&start=1789430400000&end=1789516800000' \
  -H 'X-Df-Access-Key: <AK>' \
  -H 'X-Df-SVersion: v20240417' \
  -H 'X-Df-Timestamp: <現在の秒タイムスタンプ>' \
  -H 'X-Df-Nonce: <このリクエスト用のランダムな一時コード>' \
  -H 'X-Df-Signature: <最終的なリクエストパスに基づいて計算された署名>'

各リクエストで、一時コード、タイムスタンプ、署名を再生成する必要があります。署名は、最終的に送信する元のパスとクエリ文字列を使用します。groupBy などのパラメーターを追加したり URL エンコードを行った場合は、最終的なパスに基づいて署名を再計算する必要があります。

クエリ範囲の選択¶

目的	パラメーター設定
1 つのワークスペース内で選択した時間範囲の完全なトポロジを取得する	`workspaceUUID`、`start`、`end` のみを渡し、`centralService`、`search`、制限付き `filters` は渡さない
指定した中心サービスのトポロジを取得する	`centralService` を追加します (例: `centralService=demo-web`)
環境とバージョンを区別する	このパラメーターをサポートするバージョンでは `groupBy=env,version` を追加
プロジェクトまたは K8s クラスターを区別する	実際の必要に応じて `groupBy=project`、`groupBy=cluster_name_k8s`、またはその組み合わせを設定

groupBy はノードの識別に影響します。すべてのワークスペースで同じグループ化の基準を使用する必要があります。中心サービスを指定してグループ化を有効にする場合は、centralWorkspaceUUID、centralEnv などのフィールドを使用して中心ノードをさらに特定できます。詳細は API のパラメーター説明を参照してください。

コンソールの単一サービスの「上流/下流」ビューには中心サービスの制限が含まれており、ワークスペース全体のトポロジとして直接扱うことはできません。ページと API を照合する際は、時間、ワークスペース、グループ化、フィルター条件を同時に揃えてください。グラフのレイアウトやノードの色などの表示属性は、エクスポート対象のビジネス関係には含まれません。

エクスポートでは、content.services と content.maps を直接読み取ります。serviceMapList=true に依存して追加のリストやファイルを生成しないでください。

ステップ 3: ノード、呼び出しエッジ、実行結果の保存¶

各リクエストでは、まず HTTP ステータスとレスポンス内の code、success、errorCode を確認します。成功した場合は完全な JSON を保存し、その際に今回のクエリのワークスペース UUID、時間範囲、グループ化パラメーターも併せて記録します。

フィールド	意味
`content.services`	サービスノードのリスト。ノード名、ワークスペース識別情報、ノード ID (ある場合)、`data` を保持します
`content.maps`	方向を持つ呼び出しエッジ。`source` は呼び出し元、`target` は呼び出し先
`maps[].source_workspace_uuid` / `target_workspace_uuid`	エッジの両端が属するワークスペース (返却時は保持)
`maps[].source_id` / `target_id`	エッジの両端のノード ID (返却時は保持)。同名ノードの区別に使用可能
`maps[].avg_per_second`、`error_count`、`error_rate`、`p99`	呼び出しエッジが返す可能性のある統計フィールド。実際のバージョンの返却値に従う

テスト環境で実際に取得したレスポンスのマスキング済み抜粋は、service map レスポンス例を参照してください。この例には、選択したノードと呼び出しエッジのフィールドと統計値が含まれますが、現場のレスポンス検証の代わりにはなりません。

次の 2 種類のファイルを出力することを推奨します：

元の JSON: クエリ対象のワークスペースごとに保存し、ノード、エッジ、統計値、レスポンスの traceId を保持して、再確認を容易にします。
呼び出し関係テーブル: 各行に 1 つの方向を持つ呼び出し関係を記録します。少なくともクエリ対象ワークスペース、送信元ワークスペース、送信元サービス、宛先ワークスペース、宛先サービス、開始時間、終了時間を含みます。実際のレスポンスに応じてノード ID とグループ化ディメンションを追加します。

集計ルール：

A → B と B → A は異なる関係です。
異なるワークスペースの同名サービスは、名前だけで統合することはできません。優先的に「ワークスペース識別情報 + ノード ID」を使用し、ID がない場合は「ワークスペース識別情報 + サービス名 + 選択したグループ化ディメンション」を使用します。ワークスペース識別情報を確認できない場合は、要確認としてマークし、クエリ対象のワークスペースからエッジのもう一方の端の所属ワークスペースを推測しないでください。
同じ呼び出しエッジは複数のワークスペースのクエリ結果に現れる可能性があります。関係リストは、上記のノード識別情報で構成される有向エッジで重複を排除し、元のクエリ対象ワークスペースも保持できます。元の JSON では重複を排除しません。
重複するエッジのリクエスト数を直接合算したり、リクエストレート、エラー率、P99 を直接平均したりしないでください。グローバルな統計値が必要な場合は、集計基準を別途定めてください。
services と maps はそれぞれ保存します。呼び出しエッジからのみノードを抽出すると、呼び出しエッジのないサービスが欠落する可能性があります。
フィールド欠落は 0 として扱わないでください。特に統計フィールドでは、「返却なし」と「ゼロ値の返却」を区別してください。

一括実行フロー¶

以下はフローの疑似コードです。署名クライアントの実装には、API 署名認証の Python サンプルを再利用できます。

start、end、groupBy を固定する
workspace/list をページングで読み取り、uuid で重複を排除してワークスペースリストを保存する
ワークスペースリストの読み取りに失敗した場合: 停止し、今回のエクスポートが不完全であることをマークする

ワークスペースリストの各ワークスペースに対して順番に実行する:
    署名を再生成し、service_map_v2 をクエリする
    HTTP または業務ステータスが失敗した場合:
        失敗したワークスペース、エラーコード、traceId を記録し、他のワークスペースを続行する
    成功したが services/maps の構造が異常な場合:
        元のレスポンスを保存し、構造異常としてマークし、空のトポロジとして扱わない
    成功し、構造が正常な場合:
        元の JSON を保存する
        services と maps の両方が空の場合、「この時間範囲にはトポロジデータがありません」と記録する
        それ以外の場合は、ノード識別情報に基づいて呼び出し関係テーブルを作成する

ワークスペース総数、成功数、データなし数、失敗数、失敗したワークスペースリストを出力する
失敗または構造異常がある場合: 結果を一部完了としてマークする
失敗したワークスペースに対して同じ時間範囲で再試行し、集計結果を更新する

最初は直列クエリを実行し、適切なリクエストタイムアウトを設定することを推奨します。ワークスペースが多い場合は、現場の負荷に応じて並列度を制御してください。サービスマップ API には pageIndex/pageSize 形式のページングパラメーターは公開されていません。ワークスペースリストのページング方式を流用して呼び出しエッジを追加取得することはできません。データ量が多い場合は、現場のクエリ制限と返却の完全性を確認してください。

検証とトラブルシューティング¶

現象	確認方法
署名失敗	Endpoint、AK/SK、`v20240417`、システム時刻、署名パスが最終的な URL エンコードおよびパラメーター順序と一致しているかを確認します
1 つのサービスの周辺の関係のみがエクスポートされる	ページリクエスト内の `centralService`、検索条件、フィルター条件をコピーしていないか確認します
ページ上のサービス数と一致しない	ワークスペース、時間、グループ化、フィルター、上流/下流または完全なトポロジビューを合わせます。ページ表示ではノードとエッジも処理されます
クロススペースの呼び出しエッジが見えない	収集、現場バージョン、クロススペーストポロジ設定を確認します。ワークスペースごとの集計だけからクロススペース関係の完全性を推測すべきではありません
同名サービスが統合される	ワークスペース識別情報、ノード ID、`groupBy` ディメンションが重複排除に参加しているか確認します
空の結果	まずリクエストの成功と構造が正常であることを確認し、次に時間範囲、保持期間、そのワークスペースに APM データがあるかどうかを確認します
一部のワークスペースでリクエストが失敗	失敗リストと `traceId` を保持し、再試行後にエクスポートが完了したか確認します

顧客環境にリリースする前に、少なくとも次の項目を検証することを推奨します：呼び出し関係がある 1 つのワークスペース、トポロジデータがない 1 つのワークスペース、ワークスペースリストのページング、失敗したワークスペースの記録、異なるワークスペースにおける同名サービスの区別。