コンテンツにスキップ

作成



POST /api/v1/slo/add

概要

モニター型またはメトリック型SLOとその検出設定を作成します。

呼び出し前と使用手順

現在のAPI Keyにはmonitor.sloCfgManageが必要です。メトリック型の保存には対象メトリックのnamespaceクエリ権限も必要であり、SLO管理権限だけではこの事前チェックを通過できません。Keyが所属するワークスペースのみを操作します。パス内のSLO UUIDは获取SLO列表のcontent.data[].uuid(通常はmonitor_プレフィックス)を使用し、関連するモニターのRule UUIDやmetricQueryInfo.sloIdではありません。

メトリック型はgood/totalで可用性を計算し、ビジネスのパーセント値をそのままカウントとして混在させることはできません。DQLは各クエリを比較可能な単一の数値に集約する必要があり、実際のデータと権限を事前に検証してください。PromQLではsum(...)などの集約を使用でき、本APIはpromqlTypeを一律にインスタントクエリとして扱います。モニター型はSLIモニターを参照して減点を計算し、SLO結果を生成します。groupByを設定した場合、project/env/serviceディメンションごとに個別に計算します。アラートポリシーが設定されていない場合、そのポリシーによる通知の関連付けはなく、保存が成功しても通知が送信済みであることは保証されません。

作成、変更、および有効化/無効化はローカルトランザクションの最後にコミットされ、失敗時はリモートのスケジューリングとキャッシュの復旧を試みます。リモート側の補償処理も失敗する可能性があり、HTTPエラーだけで全システムに変更がないと判断することはできません。ネットワークタイムアウトまたは500エラーが発生した場合は、まず获取SLO详情で設定と状態を確認し、必要に応じて管理者にスケジューリングの確認を依頼してから再試行してください。保存が成功しても検出結果が生成済みであるとは限らず、検出頻度を待って実際のデータを確認する必要があります。作成は冪等ではありません。重複する名前は拒否されますが、リクエスト結果が不明な場合でもまず名前で検索してください。作成レスポンスには完全なtagInfoやalertPolicyInfosは含まれないため、保存後に詳細を取得して関連付けを確認してください。

metricResultValidAfter/metricResultStoppedAt/metricQueryInfoなどのサーバー専用フィールドは送信しないでください。非公開のBodyフィールドは、ルート宣言で共通の406パラメータエラーとして先に拒否されます。

リクエストヘッダー

パラメータ名 型 必須 説明
DF-API-KEY string Y ワークスペースの OpenAPI 認証情報。
例: <DF-API-KEY>
取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。

Body リクエストパラメータ

