コンテンツにスキップ

ワークスペース認可の検出とクロスワークスペースクエリ

OWL はデフォルトで現在のワークスペースをクエリします。他のワークスペースをクエリする必要がある場合は、まず「認可されたデータクエリ」と「同組織 Trace クエリ」を区別し、対応するツールを選択してください。

クエリ方法の選択

シナリオ ワークスペースの検出 クエリ方法
自ワークスペース ワークスペースの検出は不要 ワークスペースパラメータを指定せずに直接クエリ
認可されたクロスワークスペースデータ 対象が未確定の場合は owl.workspace.data_authorized.list を呼び出す DQL ツールに workspace_uuids と target_region を渡す。1 回のクエリで対象サイトは 1 つに限定
同組織のクロスワークスペース Trace 対象 UUID が未確定の場合は owl.account.workspace.same_org.list を呼び出す owl.data.same_org.trace.query に trace_id と選択した workspace_uuids を渡す。省略または空配列の場合は自ワークスペースのみクエリ

既に明確な検出結果がある場合はそのまま再利用できます。同組織のワークスペースリストは通常のデータクエリの認可を意味するものではなく、認可ワークスペースリストの代わりにはなりません。クエリが失敗したり空の結果が返った場合でも、認証情報を切り替えたり、ワークスペースの範囲を広げたり、別の種類のクエリ経路に変更したりしないでください。

アップグレードとメンバーツールの移行

使用前に、対象サイトが認可ワークスペースの検出とクロスワークスペースクエリをサポートしていることを確認してください。CLI を v1.4.0 にアップグレードし、サーバー側も Registry とツールカタログをアップグレードしたうえで、全量同期を実行してください。MCP クライアントはツールを再検出します。

owl sync
owl tool list --category workspace

追加された workspace カテゴリには、owl.workspace.data_authorized.list と owl.workspace.member.list が含まれます。旧 member カテゴリは削除され、旧名 owl.member.list はメンバーツールの呼び出しエイリアスとして引き続き利用できます。パラメータと権限チェックは同じものを使用しますが、独立したツールとしてはリストに表示されません。

owl exec owl.workspace.member.list -p '{"search":"alice"}'
# 旧スクリプトとの互換性
owl exec owl.member.list -p '{"search":"alice"}'

旧バージョンの CLI はエイリアスをサポートしていないため、カタログの同期だけでは旧コマンドの利用を保証できません。CLI を先にアップグレードしてから owl sync を実行してください。workspace カテゴリだけを同期しないでください。

認可ワークスペースの検出

owl.workspace.data_authorized.list は、現在のワークスペースにデータクエリ権限を付与しているワークスペースをサイトごとに一覧表示します。

owl exec owl.workspace.data_authorized.list -p '{}'
パラメータ 型 説明
region_code string 任意。対象サイトを絞り込みます。返された完全なコードを保持してください。custom: などのプレフィックスも含みます
search string 任意。ワークスペース名または UUID で検索します
page_index integer サイトごとのページ番号。1 から始まり、デフォルトは 1
page_size integer サイトごとの各ページに含めるワークスペース数。1〜100。デフォルトは 100

オプションの文字列に値がない場合は省略してください。null、空文字列、空白のみの文字列を渡すことはできません。返された workspace_uuid と region_code を使用して対象を選択し、対象ワークスペースの API Key に切り替えないでください。

返された結果の current_workspace は現在のワークスペースで、sites[] には各サイトの workspaces と独立した page_info が含まれます。グローバルなページ番号はありません。特定のサイトに次のページがまだある場合は、フィルタ条件を保持したままそのサイトだけを個別にクエリしてください。

owl exec owl.workspace.data_authorized.list -p '{"region_code":"cn2","page_index":2,"page_size":100}'

(region_code, workspace_uuid) の組み合わせでワークスペースを識別します。リストはワークスペース間にクエリ認可があることを示しますが、具体的なデータ型とログインデックスの権限はクエリインターフェースが検証します。また、page_size はクエリ対象のワークスペース数の上限ではありません。

1 つの対象サイトのデータをクエリする

