認可されたワークスペースの検出とクロスワークスペースクエリ¶
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 クライアントはツールを再検出します。
新しい 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 を更新し、workspace カテゴリだけでなく owl sync で全体を同期してください。
認可されたワークスペースを検出する¶
owl.workspace.data_authorized.list は、現在のワークスペースにデータクエリ権限を付与したワークスペースをサイト別に一覧表示します。
| パラメータ | 型 | 説明 |
|---|---|---|
region_code |
string | 任意の対象サイトフィルター。custom: などの接頭辞を含め、返されたコードをそのまま使用 |
search |
string | 任意のワークスペース名または UUID 検索 |
page_index |
integer | サイトごとのページ番号。1 から開始し、デフォルトは 1 |
page_size |
integer | サイトごとの 1 ページあたりの件数。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 回の呼び出しで取得するのは 1 ページで、続きは明示的に要求します。
- CLI の
successまたは MCP のisErrorを先に確認します。text ツールの AIAPI 応答は OWL 結果のoutput文字列内にあります。 - 成功した空の結果は有効です。自動的に範囲を拡大しないでください。
- パラメータ、認可、サイトのエラーは要求を修正するか権限を確認します。ワークスペースごとの再試行で失敗を回避しないでください。
- 返された trace ID や構造化診断情報は調査用に保存します。
- ツールやクロスワークスペースパラメータが未対応の場合は管理者にサーバーバージョンを確認し、範囲パラメータを削除して再試行しないでください。