パラメータ名 型 必須 説明
metricQueries.total object 合計量クエリオブジェクト。dqlが必須で、editorのみでは提供できません。
例: {"dql": "M::http_requests:(SUM(`total`))"}
取得または入力方法: 対象メジャーメントと対応する業務フィールドから構築します。
metricQueries.total.dql string 必須の空でないクエリ文字列で、最大65536文字です。queryType=dqlの場合、現在のワークスペースのMメトリックに対する単一出力のSELECTまたは有効なeval式のみをサポートし、SHOW/その他の実行関数、クロスワークスペースメトリック、DQL独自のウィンドウはサポートしません。呼び出し元は事前に単一の比較可能な数値へ集約し、結果を検証して、GROUP BYによる複数シリーズの生成を避けてください。queryType=promqlの場合、本フィールド名は引き続きdqlであり、有効なPromQLを入力します。
例: M::http_requests:(SUM(`total`))
取得または入力方法: そのメトリッククエリの言語と業務フィールドによって決定されます。
metricQueries.total.queryType string 任意のdql/promqlで、省略時はdqlです。dql文字列の解析言語と実行言語を決定します。
例: dql
取得または入力方法: そのメトリッククエリの言語と業務フィールドによって決定されます。
metricQueries.total.promqlType string queryType=promqlの場合にのみ指定できます。instantQuery/rangeQueryを入力できますが、保存および実行時は一律instantQueryとなり、rangeQueryを渡したからといって範囲結果を要求することはできません。DQL分岐でこのキーが出現すると拒否されます。
例: instantQuery
取得または入力方法: そのメトリッククエリの言語と業務フィールドによって決定されます。
metricQueries.total.editor object 任意の返却用オブジェクトで、省略時は{}です。エディタの状態を保存し、実行クエリの比較には使用しません。変更時はクエリオブジェクト全体が置き換えられます。
例: {}
取得または入力方法: そのメトリッククエリの言語と業務フィールドによって決定されます。
metricQueries.good object 成功量クエリオブジェクト。dqlが必須で、editorのみでは提供できません。
例: {"dql": "M::http_requests:(SUM(`good`))"}
取得または入力方法: 対象メジャーメントと対応する業務フィールドから構築します。
metricQueries.good.dql string 必須の空でないクエリ文字列で、最大65536文字です。queryType=dqlの場合、現在のワークスペースのMメトリックに対する単一出力のSELECTまたは有効なeval式のみをサポートし、SHOW/その他の実行関数、クロスワークスペースメトリック、DQL独自のウィンドウはサポートしません。呼び出し元は事前に単一の比較可能な数値へ集約し、結果を検証して、GROUP BYによる複数シリーズの生成を避けてください。queryType=promqlの場合、本フィールド名は引き続きdqlであり、有効なPromQLを入力します。
例: M::http_requests:(SUM(`good`))
取得または入力方法: そのメトリッククエリの言語と業務フィールドによって決定されます。
metricQueries.good.queryType string 任意のdql/promqlで、省略時はdqlです。dql文字列の解析言語と実行言語を決定します。
例: dql
取得または入力方法: そのメトリッククエリの言語と業務フィールドによって決定されます。
metricQueries.good.promqlType string queryType=promqlの場合にのみ指定できます。instantQuery/rangeQueryを入力できますが、保存および実行時は一律instantQueryとなり、rangeQueryを渡したからといって範囲結果を要求することはできません。DQL分岐でこのキーが出現すると拒否されます。
例: instantQuery
取得または入力方法: そのメトリッククエリの言語と業務フィールドによって決定されます。
metricQueries.good.editor object 任意の返却用オブジェクトで、省略時は{}です。エディタの状態を保存し、実行クエリの比較には使用しません。変更時はクエリオブジェクト全体が置き換えられます。
例: {}
取得または入力方法: そのメトリッククエリの言語と業務フィールドによって決定されます。
sliUUIDs[*] string 単一の文字列項目です。配列にはオブジェクト/配列/nullを含めないでください。
例: rul_example
取得または入力方法: 监控器列表 から content.data[].uuid を取得し、searchで名前を検索できます。同一ワークスペース内で未削除かつSLIとして使用可能なモニターであることを確認してください。
alertPolicyUUIDs[*] string 単一の文字列項目です。配列にはオブジェクト/配列/nullを含めないでください。
例: altpl_example
取得または入力方法: 告警策略列表 から本ワークスペースの有効なポリシーuuidを取得します。
tags[*] string 単一の文字列項目です。配列にはオブジェクト/配列/nullを含めないでください。
例: production
取得または入力方法: 标签列表 から scope に monitor または all を含むタグ名を選択します。新しい名前を渡すこともできます。
groupBy[*] string 単一の文字列項目です。配列にはオブジェクト/配列/nullを含めないでください。project/env/serviceのみです。
例: service
取得または入力方法: 収集済みのproject/env/serviceディメンションを選択し、ソースのモニターイベント/サービスデータに対応するフィールドがあることを確認する必要があります。
alertPolicyUUIDs array 任意の配列です。作成時に省略すると関連付けず、変更時に省略すると保持し、[]で全関連付けを解除します。指定時は全量置換して重複を排除し、不明/削除済み/他のワークスペースのポリシーは拒否されます。本APIでは通知先やalertOptを直接設定しません。
null許可: False
例: ["altpl_example"]
取得または入力方法: 告警策略列表 から本ワークスペースの有効なポリシーuuidを取得します。
checkRange integer 統計ウィンドウの秒数で、604800/2592000のみです。作成時に省略すると604800、変更時に省略すると保持します。旧90日などの履歴設定は、サポート対象の値に明示的に変更しないと保存できません。
null許可: False
選択可能な値: [604800, 2592000]
例: 604800
取得または入力方法: SLO統計の要件に応じて7日または30日を選択します。
describe string 任意の文字列で、最大3000文字です。作成時に省略すると空文字列、変更時に省略すると保持し、空文字列でクリアします。nullは許可されません。
空文字列許可: True
null許可: False
最大長: 3000
例: 支付服务生产环境SLO
取得または入力方法: 呼び出し元が用途/保守説明を入力します。
goal float Y 作成時は必須の数値で、0<goal<100です。変更時は省略するか元の値のみを渡せます。例の99.9は99.9%を表し、0.999ではありません。
null許可: False
より大きい: 0
より小さい: 100
例: 99.9
取得または入力方法: 業務SLAに基づいて期待目標を設定します。単位はパーセントです。
groupBy array モニター型のみサポートします。配列内ではproject/env/serviceのみ許可され、重複不可で、順序は保持されます。作成時のデフォルトは[]、変更時に省略すると保持し、[]でグループ化を解除します。メトリック型では省略するか[]を指定します。
null許可: False
例: ["service"]
取得または入力方法: 収集済みのproject/env/serviceディメンションを選択し、ソースのモニターイベント/サービスデータに対応するフィールドがあることを確認する必要があります。
ignoreBadGroupEvents boolean モニター型のみ指定できます。デフォルトはtrueです。groupByが空でない場合にのみ保存され、計算に使用されます。変更時に省略すると保持し、グループを新規追加して元の値が存在しない場合はtrueになります。groupByを解除するとこの設定は削除されます。メトリック型ではfalseを渡しても拒否されます。
null許可: False
例: true
取得または入力方法: groupByがある場合、異常なグループイベントを無視するかどうかに応じて選択します。
interval string Y 作成時は5mまたは10mが必須で、変更時に省略すると保持します。checkRangeの統計ウィンドウとは異なる概念です。
null許可: False
選択可能な値: ['5m', '10m']
例: 5m
取得または入力方法: 必要に応じて検出頻度を選択します。
metricQueries object メトリック型のみです。作成時は必須、変更時に省略すると保持し、指定時はtotal/goodを組全体で置換します。部分的なpatchやnullは受け付けません。オブジェクトには正確にtotalとgoodを含めます。各項目はdql/queryType/editorおよびPromQLのpromqlTypeをサポートし、その他の実行オプションは受け付けません。両項目は同じ業務範囲/時間単位の合計量と成功量を測定し、比較可能性を確保する必要があります。APIは保存時に顧客の業務上の正しさを検証しません。
null許可: False
例: {"total": {"dql": "M::http_requests:(SUM(`total`))"}, "good": {"dql": "M::http_requests:(SUM(`good`))"}}
取得または入力方法: メトリックデータから合計量と成功量のフィールドを特定し、まず查询数据で各クエリの数値と収集範囲を検証します。
minGoal float Y 作成時は必須の数値で、0<minGoal<goal<100です。変更時は省略するか元の値のみを渡せます。minGoal未満はcritical、minGoal以上かつgoal未満はwarningです。
null許可: False
より大きい: 0
より小さい: 100
例: 99.5
取得または入力方法: 許容できる最低可用性に基づいて設定します。単位はパーセントです。
name string Y 作成時は必須の文字列で、最大256文字です。同一ワークスペース内のアクティブなSLOで名前を重複させることはできません。呼び出し元は空でない名前を指定してください。変更時は省略できますが、送信する場合は元の名前と完全に一致させる必要があります。
null許可: False
最大長: 256
例: 支付服务可用性
取得または入力方法: 呼び出し元がSLOに名前を指定します。変更前に詳細を取得してください。
sliType string 作成時のデフォルトはmonitorで、monitor/metricを選択できます。作成後は切り替えできず、変更時に省略すると保持し、値を渡す場合は元の値のみ許可されます。
null許可: False
選択可能な値: ['monitor', 'metric']
例: monitor
取得または入力方法: 既存のモニターで計算するか、メトリッククエリで計算するかを選択します。
sliUUIDs array モニター型の作成時は非空が必須です。変更時に省略すると参照を保持し、[]で参照をクリアします(SLOに有効なSLIがなくなる可能性があるため、事前に確認してください)。全量置換して重複を排除し、順序は保証されません。メトリック型では省略するか[]を指定し、非空にしてはいけません。同一ワークスペース内でアクティブかつtype=triggerまたは旧空typeのルールのみをSLIに使用します。現在の保存処理は無効なUUIDや他のワークスペースのUUIDを個別に拒否しないため、成功しても各項目が計算可能であることを証明できません。nullは許可されません。
null許可: False
例: ["rul_example"]
取得または入力方法: 监控器列表 から content.data[].uuid を取得し、searchで名前を検索できます。同一ワークスペース内で未削除かつSLIとして使用可能なモニターであることを確認してください。
status integer 任意で0は有効/2は無効です。作成時のデフォルトは0、変更時に省略すると保持します。nullは許可されません。
null許可: False
選択可能な値: [0, 2]
例: 0
取得または入力方法: すぐに検出を開始するかどうかに応じて選択します。
tags array 名前の配列で、各項目は最大128文字、大文字と小文字を区別します。新しい名前はmonitorスコープで作成されます。作成時に省略するとタグなし、変更時に省略すると保持し、[]でクリアします。全量置換して重複を排除します。同名タグが既に存在しmonitorをサポートしない場合は400になります。nullは許可されません。
null許可: False
例: ["production"]
取得または入力方法: 标签列表 から scope に monitor または all を含むタグ名を選択します。新しい名前を渡すこともできます。

