コンテンツにスキップ

スコープ影響プレビュー



POST /api/v1/tag/{tag_uuid}/scope/preview

概要

スコープ変更によってクリーンアップされるリソースとモニタリング設定をプレビューします。

呼び出し前の注意事項と使用手順

この API はタグやリソースを変更せず、影響を計算し、600 秒間の資格情報をキャッシュするだけです。scene/monitor/dialing/security スコープを削除すると、対応するエンティティ参照がクリーンアップされる場合があります。monitor を削除すると、ルールの extend.incidentsTags 内の該当名称も削除されます。インフラストラクチャ/統合カタログの名前バインディングはこのクリーンアップの対象外であり、通知条件、リソース権限、格納済みデータも変更しません。

data はビジネスリソース単位で重複排除され、summary/affectedResourceCount は全体量、pageInfo は data のみを制御します。プレビューに孤立参照がある場合、総関係数は表示リソース数より大きくなることがあります。呼び出しごとに新しい token が生成され、同じ token がその後の変更に適合する保証はありません。ページングではいずれも今回送信する scope に対応する token を取得し、送信前に影響を再確認してください。

パスパラメータ

パラメータ名 型 必須 説明
tag_uuid string Y このワークスペースのタグ UUID。タグ名、一覧の数値ページ番号、リソース UUID ではありません。
例: tag_example
取得または入力方法: タグ一覧 の content.data[].uuid から取得します。

リクエストヘッダー

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

リクエストボディパラメータ

パラメータ名 型 必須 説明
scope[*] string 配列のメンバー。all と具体的な値を混在させないでください。
例: monitor
取得または入力方法: 上記の列挙値から単一のスコープを選択します。
pageIndex integer 任意。デフォルトは 1。
$minValue: 1
例: 1
取得または入力方法: 1 から影響リソースの明細を確認します。
pageSize integer 任意。デフォルトは 50、最大 1000。
$maxValue: 1000
$minValue: 1
例: 50
取得または入力方法: 1 ページあたり 1~1000。
scope any Y 空でないスコープ配列。列挙値は all(グローバル)、scene(シーン)、monitor(モニタリング)、dialing(Synthetic テスト)、security(セキュリティ)、infrastructure(インフラストラクチャ)、catalog(統合カタログ)です。旧形式の単一値文字列との互換性があります。all は他の値と混在できません。重複値は重複排除され、固定の列挙順で返されます。[]/null/未知の値は受け付けません。新規作成/インポート時に省略した場合は ["all"] がデフォルトとなり、変更時に省略した場合は旧値を保持します。scope はタグの適用範囲のみを制限し、リソース権限を付与しません。インフラストラクチャ/統合カタログの名前バインディングは、ここでのエンティティ参照クリーンアップによって書き換えられません。
null を許可: False
例: ["scene", "monitor"]
取得または入力方法: タグをバインドするリソースのビジネスタイプに応じて選択します。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/tag/tag_example/scope/preview' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"scope":["scene"],"pageIndex":1,"pageSize":50}'

レスポンス

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

フィールド 型 説明
content.tagUUID string 対象タグ UUID。
content.oldScope array<string> 現在のスコープを正規化した配列。
content.oldScope[] string 個々の旧 scope。
content.newScope array<string> 対象スコープを正規化した配列。
content.newScope[] string 個々の新 scope。
content.requiresConfirmation boolean クリーンアップされるエンティティ参照またはモニタリング設定が存在するかどうか。公開 modify では token を省略して直接実行できます。
content.affectedResourceCount integer ビジネスリソース単位で重複排除した総数。関係数とは異なります。SLO 内部のルールは所属する SLO に統合されます。
content.affectedRelationCount integer クリーンアップが見込まれるエンティティ参照の件数。
content.affectedConfigCount integer incidentsTags のクリーンアップが見込まれるルール設定数。
content.orphanRelationCount integer 参照は存在するが対応する有効なリソースが欠落している関係の件数。関係への影響にも算入されます。
content.summary array<object> リソースタイプ別に集計した重複排除済みリソース数。
content.summary[].resourceType string dashboard/viewer/service/checker/smartMonitor/aiMonitor/incident/dialing/security/slo などの実際のビジネスタイプ。
content.summary[].count integer 該当タイプのリソース数。
content.data array<object> このページの影響リソース概要。
content.data[].resourceType string ビジネスリソースのカテゴリ。
content.data[].resourceUUID string リソース UUID。
content.data[].name string リソースの表示名。名前がない場合は UUID にフォールバックします。
content.data[].scope string このリソースが属する scope。
content.previewToken string 600 秒間有効なプレビュー資格情報。今回のアイデンティティ/ワークスペース/タグ/対象 scope/影響フィンガープリントにバインドされ、認証 Token ではありません。
content.declaration object 共通宣言。
pageInfo.pageIndex integer 明細のページ番号。
pageInfo.pageSize integer 明細のページサイズ。
pageInfo.totalCount integer 重複排除後の影響リソース総数。孤立参照は含みません。
{
  "code": 200,
  "content": {
    "tagUUID": "tag_example",
    "oldScope": [
      "all"
    ],
    "newScope": [
      "scene"
    ],
    "requiresConfirmation": true,
    "affectedResourceCount": 1,
    "affectedRelationCount": 1,
    "affectedConfigCount": 0,
    "orphanRelationCount": 0,
    "summary": [
      {
        "resourceType": "checker",
        "count": 1
      }
    ],
    "data": [
      {
        "resourceType": "checker",
        "resourceUUID": "rul_example",
        "name": "生产监控器",
        "scope": "monitor"
      }
    ],
    "previewToken": "PREVIEW-TOKEN",
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE",
  "pageInfo": {
    "pageIndex": 1,
    "pageSize": 50,
    "totalCount": 1
  }
}

エラーレスポンス

認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。

HTTP ステータス errorCode 発生条件 メッセージまたはレスポンスの説明 対応方法
406 ft.ParameterValidationFailed リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 パラメータ解析失敗 パラメータの位置、フィールド名、型、値を確認してください。
400 ft.RequestJsonFormatError リクエスト JSON の構文が無効 リクエスト JSON の形式エラー content.reason、line、column に従って JSON を修正してください。
404 ft.ObjectNotExists このワークスペースに対応する有効なタグがない、または削除済み 指定されたオブジェクトが存在しません 現在のワークスペース一覧から有効な UUID を取得してください。
406 ft.ParameterValidationFailed scope が無効、ページングが範囲外、またはクリーンアップ範囲に未知の参照タイプが含まれる パラメータ解析失敗 許可された scope を使用してください。未知の関連タイプは管理者に確認を依頼し、影響チェックを回避しないでください。
500 ft.InternalServerError タグ、参照/権限、またはアイデンティティ情報の読み取りとレスポンスのフォーマットに失敗 内部エラー ワークスペースとクエリ条件を確認し、後で再試行してください。継続的に失敗する場合は traceId を提供してください。

関連ドキュメント

フィードバック

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