Skip to content

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_example
How 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: monitor
How to obtain or enter: Select a single scope from the enumeration above.
pageIndex integer Optional, defaults to 1.
$minValue: 1
Example: 1
How to obtain or enter: View affected resource details starting from 1.
pageSize integer Optional, defaults to 50, maximum 1000.
$maxValue: 1000
$minValue: 1
Example: 50
How 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.

Feedback

Is this page helpful?