スコープ影響プレビュー¶
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 を提供してください。 |