Scope Impact Preview¶
POST /api/v1/tag/{tag_uuid}/scope/preview
Overview¶
Preview the resources and monitoring configurations that will be cleaned up when the tag scope changes.
Before You Call and Usage Steps¶
This API does not modify tags or resources. It only calculates the impact and caches the credential for 600 seconds. When removing the scene/monitor/dialing/security scopes, the corresponding entity references may be cleaned up; removing monitor also removes this name from the rule's extend.incidentsTags. Infrastructure/Unified Catalog name bindings are not included in this cleanup, and notification conditions, resource permissions, or stored data are not changed.
data is deduplicated by business resource; summary/affectedResourceCount are for the full set, while pageInfo controls only data. When the preview has orphan references, the total relation count may be greater than the displayed resource count. Each call generates a new token; the same token is not guaranteed to work with later changes. For pagination, always use the token corresponding to the scope to be submitted in this call, and confirm the impact again before submission.
Path Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| tag_uuid | string | Y | UUID of the tag in this workspace, not the tag name, list numeric page number, or resource UUID. Example: tag_exampleHow to obtain or enter: Obtain from content.data[].uuid in Tag List. |
Request Headers¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| DF-API-KEY | string | Y | OpenAPI authentication credential for the workspace. Example: <DF-API-KEY>How to obtain or enter: Obtain an OpenAPI Key with the required operation permission from API Key Management in the target workspace. |
Body Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| scope[*] | string | Array member; do not mix all with specific values. Example: monitorHow to obtain or enter: Select a single scope from the enumeration above. |
|
| pageIndex | integer | Optional, defaults to 1. $minValue: 1 Example: 1How to obtain or enter: View affected resource details starting from 1. |
|
| pageSize | integer | Optional, defaults to 50, maximum 1000. $maxValue: 1000 $minValue: 1 Example: 50How to obtain or enter: 1..1000 per page. |
|
| scope | any | Y | Non-empty scope array. Enum values: all for global, scene for scene, monitor for monitor, dialing for synthetic tests, security for security, infrastructure for infrastructure, and catalog for Unified Catalog; compatible with legacy single-value strings. all cannot be mixed with other values; duplicate values are deduplicated and returned in a fixed enum order; []/null/unknown values are not accepted. When omitted on create/import, defaults to ["all"]; when omitted on modify, the old value is retained. scope only limits the tag's applicable scope and does not grant resource permissions; Infrastructure/Unified Catalog name bindings are not rewritten by the entity reference cleanup here. Allow null: False Example: ["scene", "monitor"]How to obtain or enter: Select based on the business type of the resource to which the tag needs to be bound. |
Example Request¶
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}'
Response¶
HTTP 200, application/json. The following example shows the main fields that can be read directly.
| Field | Type | Description |
|---|---|---|
| content.tagUUID | string | Target tag UUID. |
| content.oldScope | array<string> |
Normalized array of the current scope. |
| content.oldScope[] | string | A single old scope. |
| content.newScope | array<string> |
Normalized array of the target scope. |
| content.newScope[] | string | A single new scope. |
| content.requiresConfirmation | boolean | Whether there are entity references or monitoring configurations to be cleaned up; the public modify API can still be executed directly without the token. |
| content.affectedResourceCount | integer | Total after deduplication by business resource, not equal to the relation count; SLO internal rules are merged into their parent SLO. |
| content.affectedRelationCount | integer | Estimated number of entity references to be cleaned up. |
| content.affectedConfigCount | integer | Estimated number of rule configurations whose incidentsTags will be cleaned up. |
| content.orphanRelationCount | integer | Number of relations whose references exist but corresponding valid resources are missing; also included in the relation impact. |
| content.summary | array<object> |
Deduplicated resource counts by resource type. |
| content.summary[].resourceType | string | Actual business type, such as dashboard/viewer/service/checker/smartMonitor/aiMonitor/incident/dialing/security/slo. |
| content.summary[].count | integer | Resource count for this type. |
| content.data | array<object> |
Summary of affected resources on this page. |
| content.data[].resourceType | string | Business resource category. |
| content.data[].resourceUUID | string | Resource UUID. |
| content.data[].name | string | Resource display name; falls back to UUID when no name is available. |
| content.data[].scope | string | Scope to which the resource belongs. |
| content.previewToken | string | Preview credential valid for 600 seconds, bound to this identity/workspace/tag/target scope/impact fingerprint; not an authentication token. |
| content.declaration | object | Common declaration. |
| pageInfo.pageIndex | integer | Details page number. |
| pageInfo.pageSize | integer | Details page size. |
| pageInfo.totalCount | integer | Total number of affected resources after deduplication, excluding orphans. |
{
"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": "Production Monitor",
"scope": "monitor"
}
],
"previewToken": "PREVIEW-TOKEN",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE",
"pageInfo": {
"pageIndex": 1,
"pageSize": 50,
"totalCount": 1
}
}
Error Responses¶
For authentication, rate limiting, and common request errors, see Common Error Definitions.
| HTTP Status | errorCode | Trigger Condition | Message or Response Description | Handling |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | Request field is missing, or the field value violates the declared validation conditions | Parameter parsing failed | Check the parameter location, field name, type, and value. |
| 400 | ft.RequestJsonFormatError | Invalid request JSON syntax | Request JSON format error | Correct the JSON according to content.reason, line, and column. |
| 404 | ft.ObjectNotExists | No corresponding valid tag exists in this workspace, or it has been deleted | The specified object does not exist | Obtain a valid UUID from the current workspace list. |
| 406 | ft.ParameterValidationFailed | Invalid scope, pagination out of bounds, or the cleanup scope contains an unknown reference type | Parameter parsing failed | Use an allowed scope; for unknown association types, ask the administrator to verify and do not bypass the impact check. |
| 500 | ft.InternalServerError | Failed to read the tag, references/permissions, or identity profile, or to format the response | Internal error | Check the workspace and query conditions, try again later, and provide the traceId if the failure persists. |