콘텐츠로 이동

인시던트 AI 자동 분석 구성 일괄 설정



POST /api/v1/workspace/incidents/ai_analysis/batch_set

개요

인시던트 AI 자동 분석을 일괄 설정합니다.

호출 전 확인 및 사용 단계

먼저 워크스페이스 목록에서 모든 대상 활성 워크스페이스를 확인합니다. 중복 UUID는 한 번만 계산되며, 반환된 count는 중복 제거 후 요청된 워크스페이스 수이지 변경된 워크스페이스 수가 아닙니다. 이 작업은 인시던트 AI 자동 분석 구성만 설정하며, 워크스페이스 AI 마스터 스위치를 켜지 않고 과거 인시던트 재실행도 시작하지 않습니다. AI 기능을 사용해야 하는 경우 마스터 스위치와 인시던트 자동 분석 스위치를 각각 확인해야 합니다. 인시던트 구성이 없으면 해당 구성을 생성합니다.

요청 헤더

파라미터 이름 유형 필수 설명
X-Df-SVersion string 예시와 동일하게 유지해야 하며, 이를 생략하고 이 알고리즘을 계속 사용할 수는 없습니다.
예: v20240417
획득 또는 입력 방법: 이 페이지의 원본 경로 및 요청 본문 서명 알고리즘에 맞춰 입력합니다.
X-Df-Access-Key string Y 여기의 7개 항목은 모두 쓰기 작업이며 External 쓰기 권한이 필요합니다.
예: <external-access-key>
획득 또는 입력 방법: 사이트 관리자가 w 권한을 부여한 External API AK를 할당해야 하며, 워크스페이스 OpenAPI Key가 아닙니다.
X-Df-Nonce string Y 다시 전송할 때마다 이 값과 서명도 갱신합니다.
예: 97d275ee9f774315a7885ba7347acbd9
획득 또는 입력 방법: 요청마다 uuid.uuid4().hex를 다시 생성합니다.
X-Df-Signature string Y 대문자로 변환한 메서드, nonce, 원본 전체 경로, timestamp 및 원본 UTF-8 요청 본문을 공백으로 연결한 뒤 HMAC-SHA256 hex 다이제스트를 계산합니다.
예: <hmac-sha256-hex>
획득 또는 입력 방법: 함께 제공된 SK를 사용해 External API 서명 인증 및 아래 Python 템플릿에 따라 계산합니다.
X-Df-Timestamp string Y 예시의 고정 시간을 재사용할 수 없으며, 사이트 서명 유효 시간 범위 내에 있어야 합니다.
예: 1785427200
획득 또는 입력 방법: 전송 시 str(int(time.time()))로 현재 Unix 초를 생성합니다.

Body 요청 파라미터

파라미터 이름 유형 필수 설명
workspaceUUIDs[*] string 단일 활성 워크스페이스 UUID이며, 앞뒤 공백을 제거한 뒤 입력 순서를 유지한 중복 제거에 사용됩니다.
예: wksp_example001
획득 또는 입력 방법: 워크스페이스 목록의 content.data[].uuid에서 항목별로 가져옵니다.
enableAIAnalysis boolean Y 필수 JSON 불리언 값입니다. enableAI를 동시에 변경하지 않습니다.
null 허용: False
예: true
획득 또는 입력 방법: 비즈니스 목표에 따라 true로 켜고 false로 끄며, 문자열이 아닙니다.
workspaceUUIDs array Y 필수 비어 있지 않은 문자열 배열이며, 항목별로 앞뒤 공백을 제거하고 처음 나타난 순서로 중복 제거합니다. 워크스페이스 하나라도 유효하지 않으면 전체 배치가 먼저 실패합니다. 계정 UUID 또는 수집 Token을 입력하지 마십시오.
null 허용: False
예: ["wksp_example001"]
획득 또는 입력 방법: 워크스페이스 목록의 content.data[].uuid에서 대상 워크스페이스를 선택하며, 각 워크스페이스는 활성 status=0이어야 합니다.

파라미터 추가 설명

