コンテンツにスキップ

変更



POST /api/v1/slo/{slo_uuid}/modify

概要

既存 SLO の変更可能な設定および関連付けを変更します。

呼び出し前の確認と使用手順

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

name/goal/minGoal/sliType は変更不可で、省略するか元の値をそのまま送信する必要があります。checkRange、interval、説明、ステータス、関連付けは変更できます。sliUUIDs/alertPolicyUUIDs/tags が出現した場合は全体を置換します。追加したい 1 項目だけを渡すことはできません。既存の関連付けは、事前に詳細を読み取ってバックアップしてください。通常の {} リクエストでも既存設定を検証し、実行設定および更新時刻を更新するため、無操作ではありません。旧来の不正な期間は、明示的に 7 日または 30 日を選択する必要があります。

メトリクス型の metricQueries は total/good を同時に送信する必要があります。クエリ言語または実行テキスト、checkRange を変更した場合、または再度有効化した場合は統計の有効下限が進むため、履歴結果を新しい定義と直接混在計算できません。editor のみの変更では進みません。モニター型でディメンションを変更する場合は、ソースイベント/メトリクスのディメンションが完全であることを併せて確認してください。メトリクス型では good/total で可用性を計算し、業務上のパーセンテージをそのままカウントとして混在させないでください。DQL は各クエリを比較可能な単一の数値に集約する必要があり、実際のデータと権限は事前に検証してください。PromQL では sum(...) などの集約を使用できます。本エンドポイントは promqlType を一律にインスタントクエリとして扱います。モニター型は SLI モニターを参照して減点を計算し、SLO 結果を生成します。groupBy を設定した後は project/env/service ディメンションごとに個別に計算します。アラートポリシーが設定されていない場合、そのポリシーの通知関連付けは存在しません。保存に成功しても、通知が送信されたことは保証されません。

作成、変更、有効化/無効化はローカルトランザクションの末尾でコミットされ、失敗時はリモートスケジューリングとキャッシュの復旧を試みます。リモート補償も失敗する可能性があるため、HTTP 失敗によってすべてのシステムに変更がないと判断することはできません。ネットワークタイムアウト/500 の後は、まず SLO 詳細を取得 で設定とステータスを確認し、必要に応じて管理者にスケジューリングを確認してもらってから再試行してください。保存の成功は検出結果が既に生成されたことを意味しません。検出頻度の経過を待ち、実際のデータを確認する必要があります。本エンドポイントは完全なタグ/ポリシー/ユーザーサマリーを返しません。詳細を読み戻して検証してください。

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

ルートパラメータ

パラメータ名 型 必須 説明
slo_uuid string Y 対象 SLO UUID。SLI モニター UUID や metricQueryInfo.sloId ではありません。
null 許可: False
例: monitor_example
取得または入力方法: SLO 一覧を取得 から content.data[].uuid を読み取ります。

リクエストヘッダー

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

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 任意の配列。作成時に省略すると関連付けず、変更時に省略すると保持し、[] で全関連付けを解除します。渡す場合は全体を置換して重複を排除し、未知/削除済み/他のワークスペースのポリシーは拒否します。本エンドポイントで通知先や 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 作成時に必須の数値で、0<goal<100。変更時は省略するか元の値のみ送信できます。例 99.9 は 99.9% を表し、0.999 ではありません。
null 許可: False
例: 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 作成時は 5m または 10m が必須で、変更時に省略すると保持します。checkRange の統計ウィンドウとは異なる概念です。
null 許可: False
選択可能な値: ['5m', '10m']
例: 5m
取得または入力方法: 必要に応じて検出頻度を選択します。
metricQueries object メトリクス型のみ。作成時は必須で、変更時に省略すると保持し、出現時は total/good を組全体で置換します。部分的な patch や null は受け付けません。オブジェクトは正確に total と good を含みます。各項目は dql/queryType/editor および PromQL の promqlType をサポートし、その他の実行オプションは受け付けません。2 項目は同じ業務範囲/時間単位の総量と成功量を測定し、比較可能性を保証する必要があります。本 API は保存時に顧客の業務上の正しさを検証しません。
null 許可: False
例: {"total": {"dql": "M::http_requests:(SUM(`total`))"}, "good": {"dql": "M::http_requests:(SUM(`good`))"}}
取得または入力方法: メトリクスデータから総量と成功量のフィールドを特定し、まず データをクエリ で各クエリの数値と収集範囲を検証します。
minGoal float 作成時に必須の数値で、0<minGoal<goal<100。変更時は省略するか元の値のみ送信できます。minGoal 未満は critical、minGoal 以上 goal 未満は warning です。
null 許可: False
例: 99.5
取得または入力方法: 最低許容可用性に基づいて設定します。単位はパーセントです。
name string 作成時は必須の文字列で、最大 256 文字、同一ワークスペース内のアクティブな SLO で重複した名前は使用できません。呼び出し元は非空の名前を指定してください。変更時は省略できますが、送信する場合は元の名前と完全に一致する必要があります。
null 許可: False
例: 支付服务可用性
取得または入力方法: 呼び出し元が 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 を含むタグ名を選択します。新しい名前を渡すこともできます。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/slo/monitor_example/modify' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"describe":"更新生产SLO维护说明","interval":"10m"}'

レスポンス

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 作成した API キーリソース 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": 123,
    "uuid": "monitor_example",
    "workspaceUUID": "wksp_example",
    "name": "支付服务可用性",
    "type": "slo",
    "score": 0,
    "status": 0,
    "creator": "wsak_example",
    "updator": "wsak_example",
    "createAt": 1785427200,
    "updateAt": 1785427260,
    "deleteAt": -1,
    "config": {
      "goal": 99.9,
      "minGoal": 99.5,
      "interval": "5m",
      "checkRange": 604800,
      "sliType": "monitor",
      "describe": "支付服务生产环境SLO",
      "groupBy": []
    },
    "declaration": {}
  },
  "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 ファイル形式エラー オブジェクトを送信します。
404 ft.NotFoundSLO 対象が現在のワークスペースにない、削除済み、または SLO ではない。変更の場合は必要な検出/計算コンポーネントの欠落も含む 指定された SLO が見つかりません 現在のワークスペースの SLO 一覧から uuid を取得します。対象がまだ存在することを確認し、コンポーネントが欠落している場合は管理者に修復を依頼します。
400 ft.ParamsValidateError メトリクスクエリ/期間/ディメンションなど公開済みフィールドの業務的な組み合わせが不正 パラメータ検証失敗: {} 2 種類の型のパラメータ制約に従って修正し、元の名前、目標、型を保持します。サーバー側フィールドを送信しないでください。
400 ft.SloImmutableField name/goal/minGoal/sliType が元の設定と異なる SLO 作成後はフィールドを変更できません:name 元の値を保持します。定義を変更する場合は別の SLO を作成し、依存関係を移行します。
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 権限チェックを通過したが、現在の API キーにメトリクスクエリ権限がない {} に対する権限がありません API キーのロールに目標メトリクスのクエリ権限を追加し、同じ API キーでクエリを検証してから保存します。

フィードバック

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