パラメータ補足説明

SLI UUIDはモニターリストのRule uuidを使用します。アラートはalertPolicyUUIDsでアラートポリシーを関連付け、その後ポリシーで通知を制御します。旧文書のalertOpt/alertTargetは送信しないでください。本エンドポイントではこれらのフィールドを公開していません。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/slo/add' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"name":"支付服务可用性","interval":"5m","goal":99.9,"minGoal":99.5,"sliUUIDs":["rul_example"]}'

レスポンス

HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。

フィールド 型 説明
content.id integer または null データベース行ID。作成レスポンスはコミット前に生成されるためnullになり得ます。業務上の識別子にはuuidを使用します。
content.uuid string SLO UUID。以降の詳細取得、変更、有効化/無効化、削除で使用します。
content.workspaceUUID string 対象ワークスペースUUID。
content.name string SLO名。
content.type string 固定値slo。
content.score integer リソースの並び順の重みで、SLO可用性のパーセントではありません。
content.status integer 0は有効/2は無効。
content.creator string 作成KeyのリソースUUIDまたは履歴アカウント識別子。
content.updator string 最新更新主体。作成時は空になり得ます。
content.createAt integer 作成時刻(Unix秒)。
content.updateAt integer 最新更新時刻(Unix秒)。未更新の場合は-1になり得ます。
content.deleteAt integer 削除時刻。正常にアクティブなレコードでは-1です。
content.config object 保存後のSLO計算設定。直接の通知先設定alertOptは含みません。
content.config.sliType string monitorまたはmetric。旧設定で欠落している場合はmonitorを返します。
content.config.checkRange integer 統計ウィンドウの秒数。604800または2592000。
content.config.goal number 期待目標のパーセント。
content.config.minGoal number 最低目標のパーセント。
content.config.interval string 5mまたは10m。
content.config.describe string 用途説明。
content.config.groupBy array<string> モニター型のグループ化ディメンション配列。メトリック型では空です。
content.config.groupBy[] string project/env/serviceのいずれか。
content.config.ignoreBadGroupEvents boolean グループ化ディメンションが存在する場合にのみ返されます。異常なグループイベントを無視するかどうか。
content.config.sli_infos array<object> または object 今回SLIサマリーを読み込む場合に存在します。モニター型では通常オブジェクト配列、メトリック型の作成時は現在{}です。変更時にsliUUIDsを送信しない場合は省略され得ます。本フィールドを完全な参照UUIDリストとして扱うことはできません。
content.config.sli_infos[].id string 実際に本ワークスペースの有効なSLIモニターに一致したRule UUID。
content.config.sli_infos[].name string または null SLIモニター名。
content.config.sli_infos[].status integer 関連するモニターの状態で、0または2になり得ます。存在しない参照はサマリーに含まれません。
content.config.metricResultValidAfter integer または null メトリック型のみ: 今回の統計が有効になる下限(Unixミリ秒)。作成、ウィンドウ/実行クエリの変更、無効から有効への切り替えでリセットされます。editorのみの変更ではリセットされません。
content.config.metricResultStoppedAt integer または null メトリック型のみ: 計算停止時刻(Unixミリ秒)。実行中はnullで、無効化時に記録されます。
content.metricQueryInfo object メトリック型のみ: クエリ結果の位置情報であり、元の業務メトリック値ではありません。
content.metricQueryInfo.measurement string 固定値slo_metric。
content.metricQueryInfo.sloId string 実際の検出Rule UUID。slo_metric.slo_idのクエリに使用します。content.uuidとは異なります。
content.metricQueryInfo.validAfter integer または null config.metricResultValidAfterと同じ。
content.metricQueryInfo.stoppedAt integer または null config.metricResultStoppedAtと同じ。
content.declaration object 現在のワークスペースの共通宣言。
content.config.metricQueries.total.dql string 正規化後の実行クエリ。
content.config.metricQueries.total.queryType string dqlまたはpromql。
content.config.metricQueries.total.promqlType string PromQLのみ返され、固定値instantQuery。
content.config.metricQueries.total.editor object 呼び出し元のエディタ返却情報。
content.config.metricQueries.total.editor.カスタムフィールド JSON 呼び出し元が渡した動的編集状態。サーバー側の実行オプションとしては解釈されません。
content.config.metricQueries.good.dql string 正規化後の実行クエリ。
content.config.metricQueries.good.queryType string dqlまたはpromql。
content.config.metricQueries.good.promqlType string PromQLのみ返され、固定値instantQuery。
content.config.metricQueries.good.editor object 呼び出し元のエディタ返却情報。
content.config.metricQueries.good.editor.カスタムフィールド JSON 呼び出し元が渡した動的編集状態。サーバー側の実行オプションとしては解釈されません。
content.config.metricQueries object メトリック型のみ。totalとgoodの完全な正規化設定。
content.config.metricQueries.total object 合計量クエリ設定。
content.config.metricQueries.good object 成功量クエリ設定。
{
  "code": 200,
  "content": {
    "id": null,
    "uuid": "monitor_example",
    "workspaceUUID": "wksp_example",
    "name": "支付服务可用性",
    "type": "slo",
    "score": 0,
    "status": 0,
    "creator": "wsak_example",
    "updator": "",
    "createAt": 1785427200,
    "updateAt": -1,
    "deleteAt": -1,
    "config": {
      "goal": 99.9,
      "minGoal": 99.5,
      "interval": "5m",
      "checkRange": 604800,
      "sliType": "monitor",
      "describe": "支付服务生产环境SLO",
      "groupBy": [],
      "sli_infos": [
        {
          "id": "rul_example",
          "name": "支付接口成功率",
          "status": 0
        }
      ]
    },
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}
curl --request POST '<Endpoint>/api/v1/slo/add' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"name":"支付指标成功率","sliType":"metric","goal":99.9,"minGoal":99.5,"interval":"5m","metricQueries":{"total":{"dql":"M::http_requests:(SUM(`total`))"},"good":{"dql":"M::http_requests:(SUM(`good`))"}}}'
{
  "code": 200,
  "content": {
    "id": null,
    "uuid": "monitor_example",
    "workspaceUUID": "wksp_example",
    "name": "支付指标成功率",
    "type": "slo",
    "score": 0,
    "status": 0,
    "creator": "wsak_example",
    "updator": "",
    "createAt": 1785427200,
    "updateAt": -1,
    "deleteAt": -1,
    "config": {
      "goal": 99.9,
      "minGoal": 99.5,
      "interval": "5m",
      "checkRange": 604800,
      "sliType": "metric",
      "describe": "",
      "groupBy": [],
      "sli_infos": {},
      "metricQueries": {
        "total": {
          "dql": "M::http_requests:(SUM(`total`))",
          "queryType": "dql",
          "editor": {}
        },
        "good": {
          "dql": "M::http_requests:(SUM(`good`))",
          "queryType": "dql",
          "editor": {}
        }
      },
      "metricResultValidAfter": 1785427200000,
      "metricResultStoppedAt": null
    },
    "declaration": {},
    "metricQueryInfo": {
      "measurement": "slo_metric",
      "sloId": "rul_slo_detect_example",
      "validAfter": 1785427200000,
      "stoppedAt": null
    }
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラー応答

認証、レート制限、および共通リクエストエラーについては公共错误定义を参照してください。

HTTPステータス errorCode 発生条件 メッセージまたはレスポンス説明 対処方法
406 ft.ParameterValidationFailed リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している パラメータ解析失敗 パラメータの位置、フィールド名、型、値を確認します。
400 ft.RequestJsonFormatError リクエストJSONの構文が無効 リクエストJSONの形式エラー content.reason、line、columnに従ってJSONを修正します。
400 ft.JsonFormatError JSONのトップレベルがオブジェクトではない 一部のjsonファイルの形式エラー JSONオブジェクトを送信します。
400 ft.ParamsValidateError メトリッククエリ/周期/ディメンションなど公開済みフィールドの業務上の組み合わせが不正 パラメータ検証失敗: {} 2つの型のパラメータ制約に従って修正し、元の名前、目標、型を保持します。サーバー側フィールドは送信しないでください。
400 ft.SloNameRepeat 本ワークスペースのアクティブなSLOで既にこの名前が使用されている SLO名は既に存在します。再入力してください まずリストで既存オブジェクトを確認します。更新が必要な場合は元のuuidで変更します。
406 ft.SloMinGoalGreaterThanGoal minGoalがgoal以上 minGoalはgoalより小さい必要があります。現在 minGoal: 99.9 goal: 99.9 0<minGoal<goal<100を保証します。
400 ft.InvalidAlertPolicyUUID alertPolicyUUIDsに本ワークスペースで有効でないポリシーが含まれている 無効なアラートポリシーUUID 現在のワークスペースのアラートポリシーリストから再取得します。
400 ft.TagScopeMismatch 同名タグが既に存在し、scopeにmonitorまたはallが含まれていない production: ['scene'] -> monitor モニタリングに使用可能なタグを選択します。他の専用スコープの同名タグを直接再利用しないでください。
406 ft.ExceedMaxCharacterLimit タグ名が128文字を超えている {}が最大文字長制限を超えています タグ名を短縮し、業務上識別可能な状態を保ちます。
400 ft.FiledCreateTrigger スケジューリング作成の応答にタスクIDがない トリガー設定の作成に失敗しました。再試行してください まずSLOと残留タスクを確認し、スケジューリングを修正してから再試行します。
400 ft.OuterFuncFailed リモートスケジューリングサービスが失敗を返した 外部関数呼び出し失敗(一部の分岐では下流のmessageを使用) messageとtraceIdを確認し、管理者にスケジューリングの可用性と設定の現状を確認してもらってから再試行します。
400 ft.SameSetTraggerExists リモートスケジューリングサービスが同じトリガー設定の既存を報告 同じ設定のトリガーが既に存在します まず該当SLOとリモートスケジューリングを確認し、残留/重複設定を処理してから送信します。
500 ft.InternalServerError データベース/キャッシュ、タスクキュー、不正な配列メンバー、または未処理の下流例外。失敗時でもリモート変更が既に存在する可能性があります 内部エラー まず対象SLOの設定とスケジューリングの現状を確認します。削除失敗の場合は削除済み状態も確認し、盲目的に作成を繰り返したり一括上書きしたりしないでください。
403 ft.ForbiddenQuery メトリック型クエリがnamespace権限チェックを通過したが、現在のKeyにメトリッククエリ権限がない {}の権限がありません Keyのロールに対象メトリックのクエリ権限を追加し、まず同じKeyでクエリを検証してから保存します。

フィードバック

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