Skip to content

Batch Set Workspace AI Master Switch



POST /api/v1/workspace/ai_analysis/batch_set

Overview

Batch set the workspace AI master switch.

Before Calling and Usage Steps

First, confirm all target active workspaces from the Workspace List. Duplicate UUIDs are counted once; the returned count is the number of deduplicated requested workspaces, not the number of changed workspaces. This operation only modifies the workspace enableAI, and does not change the incident auto-analysis configuration. After the master switch is turned off, the original incident configuration values are retained; if you need to keep a capability disabled, manage the two switches separately. Setting the same value can succeed; only actual changes record the corresponding state-change audit. Alert configuration refresh is performed asynchronously; a task enqueue failure may be logged while success is still returned.

Request Headers

Parameter Type Required Description
X-Df-SVersion string Must be consistent with the example; do not omit it and continue using this algorithm.
Example: v20240417
How to obtain or fill in: fill it in together with the signing algorithm for the original path and request body on this page.
X-Df-Access-Key string Y All seven items here are write operations and require External write permission.
Example: <external-access-key>
How to obtain or fill in: assigned by the site administrator as an External API AK with w permission; it is not a workspace OpenAPI Key.
X-Df-Nonce string Y Update this value and the signature on every resend as well.
Example: 97d275ee9f774315a7885ba7347acbd9
How to obtain or fill in: generate a new uuid.uuid4().hex for each request.
X-Df-Signature string Y Concatenate the uppercase method, nonce, original full path, timestamp, and original UTF-8 request body with spaces, then compute the HMAC-SHA256 hex digest.
Example: <hmac-sha256-hex>
How to obtain or fill in: use the matching SK to calculate it according to External API Signature Authentication and the Python template below.
X-Df-Timestamp string Y Do not reuse the fixed time in the example; it must be within the site's signature validity window.
Example: 1785427200
How to obtain or fill in: when sending, use str(int(time.time())) to generate the current Unix seconds.

Body Request Parameters

Parameter Type Required Description
workspaceUUIDs[*] string A single active workspace UUID; leading and trailing whitespace is removed before order-preserving deduplication.
Example: wksp_example001
How to obtain or fill in: obtain each item from content.data[].uuid in the Workspace List.
enableAI boolean Y Required JSON boolean. Does not change enableAIAnalysis at the same time.
Allow null: False
Example: true
How to obtain or fill in: pass true to enable or false to disable according to business requirements; this is not a string.
workspaceUUIDs array Y Required non-empty string array; trim leading and trailing whitespace from each item and deduplicate in first-occurrence order. If any workspace is invalid, the entire batch fails first. Do not enter an account UUID or collection Token.
Allow null: False
Example: ["wksp_example001"]
How to obtain or fill in: select target workspaces from content.data[].uuid in the Workspace List; each must be active with status=0.

Additional Parameter Notes

Use site-level External API credentials with w permission. For authentication, see External API Signature Authentication. The example calculates the signature according to v20240417; signing and sending use the same path, Query, and original request body. All examples are demonstration values; replace them with actual targets before execution. After a write request times out or returns 500, query the current state first, and then decide whether to retry. API success does not mean the alert pipeline has consumed the new state; verify with actual new events.

Request Example

import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen

# Replace with the target site address and the External API AK/SK assigned by the administrator.
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'POST'
path = '/api/v1/workspace/ai_analysis/batch_set'
query = {}
data = {'workspaceUUIDs': ['wksp_example001'], 'enableAI': True}
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
    "X-Df-Access-Key": access_key,
    "X-Df-Timestamp": timestamp,
    "X-Df-Nonce": nonce,
    "X-Df-Signature": signature,
    "X-Df-SVersion": "v20240417",
}
if data is not None:
    headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
    print(result.read().decode("utf-8"))

Response

HTTP 200, application/json, unified response envelope. The business result is in content; External does not automatically inject declaration. The declaration in the workspace object is its own stored field.

Field Type Description
content.workspaceUUIDs string array Active workspace UUIDs after whitespace removal and order-preserving deduplication.
content.count integer Number of requested workspaces after deduplication, not the number actually changed.
content.enableAI boolean Switch value set for all target workspaces in this request.
{
  "code": 200,
  "content": {
    "workspaceUUIDs": [
      "wksp_example001"
    ],
    "count": 1,
    "enableAI": true
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

Error Response

For authentication, rate limiting, and common request errors, see Common Error Definitions.

The table below lists the main confirmed error branches for this API's business validation. Downstream services may also return other 4xx errors mapped from specific errors; ordinary 5xx and unknown exceptions are handled globally and return ft.InternalServerError. For write requests, determine whether they have taken effect based on the current configuration and error content; do not infer rollback solely from the HTTP status.

HTTP Status errorCode Trigger Condition Message or Response Description Handling
406 ft.ParameterValidationFailed A 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.
400 ft.JsonFormatError JSON top level is not an object Some JSON file format error Submit a JSON object according to the parameter table; do not use an array or null as the entire request body.
400 ft.ParamsValidateError Request business validation finds that the switch is not a boolean, the UUID list is empty, or an element is not a non-empty string Parameter validation failed: {} Use a JSON boolean switch and a non-empty string UUID array.
401 ft.WKSPNotExistOrReleased Any target workspace does not exist, has been deleted, or is not active with status=0 Workspace does not exist or has been released Re-read the workspace list, correct the entire batch of targets, and retry.
500 ft.InternalServerError Database, cache, resource service, or unhandled parameter conversion exception Internal error Save the traceId and contact the administrator; query the configuration and the actual downstream state first. Do not directly regard a failure response as not saved, and do not blindly repeat creation or rotation.

Feedback

Is this page helpful?