CLI では owl.data.query または owl.data.simple_query_file を使用し、MCP では owl.data.simple_query を使用します。クロスワークスペースクエリでは、既存の DQL パラメータに加えて次のものを指定します。

パラメータ 型 ルール
workspace_uuids string[] 空でない配列。要素は認可ワークスペースリストの workspace_uuid から取得
target_region string リストの region_code から取得。このパラメータを指定する場合は、必ず workspace_uuids も指定

両方を省略すると現在のワークスペースをクエリします。ワークスペース UUID のみを渡した場合、サーバーは既存の認可情報に基づいてサイトを推定します。同じリクエストで 1 つのサイト内の複数の認可ワークスペースを選択できますが、複数のサイトを混在させることはできません。リモートサイトを明示的にクエリする場合は、現在のワークスペースを同時に含めることはできません。

workspace_uuids=["*"] は、対象サイト内のすべての認可ワークスペースを意味します。対象サイトを省略した場合は現在のサイトを使用し、現在のワークスペースも含みます。* は明示的な UUID と混在できません。また、ページをめくるたびに認可が再解決されます。クエリ範囲を固定する必要がある場合は、明示的な UUID を渡してください。

CLI の例

例の中のワークスペース、サイト、データソース、時間は実際の値に置き換えてください。時間は 13 桁のミリ秒タイムスタンプを使用し、終了時間は開始時間より後、期間は最大 7 日です。

owl exec owl.data.simple_query_file -p '{"namespace":"L","source":"nginx","start_time":1772516130000,"end_time":1772516140000,"limit":100,"workspace_uuids":["wksp_b","wksp_c"],"target_region":"cn2"}'

CLI はクエリ結果を data ファイルに保存し、ファイルインデックスのパラメータにワークスペースとサイトの範囲を保持します。すべてのデータにワークスペースフィールドが含まれると想定したり、すべてのデータを最初のワークスペースにまとめたりしないでください。

MCP の例

facade モードでは、まず workspace カテゴリ内の認可ワークスペースツールを発見し、クエリ範囲を取得したうえで exec_tool を介して呼び出します。

{
  "tool_name": "owl.data.simple_query",
  "parameters": {
    "namespace": "L",
    "source": "nginx",
    "start_time": 1772516130000,
    "end_time": 1772516140000,
    "workspace_uuids": ["wksp_b", "wksp_c"],
    "target_region": "cn2"
  }
}

static モードでは、tools/list でツールを発見した後、ビジネスツール名で tools/call を直接呼び出し、上記の parameters オブジェクトを arguments として渡します。どちらのモードも現在接続している認証情報を使用します。

ページングとエラー処理

認可ワークスペースリストはページ番号を使用し、データクエリはカーソルを使用します。データレスポンスで data.page_info.has_more=true の場合、返された next_cursor_time / next_cursor_token をそのまま次の cursor_time / cursor_token として使用し、元の時間、条件、ワークスペース、サイトの範囲を保持してください。

カーソル時刻はマイクロ秒単位の場合があります。13 桁のミリ秒に変換しないでください。また、リストの page_index や page_size をデータクエリに使用しないでください。各呼び出しで取得できるのは 1 ページのみで、後続ページは呼び出し側が明示的にリクエストします。

  • まず CLI の success または MCP の isError を確認してから、ツールの結果を解析してください。text ツールの AIAPI レスポンスは OWL 実行結果の output 文字列にあります。
  • 成功してもデータが空の場合は有効な結果です。自動的に範囲を広げて再クエリしないでください。
  • パラメータ、認可、またはサイトが一致しない場合は、パラメータを修正するか、認可範囲を再確認してください。失敗を回避するためにワークスペースごとにリトライしないでください。
  • trace ID や構造化されたエラー診断フィールドが返された場合は、調査のためにその情報を保持してください。
  • 対象サイトがツールまたはクロスワークスペースパラメータをサポートしていない場合は、管理者に連絡してサーバーバージョンを確認してください。ワークスペースパラメータを削除してリトライしないでください。

フィードバック

このページは役に立ちましたか？