取得¶
GET /api/v1/aggs_to_metric/{rule_uuid}/get
概要¶
指定したメトリクスを生成するルールの保存済み完全設定と、作成者/更新者の識別情報を読み取ります。
呼び出し前の準備と使用手順¶
メトリクスを生成するリストから本ワークスペースの UUID を取得し、ルールと 2 種類の識別情報サマリーを読み取ります。実行結果は照会しません。詳細は RUM タイプのフィルタリストのように sourceInfo を自動追加しません。過去の extend にこのフィールドが保存されている場合は、引き続き返される可能性があります。
これらのエンドポイントは共通のルール処理を共有しており、一部の対象クエリでは type=aggs による追加の限定がありません。他のルールを誤って読み取ったり変更したりしないよう、本モジュールのリストが返す UUID のみを使用してください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| rule_uuid | string | Y | パス内のルール UUID であり、メトリクス名、メジャーメント名、スケジュール ID ではありません。通常のモニターの rul_ UUID を渡さないでください。 例: rul_aggs_example取得または入力方法: メトリクスを生成するルールのリスト の content.data[].uuid からのみ、本ワークスペースの aggs ルールを取得してください。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得してください。 |
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/aggs_to_metric/rul_aggs_example/get' \
-H 'DF-API-KEY: <DF-API-KEY>'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | レコード番号。新規スナップショットは送信前に生成されるため null の可能性があります。操作には uuid を使用してください。 |
| content.uuid | string | rul_ ルール UUID。 |
| content.workspaceUUID | string | 所属ワークスペース。 |
| content.monitorUUID | string | 関連付けられたモニター UUID。本モジュールでは通常空文字列です。 |
| content.type | string | エンティティタイプは固定で aggs。jsonScript.type とは異なります。 |
| content.refKey | string | 関連キー。通常は空です。 |
| content.secret | string | 互換エンティティフィールド。通常のメトリクスを生成するルールでは通常空です。呼び出し認証情報として使用したり、実際の値を記録したりしないでください。 |
| content.createdWay | string | manual/import/template または履歴上の空値。 |
| content.isLocked | integer または boolean | ロックフラグ。通常 0/false。 |
| content.openPermissionSet | boolean | カスタム操作権限スイッチ。本モジュールでの作成時は通常 false。 |
| content.permissionSet | array<string> |
カスタム操作主体の配列。通常 []。 |
| content.permissionSet[] | string | 単一のアカウント/チーム/ロール識別子。 |
| content.status | integer | 0 有効、2 無効、3 削除。状態は直近のタスク実行の成功を意味するものではありません。 |
| content.creator | string | 作成者の識別情報。 |
| content.updator | string | 最終更新者の識別情報。初期状態では空の場合があります。 |
| content.createAt | integer | 作成 Unix 秒。 |
| content.updateAt | integer | 更新 Unix 秒。未更新は -1。 |
| content.deleteAt | integer | 削除 Unix 秒。未削除は -1。 |
| content.crontabInfo | object | スケジュール設定のサマリー。タスク実行結果ではありません。 |
| content.crontabInfo.id | string | スケジュール設定識別子。システム保守用。ルール操作には uuid を使用。 |
| content.crontabInfo.crontab | string | 実際の 6 フィールドのスケジュール式。例: 0 */5 * * * *。リクエスト頻度には引き続き metricInfo.every を使用。 |
| content.jsonScript | object | 保存された設定: 必須のルールオブジェクト。変更時は全体置換で、フィールドマージは行いません。本ページに記載されたサブフィールドのみを送信し、詳細レスポンスで返されたすべてのエンティティをそのまま返さないでください。 |
| content.jsonScript.type | string | 保存された設定: 必須のデータカテゴリ。公開宣言ではこの 6 種類のみを受け付けます。内部オブジェクトプラグインは、現在の OpenAPI で公開サポートされていることと同義ではありません。変更によってカテゴリを変更することはできません。 |
| content.jsonScript.query | json | 保存された設定: 必須のクエリオブジェクト。実際の実行は q を基準とし、extend フィールドからクエリを自動生成または修正しません。保存成功は、クエリ構文、データ可用性、または生成結果が期待どおりであることを保証しません。 |
| content.jsonScript.query.q | string | 保存された設定: クエリオブジェクト内の必須文字列。選択モードでも完全な q を提供する必要があります。認証情報を入力しないでください。Distribution の例では histogram_auto(フィールド) を使用し、distribution(フィールド) ではありません。 |
| content.jsonScript.query.qtype | string | 保存された設定: オプションのクエリ構文。省略時の実行デフォルトは dql。明示する場合は dql/promql のみを使用でき、空文字列や null は渡せません。常に明示的に入力することを推奨します。PromQL は即時クエリとして実行され、このオブジェクトで rangeQuery を設定することはありません。 |
| content.jsonScript.query.qmode | string | 保存された設定: オプション。明示を推奨。selectorQuery では extend.fieldKey/funcName が必須。customQuery ではこのエコーバックフィールドは要求されません。省略時、コントローラは選択モードの構造検証をトリガーしませんが、プラグインは引き続き選択モードに従って関数を検証する可能性があるため、省略によって検証を回避することはできません。 |
| content.jsonScript.metricInfo | json | 保存された設定: 必須の出力とスケジュールのオブジェクト。変更時はオブジェクト全体を再設定し、metric/metricField は変更できません。単位説明は変更可能で、省略時は空文字列として同期されます。 |
| content.jsonScript.metricInfo.every | string | 保存された設定: 必須の頻度。先頭の 0 は不可。60m、0m、秒、日、Cron 式はサポートしません。スケジュール頻度とクエリウィンドウ長に使用され、遅延時間ではありません。 |
| content.jsonScript.metricInfo.metric | string | 保存された設定: 必須のメジャーメント名。英字、数字、アンダースコアのみで、ハイフン、スペース、中国語を含めることはできません。変更は許可されません。 |
| content.jsonScript.metricInfo.metricField | string | 保存された設定: 必須のメトリクス名。命名文字制限は metric と同じです。変更は許可されません。過去の例にある 001-test を流用しないでください。 |
| content.jsonScript.metricInfo.unit | string | 保存された設定: オプションの表示単位文字列。省略/空文字列でクリアされます。単位に基づいて q の数値を自動換算することはありません。クエリ結果と単位が一致するよう自身で保証する必要があります。 |
| content.jsonScript.metricInfo.desc | string | 保存された設定: オプションのメトリクス説明。省略/空文字列は空として同期されます。ルール名ではありません。 |
| content.jsonScript.metricInfo.delaySeconds | integer | 保存された設定: オプションの待機秒数。デフォルトは 0 で遅延しません。定期トリガー後にソースデータが揃うまで待機します。every に対応するクエリウィンドウは変更しません。このフィールドを指定しない場合、変更後は 0 に戻ります。JSON 整数である必要があり、ブール値や "60" 文字列は受け付けません。 |
| content.extend | object | 保存された設定: 必須のエコーバックオブジェクト。変更時は全体置換。すべてのエコーバックオプションは jsonScript.query の代替にはなりません。手書きモードでエコーバックが不要な場合は {} を指定できます。 |
| content.extend.funcName | string | 保存された設定: selectorQuery 時に条件付きで必須となる集計関数名。count はカウント、count_distinct は重複排除数です。数値集計関数には実際の数値フィールドが必要です。distribution は q 内の対応する histogram_auto をエコーバックします。 |
| content.extend.fieldKey | string | 保存された設定: selectorQuery 時に条件付きで必須となるエコーバック集計フィールド。追加時はソースフィールド型を照会して数値関数との互換性を確認しますが、未知のフィールドが必ず拒否されるとは限りません。変更時は同じフィールド型チェックを繰り返し実行しません。 |
| content.extend.source | string | 保存された設定: オプションのソースエコーバック。すべて利用可能な場合は * で表し、実際の範囲は引き続き q によって限定されます。RUM リストをクエリする際、この値によって sourceInfo を付加できます。 |
| content.extend.index | string | 保存された設定: オプションのログインデックスのエコーバック。これを変更しても q 内の L インデックスは自動変更されません。 |
| content.extend.groupBy | array | 保存された設定: オプションのグループ化エコーバック配列。省略時はこのエコーバックフィールドはありません。空配列はグループ化しません。実際のグループ化は q を基準とします。 |
| content.extend.groupBy[] | string | 保存された設定: 単一のグループ化キー。 |
| content.extend.filterString | string | 保存された設定: オプションのログフィルタエコーバック文字列。q の自動連結入口ではありません。実際のフィルタは q に書き込む必要があります。 |
| content.extend.filters | array | 保存された設定: オプションの配列。複数形の values を使用し、他のインターフェースの value とは異なります。実際の実行フィルタは q を基準とします。 |
| content.extend.filters[] | json | 保存された設定: フィルタエコーバックオブジェクト。クライアント側の既存形式を再帰的に保持できます。現在のエコーバック構造は実行クエリに変換されません。 |
| content.extend.filters[].name | string | 保存された設定: エコーバックフィールド。 |
| content.extend.filters[].condition | string | 保存された設定: 前のエコーバック条件との関係。 |
| content.extend.filters[].op | string | 保存された設定: エコーバック演算子。本インターフェースではクエリ条件変換を実行しません。 |
| content.extend.filters[].values | array | 保存された設定: エコーバック値配列。実際の比較と値の取得はすべて q に反映する必要があります。 |
| content.extend.filters[].values[] | JSON | 保存された設定: 単一の文字列、数値、またはブール値。 |
| content.creatorInfo | object | 関連する識別情報のサマリー。一致する識別情報がない場合は {}。 |
| content.creatorInfo.uuid | string | 識別情報 UUID。省略可能。 |
| content.creatorInfo.status | integer | アカウント状態。省略可能。 |
| content.creatorInfo.wsAccountStatus | integer | ワークスペースメンバーシップ状態。省略可能。 |
| content.creatorInfo.name | string | 表示名。 |
| content.creatorInfo.username | string | ログイン名。 |
| content.creatorInfo.email | string | メールアドレスまたはシステム識別子。 |
| content.creatorInfo.mobile | string | 携帯電話番号。空の場合があります。 |
| content.creatorInfo.countryCode | string | 国/地域コード。省略可能。 |
| content.creatorInfo.iconUrl | string | アバター。省略可能。 |
| content.creatorInfo.acntWsNickname | string | ワークスペースニックネーム。省略可能。 |
| content.updatorInfo | object | 関連する識別情報のサマリー。一致する識別情報がない場合は {}。 |
| content.updatorInfo.uuid | string | 識別情報 UUID。省略可能。 |
| content.updatorInfo.status | integer | アカウント状態。省略可能。 |
| content.updatorInfo.wsAccountStatus | integer | ワークスペースメンバーシップ状態。省略可能。 |
| content.updatorInfo.name | string | 表示名。 |
| content.updatorInfo.username | string | ログイン名。 |
| content.updatorInfo.email | string | メールアドレスまたはシステム識別子。 |
| content.updatorInfo.mobile | string | 携帯電話番号。空の場合があります。 |
| content.updatorInfo.countryCode | string | 国/地域コード。省略可能。 |
| content.updatorInfo.iconUrl | string | アバター。省略可能。 |
| content.updatorInfo.acntWsNickname | string | ワークスペースニックネーム。省略可能。 |
| content.declaration | object | 公開宣言。 |
{
"code": 200,
"content": {
"id": 101,
"uuid": "rul_aggs_example",
"workspaceUUID": "wksp_example",
"monitorUUID": "",
"type": "aggs",
"refKey": "",
"secret": "",
"jsonScript": {
"type": "logToMetric",
"query": {
"q": "L('default')::`nginx`:(count(`*`)) BY `host`",
"qtype": "dql",
"qmode": "selectorQuery"
},
"metricInfo": {
"every": "5m",
"metric": "recording_rules",
"metricField": "nginx_requests",
"unit": "custom/[\"custom\",\"次\"]",
"desc": "按host统计nginx请求数。",
"delaySeconds": 60
}
},
"extend": {
"funcName": "count",
"fieldKey": "*",
"source": "nginx",
"index": "default",
"groupBy": [
"host"
],
"filters": [],
"filterString": ""
},
"crontabInfo": {
"id": "cron_example",
"crontab": "0 */5 * * * *"
},
"createdWay": "manual",
"isLocked": 0,
"openPermissionSet": false,
"permissionSet": [],
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"creatorInfo": {},
"updatorInfo": {},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては、共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 404 | ft.NotFoundRuleInspector | ワークスペース内に指定された未削除ルールが存在しない(削除済みまたはクロスワークスペース UUID を含む) | 指定されたルール/インスペクターが見つかりません | 本モジュールのリストから有効な aggs UUID を再取得してください。 |
| 500 | ft.InternalServerError | ルールの読み取りまたはレスポンスの整形に失敗 | 内部エラー | ワークスペースと UUID を確認し、継続的に失敗する場合は traceId を提供してください。 |
| 403 | ft.Forbidden | API Key の権限が不足している、またはワークスペースのバージョンがこの機能をサポートしていない | 操作権限がありません | 対応する権限を持つ API Key と、メトリクスを生成する機能をサポートするワークスペースを使用してください。 |