w 권한이 있는 사이트 수준 External API 자격 증명을 사용합니다. 인증 방식은 External API 서명 인증을 참조하십시오. 예시는 v20240417에 따라 서명을 계산하며, 서명과 전송에는 동일한 경로, Query 및 원본 요청 본문을 사용합니다. 모든 예시는 데모 값이므로 실행 전에 실제 대상으로 교체하십시오. 쓰기 요청이 타임아웃되거나 500이 발생하면 먼저 현재 상태를 조회하고 확인한 뒤 재시도 여부를 결정해야 합니다. 인시던트 구성과 AI 마스터 스위치는 독립적인 기능이므로, 이 구성을 활성화하더라도 매 인시던트에 대해 AI 분석이 반드시 수행되는 것은 아니며 마스터 스위치, 데이터 및 실행 조건에 따라 달라집니다.

요청 예시

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

# 대상 사이트 주소 및 관리자가 할당한 External API AK/SK로 교체합니다.
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'POST'
path = '/api/v1/workspace/incidents/ai_analysis/batch_set'
query = {}
data = {'workspaceUUIDs': ['wksp_example001'], 'enableAIAnalysis': 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"))

응답

HTTP 200, application/json, 통합 응답 래퍼입니다. 비즈니스 결과는 content에 있으며, External은 declaration을 자동으로 주입하지 않습니다. 워크스페이스 객체의 declaration은 자체 저장 필드입니다.

필드 유형 설명
content.workspaceUUIDs 문자열 배열 공백을 제거하고 입력 순서를 유지하며 중복 제거한 활성 워크스페이스 UUID입니다.
content.count integer 중복 제거 후 요청된 워크스페이스 수이며, 실제 변경 수가 아닙니다.
content.enableAIAnalysis boolean 이번에 모든 대상 워크스페이스에 설정한 스위치 값입니다.
{
  "code": 200,
  "content": {
    "workspaceUUIDs": [
      "wksp_example001"
    ],
    "count": 1,
    "enableAIAnalysis": true
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.

아래 표는 이 API의 비즈니스 검증 및 확인된 주요 오류 분기를 나열합니다. 다운스트림 서비스는 구체적인 오류 매핑에 따라 다른 4xx 오류를 반환할 수 있으며, 일반 5xx 및 알 수 없는 예외는 전역 처리되어 ft.InternalServerError를 반환합니다. 쓰기 요청은 현재 구성과 오류 content를 함께 확인하여 적용 여부를 판단해야 하며, HTTP 상태만으로 롤백을 추론할 수 없습니다.

HTTP 상태 errorCode 트리거 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 파라미터 파싱 실패 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정합니다.
400 ft.JsonFormatError JSON 최상위가 객체가 아님 일부 json 파일 형식 오류 파라미터 표에 따라 JSON 객체를 제출하고, 배열이나 null을 전체 요청 본문으로 사용하지 마십시오.
400 ft.ParamsValidateError 요청 비즈니스 검증에서 스위치가 불리언이 아니거나 UUID 목록이 비어 있거나 요소가 비어 있지 않은 문자열이 아닌 경우 발견 파라미터 검증 실패: {} JSON 불리언 스위치와 비어 있지 않은 문자열 UUID 배열을 사용합니다.
401 ft.WKSPNotExistOrReleased 대상 워크스페이스 중 하나라도 존재하지 않거나 삭제되었거나 활성 status=0이 아님 워크스페이스가 존재하지 않음/또는 해제됨 워크스페이스 목록을 다시 읽고 전체 배치 대상을 수정한 뒤 재시도합니다.
500 ft.InternalServerError 데이터베이스, 캐시, 리소스 서비스 또는 처리되지 않은 파라미터 변환 예외 내부 오류 traceId를 저장하고 관리자에게 문의하십시오. 먼저 구성 및 다운스트림 실제 상태를 조회해야 하며, 실패 응답을 곧바로 저장되지 않은 것으로 간주하거나 무작정 반복 생성 또는 교체하지 마십시오.

문서 평가

이 페이지가 도움이 되었나요?